References and the Blueprint Container

In the Blueprint programming model, you use the reference element to find services in the service registry, and the reference-list element to find multiple matching services.

The reference element is used to refer to a service in the OSGi service registry, and is independent of how that service was registered. For example, it can refer to the following services:

A Java™ bean that is declared in a service element in the Blueprint XML file of the bundle that provides the service; for more information, see Services and the Blueprint Container.
An enterprise bean that is specified in the Export-EJB header in the manifest file of the bundle that provides the service.
A service that is registered by making direct calls to the OSGi API.

The following Blueprint XML example code shows the accountRef reference that refers to an Account service. If a service that matches this reference is found in the service registry, the service is set on the accountClient bean through the account property.

<bean id="accountClient" class="...">    
   <property name="account" ref="accountRef" />
</bean>

<reference id="accountRef" interface="org.apache.aries.simple.Account" />

Reference dynamism

The object that is injected for a reference is a proxy to the service that is registered in the service registry. By using a proxy, the injected object remains the same when the availability of the backing service varies, or the backing service is replaced. If there are calls on a proxy that does not have a backing service, those calls block until a service becomes available or a timeout occurs. The default timeout in the Blueprint component is 300000 milliseconds (5 minutes). If a timeout occurs, a ServiceUnavailableException exception is created and the Blueprint Container is destroyed. See the following example code.

try {
   balance = account.getBalance();
} catch (ServiceUnavailableException e) {
   ...
}

You can change the timeout for each bundle by using directives in the Bundle-SymbolicName header in the bundle manifest, META-INF/MANIFEST.MF. The following example switches the timeout for a bundle off (the default is true).

Bundle-SymbolicName: org.apache.aries.simple.account; 
   blueprint.graceperiod:=false

The following example sets the timeout for a bundle to 10000 milliseconds (10 seconds).

Bundle-SymbolicName: org.apache.aries.simple.account; blueprint.timeout=10000;

You can set the timeout for an individual reference by using the timeout attribute. The following example XML code sets the timeout for the accountRef reference to 20000 milliseconds (20 seconds).

<reference id="accountRef" timeout="20000" 
   interface="org.apache.aries.simple.Account" />

For both a bundle and a reference, a timeout value of 0 means wait indefinitely for the reference to be satisfied.

Reference lists

You can use the reference-list element to find multiple matching services. The reference-list element provides a List object that contains the service proxy objects or ServiceReference objects, depending on the value of the member-type attribute (the default value is service-object). The List object that is provided is dynamic and expands or contracts when matching services are added or removed from the service registry. The List object is read-only and supports only a subset of the List API.

The proxies in a reference-list element target a specific service and do not have a timeout. If the backing service for a proxy becomes unavailable, a ServiceUnavailableException exception is created immediately.

The following Blueprint XML example code shows a reference-list that returns a list of service objects (proxies).

<reference-list id="accountRefs" member-type="service-object" 
   interface="org.apache.aries.simple.Account" />

The following Blueprint XML example code shows a reference-list that returns a list of ServiceReference objects.

<reference-list id="accountRefs" member-type="service-reference" 
   interface="org.apache.aries.simple.Account" />

Availability

By default, a service reference manager requires that at least one suitable service exists before initialization of the Blueprint Container can continue. That is, a service that matches the selection criteria of the reference or reference list must exist. To control this behavior, you use the availability attribute of the reference or reference-list element. The availability attribute can have the following values:

optional: The existence of a service that matches the selection criteria of the element during initialization of the Blueprint Container is optional. A service reference manager with optional availability is always considered satisfied, even if it does not have any matching services.
mandatory: At least one service that matches the selection criteria of the element during initialization of the Blueprint Container must exist. For a service reference manager with mandatory availability, if it has a matching service, it is considered satisfied. This is the default.

Initialization of the Blueprint Container is delayed until all service reference managers with mandatory availability are satisfied.

The availability attribute applies only during initialization of the Blueprint Container. After initialization, a service reference manager that has mandatory availability can become unsatisfied at any time, when services become unavailable or available again.

To change the default availability setting for all service reference managers in the Blueprint XML, you use the default-availability attribute on the Blueprint element.

The following Blueprint XML example code shows a reference manager that has mandatory availability.

<reference id="accountRef" timeout="20000" 
   interface="org.apache.aries.simple.Account"  
   availability="mandatory"/>

Service selection and proxies

The reference and reference-list managers share the following attributes that you can use to select services:

interface: Use the interface attribute to specify an interface class. The interface attribute is optional, but if set, it must specify an interface class. The interface class is used to select services or return service proxies.
For service selection, the interface class is used to select services from the service registry registered with that interface name. For service proxies, the proxies that the service reference managers return must implement all the methods that the interface class defines. If the interface attribute is not specified, the proxy behaves as though it implements an interface without any methods.
component-name: Use the component-name attribute to select services by adding an osgi.service.blueprint.compname=component_name expression to the selection filter.
filter: Use the filter attribute to select services by specifying the raw OSGi filter expression to add to the selection filter.

The three attributes combine to create one OSGi filter expression to use to select services.

For example, the selection filter for the reference in the following Blueprint XML example code is (&(objectClass=org.apache.aries.simple.Account) (osgi.service.blueprint.compname=myAccount)(mode=shared)).

<reference id="accountRef"              
   interface="org.apache.aries.simple.Account" 
   component-name="myAccount"
   filter="(mode=shared)"/>