+

Search Tips   |   Advanced Search

Dynamism and the Blueprint Container

In the Blueprint programming model, we can use registration listeners or reference listeners so that a bundle can have control when services become available.

For example, a bundle might have an optional service that it wants to start using when the service becomes available, and stop using when the service becomes unavailable. Use a reference listener so that the bundle is notified when this optional service becomes available or unavailable.

The service reference managers, that is, a reference manager or a reference-list manager, can have zero or more registration listeners, and zero or more reference listeners.


Registration listener

To specify a registration listener, use the registration-listener element, and use the registration-method and unregistration-method attributes specify the callback methods. We can specify the object that provides the callback methods as a reference to a top-level manager or we can use an inline declaration in the registration-listener element.

If the service implements the ServiceFactory interface, the registration and unregistration callback methods must have the following signature, where anyMethod represents an arbitrary method name. 

void anyMethod(ServiceFactory, Map)

If the service does not implement the ServiceFactory interface, the registration and unregistration callback methods must match the following signature. 

void anyMethod(? super T, Map)
The first argument is an instance of the service object. The type T must be able to be assigned from the type of the service object. The second argument provides the registration properties associated with the service.

If a registration listener has multiple overloaded methods for a callback, every method with a matching signature is invoked.

The following partial Java class and Blueprint XML example code shows a simple registration listener.

public class RegistrationListener {
   public void register(Account account, Map properties) {
      ...
   }
   public void unregister(Account account, Map properties) {
      ...
   }
}

<service id="serviceSix" ref="myAccount" auto-export="all-classes">
   <registration-listener 
      registration-method="register" unregistration-method="unregister">
      <bean class="org.apache.aries.RegistrationListener"/>         
   </registration-listener>
</service>


Reference listener

To specify a reference listener, we use the reference-listener element, and use the bind-method and unbind-method attributes to specify the callback methods. We can specify the object that provides the callback methods as a reference to a top-level manager or we can use an inline declaration in the reference-listener element.

The bind and unbind callback methods can have any of the following signatures, where anyMethod represents an arbitrary method name:

If a reference listener has multiple overloaded methods for a callback, every method with a matching signature is invoked.

For a reference-list manager, the listener callbacks are invoked each time a matching service is added or removed from the service registry. However, for a reference manager, the bind callback is not invoked when the manager is already bound to a service and a matching service with lower ranking is added to the service registry. Similarly, the unbind callback is not called if the service that the manager is bound to goes away and it is replaced immediately with another matching service.

If we use a reference manager and interact with stateful services, it is important to use reference listeners to track the backing services of the proxy so that we can manage the state of the service appropriately.

The following partial Java class and Blueprint XML example code shows a simple registration listener. The ReferenceListener class has two bind and one unbind callback methods, which are called when the services are bound and unbound from the service reference-list manager.

public class ReferenceListener {
   public void bind(ServiceReference reference) {
      ...
   }
   public void bind(Serializable service) {
      ...
   }
   public void unbind(ServiceReference reference) {
      ...
   }       
}

<reference-list id="serviceReferenceListTwo" 
   interface="org.apache.aries.simple.Account" availability="optional">
   <reference-listener bind-method="bind" unbind-method="unbind">
      <bean class="org.apache.aries.ReferenceListener"/>        
   </reference-listener>
</reference-list>


Related:

  • Blueprint bundles
  • Blueprint XML
  • Beans and the Blueprint Container
  • Services and the Blueprint Container
  • References and the Blueprint Container
  • Scopes and the Blueprint Container
  • Object values and the Blueprint Container
  • Object life cycles and the Blueprint Container
  • Resource references and the Blueprint Container
  • Type converters and the Blueprint Container
  • JNDI lookup for blueprint components
  • Developing an OSGi application
  • OSGi Service Platform Release 4 Version 4.2 Enterprise Specification
  • Building OSGi applications with the Blueprint Container specification




    File name: was311.html

    prettyPrint();