Component Configuration

Work in progress

Overview

OSGi provides a framework for individual software components to declare certain parameters to be configurable. This framework allows changing these parameters in-flight and tracks their values across system restart. However, this occurs only on the local container, which in ONOS's case is Apache Karaf. For this reason, ONOS provides a subsystem, which overlays the OSGi mechanism, but which manages the configurations in a distributed fashion across the entire ONOS cluster. This assures that all ONOS cluster instances are running using the same configuration and at the same time provides a convenient means to view the state of the configuration parameters.

This subsystem continues to use the OSGi mechanism to persistently track configurable parameters in the local instance context and to notify components when the parameters change. In this way the application components can continue to use the standard and well-understood OSGi configuration via ComponentContext. Furthermore, if components use the Apache Felix compile-time @Parameter annotation, ONOS build process generates a configuration catalog as a jar/bundle resource, which the component can register, allowing the ONOS administrator to see what parameters can be configured.

Component Code Example

To allow parameters to be configurable, components must first designate their fields using the @Parameter annotation as follows:

private static final int DEFAULT_MAX_EVENTS = 1000;

@Property(name = "maxEvents", intValue = DEFAULT_MAX_EVENTS,
        label = "Maximum number of events to accumulate")
private int maxEvents = DEFAULT_MAX_EVENTS;


private static final int DEFAULT_EMAIL = "onos-dev@onosproject.org";


@Property(name = "notificationEmail", value = DEFAULT_EMAIL,
          label = "Notification email address")
private String notificationEmail = DEFAULT_EMAIL;

In order to allow these parameters to be changed dynamically, a component should define a modified method, annotated using @Modify compile-time annotation as in this example:

@Modified
public boolean modified(ComponentContext context) {
    Dictionary<?, ?> properties = context.getProperties();


    String s = Tools.get(properties, "newMaxEvents");
    maxEvents = isNullOrEmpty(s) ? DEFAULT_MAX_EVENTS : Integer.parseInt(s.trim())

    s = Tools.get(properties, "notificationEmail");
    notificationEmail = isNullOrEmpty(s) ? DEFAULT_EMAIL : s;
    ...
}

Note: There is a slight anomaly in the OSGi framework where sometimes the parameters for fields of type other than String are contained in the map as their specific type, i.e. Integer, Boolean, and sometime the same value will be returned as a String. This is why the above example uses the recommended method for retrieving the property value via the Tools.get() method. This method forces all values to be returned as a String, allowing the component code in the modified method to be simpler and safer.

Finally, the component should register and unregister the configuration properties from its activate and deactivate methods:

@Reference(cardinality = ReferenceCardinality.MANDATORY_UNARY)
protected ComponentConfigService cfgService;


@Activate
public void activate(ComponentContext context) {
    cfgService.registerProperties(getClass());
    modified(context);
    ...
    log.info("Started");
}

@Deactivate
public void deactivate(ComponentContext context) {
    cfgService.unregisterProperties(getClass(), false);
    ...
    log.info("Stopped");
}

Maven Example