Dynamism and the Blueprint Container

In the Blueprint programming model, you 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. You can 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 listeners are objects that have callback methods invoked immediately after a service is registered, or immediately before a service is unregistered.
Reference listeners are objects that have callback methods invoked when a service is selected by the service reference manager, or a service is no longer used by the service reference manager.

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. You can specify the object that provides the callback methods as a reference to a top-level manager or you 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 that are 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, you use the reference-listener element, and use the bind-method and unbind-method attributes to specify the callback methods. You can specify the object that provides the callback methods as a reference to a top-level manager or you 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:

```
void anyMethod(ServiceReference)
```
The argument is a ServiceReference object of the service that is bound or unbound.
```
void anyMethod(? super T)
```
The argument is the service object proxy that is bound or unbound. The type T must be able to be assigned from the service object.
```
void anyMethod(? super T, Map)
```
The first argument is the service object proxy that is bound or unbound. The type T must be able to be assigned from the service object. The second argument provides the service properties that are associated with the service.

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 you 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 you 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>