A Managed Service Example

• Consider an application where you have the following bundle:
  • Counter: This bundle wishes to register a ManagedService, creating an instance of the Counter class based on a configuration provided by ConfigurationAdmin. The Counter object will be registered with the OSGi framework as a CounterService.
  While not shown, there would clearly be at least one other bundle in the application that imports the CounterService. It's even feasible for a bundles that imports this service to also register a ManagedService, making it also remotely configurable at runtime, but to keep things simple this has been omitted from this example.

• As the diagram shows, the configuration results in the creation of an inner-bundle. This allows SAT to support imported and exported service between configuration, as well as supporting LDAP filters for imported services.
  • The inner-bundle is created by the ManagedServiceBundleActivator and passed to the advisor as the IBundleActivationManager parameter.
  • The BundleContext for the IBundleActivationManager is identical to that of the bundle that registered the managed service.
  • It is worth noting that the interface IBundleActivationManager is what SAT uses internally as an implementation detail of the BaseBundleActivator. An inner-bundle really does behave like a regular SAT bundle activator for the configuration!
  • Providing the configuration with its own activation manager is what makes SAT's support for Managed Service bundles so powerful.
• The bundle activator for the Counter bundle is as follows:

public class Activator extends ManagedServiceBundleActivator {
  protected IManagedServiceAdvisor createAdvisor() {
    return new CounterManagedServiceAdvisor();
  }
}

• By subclassing ManagedServiceBundleActivator the activator is automatically registered with the OSGi framework as a ManagedService.
• The activator simply implements the createAdvisor() method to create and return an implementation of the IManagedServiceAdvisor interface that knows how to manage configuration updates from ConfigurationAdmin.
• The class BaseManagedServiceAdvisor provides an abstract implementation of the IManagedServiceAdvisor interface.
  • Subclassing BaseManagedServiceAdvisor is highly recommended since it provides a reasonable implementation for most methods.
  • Alternatively it is possible to implement the IManagedServiceAdvisor interface from scratch, but needing to do this should be rare.
• The following methods are not implemented by BaseManagedServiceAdvisor and must be implemented by concrete subclasses.
  • Object create(String, Dictionary, IBundleActivationManager);
  • Object update(String, Object, Dictionary, Dictionary, IBundleActivationManager);
• Here is the Counter bundle's subclass of BaseManagedServiceAdvisor:

        
public class CounterManagedServiceAdvisor extends BaseManagedServiceAdvisor {
  public Object create(String pid, Dictionary properties, IBundleActivationManager manager) {
    Counter counter = new Counter();
    int value = getValue(properties);
    counter.setValue(value);
    LogUtility.logInfo(pid, "Created Counter: " + counter);
    manager.addExportedService(CounterService.SERVICE_NAME, counter, null);
    return counter;
  }

  public void destroy(String pid, Object object, Dictionary properties, IBundleActivationManager manager) {
    LogUtility.logInfo(pid, "Destroyed Counter: " + object);
  }

  private int getValue(Dictionary properties) {
    Integer wrapper = (Integer) properties.get(CounterService.VALUE_PROPERTY_KEY);
    int value = wrapper != null ? wrapper.intValue() : 0;
    return value;
  }
	
  public Object update(String pid, Object object, Dictionary oldProperties, Dictionary properties, IBundleActivationManager manager) {
    int oldValue = getValue(oldProperties);
    int newValue = getValue(properties);
		
    if (oldValue != newValue) {
      Counter counter = (Counter) object;
      counter.setValue(newValue);
      LogUtility.logInfo(pid, "Updated Counter: " + counter);
      Dictionary serviceProperties = manager.getExportedServiceProperties(CounterService.SERVICE_NAME, counter);
      serviceProperties.put(CounterService.VALUE_PROPERTY_KEY, new Integer(newValue));
      manager.setExportedServiceProperties(CounterService.SERVICE_NAME, counter, serviceProperties);
    }
		
    return object;
  }
}

• The create method is called when the configuration has been created by ConfigurationAdmin.
  • The first parameter is the unique persistent ID, for the configuration. This persistent ID is passed to every method defined by the IManagedServiceAdvisor interface, even though it really is just an implementation detail of ConfigurationAdmin and ManageService objects. The persistent ID is useful for debugging and logging messages.
  • The create method simply creates an instance of the Counter class and sets its value to the value provided by the properties. The private method getValue(Dictionary) is used to get the value.
  • The Counter is then registered with the OSGi framework as a CounterService.
  • It is very important to notice that the call to addExportedService(String, Object, Dictionary), that registers the service with the OSGi framework, is done through the IBundleActivationManager parameter. Remember the IBundleActivationManager is the inner-bundle for the configuration.
  • Finally the created Counter object is returned. The object returned by this method is cached by SAT. Later when the configuration is updated the object is passed back to the advisor.
• The update method is called when the configuration's properties have been changed by ConfigurationAdmin.
  • The update method queries the old and new properties for the value entries and compares them. This comparison is not strictly needed since value is the only property of the configuration. But nevertheless, this is exactly what should be done to identify which properties need updating.
  • The object returned by the create method is passed back into the update method. Since it is typed as an Object it must be cast back to a Counter before having its setValue(int) method called.
  • Once the Counter object has been updated, its registered exported properties are retrieved using the method getExportedServiceProperties(String, Object), updated and set using the method setExportedServiceProperties(String, Object, Dictionary). Again, it is important to note that this is all done via the IBundleActivationManager parameter.
  • Finally the updated Counter object is returned. Just as with the create method, the object returned by this method will be cached by the advisor. While typically this is the same object as passed to the update method, this is not necessarily the case. Returning a different object will cause the previously cached object to be replaced.

---

|

---

Copyright © 2001, 2008 IBM Corporation and others. All Rights Reserved.