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 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" />
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.
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" />
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”/>
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.
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)”/>