## Chapter 9. The Service Registry

The OSGi service registry enables a bundle to publish objects to a shared registry, advertised via a given set of Java interfaces. Published services also have service properties associated with them in the registry. The registry is a crucial feature of OSGi, facilitating decoupling between bundles by promoting a dynamic collaborative model based on a service-oriented paradigm (publish/find/bind).

Gemini Blueprint integrates tightly with the service registry, allowing clients to publish, find and bind services in a POJO-friendly manner, without coupling themselves to the OSGi API.

By using the `osgi` namespace for Spring (see Appendix F, Gemini Blueprint Schema) one can be indicate what Spring beans to export as OSGi services (and how) and to define the criteria and the manner in which services available in the OSGi registry are imported as beans.

Just like the rest of the namespaces, the `osgi` namespace can be embedded or nested inside another top-level namespace (typically the Spring `beans` namespace) or be made the default namespace.

The following example shows the use of the `osgi` namespace within the familiar Spring beans element:

    <?xml version="1.0" encoding="UTF-8"?>
    <beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:osgi="http://www.eclipse.org/gemini/blueprint/schema/blueprint"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans.xsd
           http://www.eclipse.org/gemini/blueprint/schema/blueprint
           http://www.eclipse.org/gemini/blueprint/schema/blueprint/gemini-blueprint.xsd">

        <osgi:service id="simpleServiceOsgi" ref="simpleService"
          interface="org.xyz.MyService" />
    </beans>

| Use Spring Framework `beans` schema as the default namespace.
| Import Gemini Blueprint schema and associate a prefix with its namespace (`osgi` in this example).
| Make sure to import Spring beans schema version 3.0 or higher.
| Use Gemini Blueprint elements using the declared namespace prefix (in this example `osgi`).

Spring DM users can still use its namespace which is still supported by the Gemini Blueprint bundles. So the above configuration becomes:

    <?xml version="1.0" encoding="UTF-8"?>
    <beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:osgi="http://www.springframework.org/schema/osgi"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans.xsd
           http://www.springframework.org/schema/osgi
           http://www.springframework.org/schema/osgi/spring-osgi.xsd">

        <osgi:service id="simpleServiceOsgi" ref="simpleService"
          interface="org.xyz.MyService" />
    </beans>

| Use Spring Framework `beans` schema as the default namespace.
| Import Gemini Blueprint schema and associate a prefix with its namespace (`osgi` in this example).
| Make sure to import Spring beans schema version 3.0.
| Use Gemini Blueprint elements using the declared namespace prefix (in this example `osgi`).

Through-out this documentation both the Gemini Blueprint and Spring DM namespaces will be used interchangeably - in fact, at a close look one will notice the two are identical (except for the schema location declaration). As much as possible, new apps should use the Gemini Blueprint namespace as the Spring DM ones while supported, are being deprecated.

Using the OSGi namespace as a top-level namespace, the same service would be declared as follows:

    <?xml version="1.0" encoding="UTF-8"?>
    <beans:beans
       xmlns="http://www.eclipse.org/gemini/blueprint/schema/blueprint"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:beans="http://www.springframework.org/schema/beans"
       xsi:schemaLocation="http://www.eclipse.org/gemini/blueprint/schema/blueprint
           http://www.eclipse.org/gemini/blueprint/schema/blueprint/gemini-blueprint.xsd
           http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans.xsd">

        <service id="simpleServiceOsgi" ref="simpleService"
           interface="org.xyz.MyService" />

    </beans:beans>

| `beans` root element has to be prefixed with Spring Framework beans schema prefix (`beans` in this example).
| Use Gemini Blueprint schema as the default namespace.
| Import Spring Framework `beans` schema and associate a prefix with its namespace (`beans` in this example).
| Make sure to import Spring beans schema version 2.5.
| Use Gemini Blueprint elements without any prefix.

Using the OSGi namespace as a top-level namespace is particularly convenient when following the configuration recommendation from the previous section, to use a dedicated configuration file for all OSGi-related declarations.

## 9.1. Exporting A Spring Bean As An OSGi Service

The `service` element is used to define a bean representing an exported OSGi service. There are no requirements for the class or object being exported - practically any bean can be exported. At a minimum you must specify the bean to be exported, and the service interface that the service advertises.

| Note
The publication interface is used by service consumers, to identify the service. A service instance must implement the interface - specifying a non-implemented interface results in an error. The term interface is used in an abstract form; in practice any Java interface or class, implemented or extended by the service instance can be specified.

For example, the declaration

    <service ref="beanToPublish" interface="com.xyz.MessageService"/>

exports the bean with name `beanToPublish` with interface `com.xyz.MessageService`. The published service will have a service property with the name `org.eclipse.gemini.blueprint.bean.name` set to the name of the target bean being registered (`beanToPublish` in this case).

As an alternative to exporting a named bean, the bean to be exported to the service registry may be defined as an anonymous inner bean of the service element. Typically the top-level namespace would be the `beans` namespace when using this style:

    <osgi:service interface="com.xyz.MessageService">
      <bean class="SomeClass">
         ...
      </bean>
    </osgi:service>

### 9.1.1. Using The Service Registration

Each `service` declaration, provides control access to the exported service. The declaration returns an element of type `org.osgi.framework.ServiceRegistration` which can be used to read or even modify the properties published for the OSGi service. Since DM 2.X, the definition has been aligned with the Blueprint spec and unregistration of the service is not possible any more (an exception is thrown if the `unregister` is called). Additionally, the returned service registration will track the service being registered (if multiple registration occur, these will be reflected in the returned registration object). See Section 9.2.1.2, “Relationship Between The Service Exporter And Service Importer” for more information on when registration/unregistration of exported services can occur.

To use the service registration, simply inject the service bean definition into the relevant class; the example below shows one way of updating the service properties from Java:

    <service id="myServiceRegistration" ref="beanToPublish"
         interface="com.xyz.MessageService"/>

    <bean id="propUpdater" class="com.xyz.ServicePropertiesUpdater">
       <property name="serviceRegistration ref="myServiceRegistration"/>
    </bean>

Where `ServicePropertiesUpdater` can have the following definition:

    public class ServicePropertiesUpdater implements BeanNameAware {

    	private ServiceRegistration serviceRegistration;
    	private String beanName;

    	public void setServiceRegistration(ServiceRegistration serviceRegistration) {
    		this.serviceRegistration = serviceRegistration;
    	}

    	public void setBeanName(String beanName) {
    		this.beanName = beanName;
    	}

    	public void update() {
    		ServiceReference reference = serviceRegistration.getReference();
    		// get current properties
    		Dictionary dictionary = OsgiServiceReferenceUtils.getServiceProperties(reference);
    		dictionary.put("last-update", new Date());
    		dictionary.put("updated-by", beanName);
    		dictionary.put("user.name", System.getProperties().getProperty("java.version"));
    		// update properties
    		serviceRegistration.setProperties(dictionary);
    	}
    }

Each time the update() method is called, the service properties are retrived, new ones are added and finally the service registration updated.

### 9.1.2. `org.osgi.framework.ServiceFactory` Support

OSGi Service Platform Core Specification allows services not just to be registered directly, but also to be created on demand, through the `org.osgi.framework.ServiceFactory` interface (see section 5.6). Gemini Blueprint/Spring DM recognizes this OSGi interface and honours its contract, by forwarding each new bundle request, to the backing bean implementing the aforementioned interface.

As an alternative to implementing the OSGi API, one can use the `bundle` scope, introduced by Gemini Blueprint/Spring DM which offers a instance-per-bundle contract (see Section 7.5, “Bundle Scope” for more information). To declare a bean with `bundle` scope simply use the `scope` attribute of the `bean` element:

    <osgi:service ref="beanToBeExported" interface="com.xyz.MessageService"/>

    <bean id="beanToBeExported" scope="bundle" class="com.xyz.MessageServiceImpl"/>

### 9.1.3. Controlling The Set Of Advertised Service Interfaces For An Exported Service

The OSGi Service Platform Core Specification defines the term service interface to represent the specification of a service's public methods. Typically this will be a Java interface, but the specification also supports registering service objects under a class name, so the phrase service interface can be interpreted as referring to either an interface or a class.

There are several options for specifying the service interface(s) under which the exported service is registered. The simplest mechanism, shown above, is to use the `interface` attribute to specify a fully-qualified interface name. To register a service under multiple interfaces the nested `interfaces` element can be used in place of the `interface` attribute.

    <osgi:service ref="beanToBeExported">
      <osgi:interfaces>
         <value>com.xyz.MessageService</value>
         <value>com.xyz.MarkerInterface</value>
      </osgi:interfaces>
    </osgi:service>

It is illegal to use both `interface` attribute and `interfaces` element at the same time - use only one of them.

#### 9.1.3.1. Detecting The Advertised Interfaces At Runtime

Using the `auto-export` attribute you can avoid the need to explicitly declare the service interfaces at all by analyzing the object class hierarchy and its interfaces.

The `auto-export` attribute can have one of four values:

- `disabled` : the default value; no auto-detected of service interfaces is undertaken and the `interface` attribute or `interfaces` element must be used instead.

- `interfaces` : the service will be registered using all of the Java interface types implemented by the bean to be exported

- `class-hierarchy` : the service will be registered using the exported bean's implementation type and super-types

- `all-classes` : the service will be registered using the exported bean's implementation type and super-types plus all interfaces implemented by the bean.

`auto-export` and `interface(s)` option are not exclusive; both can be used at the same time for fine grained control over the advertised interfaces if there is such a need. However, the former option should be enough for most cases.

For example, to automatically register a bean under all of the interfaces that it supports you would declare:

    <service ref="beanToBeExported" auto-export="interfaces"/>

Given the interface hierarchy:

    public interface SuperInterface {}

    public interface SubInterface extends SuperInterface {}

then a service registered as supporting the `SubInterface` interface is not considered a match in OSGi when a lookup is done for services supporting the `SuperInterface` interface. For this reason it is a best practice to export all interfaces supported by the service being registered explicitly, using either the `interfaces` element or `auto-export="interfaces"`.

### 9.1.4. Controlling The Set Of Advertised Properties For An Exported Service

As previously described, an exported service is always registered with the service property `org.eclipse.gemini.blueprint.bean.name` set to the name of the bean being exported. Since DM 2.x, the bean name is also published under `osgi.service.blueprint.compname` (introduced by the OSGi 4.2 Blueprint spec). Additional service properties can be specified using the nested `service-properties` element. The `service-properties` element contains key-value pairs to be included in the advertised properties of the service. The key must be a string value, and the value must be a type recognized by OSGi Filters. See section 5.5 of the OSGi Service Platform Core Specification for details of how property values are matched against filter expressions.

The `service-properties` element must contain at least one nested `entry` element from the Spring beans namespace. For example:

    <service ref="beanToBeExported" interface="com.xyz.MyServiceInterface">
      <service-properties>
        <beans:entry key="myOtherKey" value="aStringValue"/>
        <beans:entry key="aThirdKey" value-ref="beanToExposeAsProperty"/>
      </service-properties>
    </service>

Non-String values can be specified by enforcing the value type. Consider the publication of an OSGi event consumer (`org.osgi.service.event.EventHandler`) that needs to specify the topics it follows as an array under `event.topics` property. Below are a list of configuration on how this can be achieved:

    <osgi:service
         id="eventMonitorService"
         ref="someBean"
         interface="org.osgi.service.event.EventHandler">
            <osgi:service-properties value-type="java.lang.String[]">
                <entry key="event.topics" value="eventQueue"/>
            </osgi:service-properties>
    </osgi:service>

| Specify an array type for all the values declared inside the `service-properties` element.

    <osgi:service
         id="eventMonitorService"
         ref="someBean"
         interface="org.osgi.service.event.EventHandler">
            <osgi:service-properties>
                <entry key="event.topics">
                    <value type="java.lang.String[]">eventQueue</value>
                </entry>
        	</osgi:service-properties>
    </osgi:service>

| Indicate the value type just for this particular value.

    <osgi:service
         id="eventMonitorService"
         ref="someBean"
         interface="org.osgi.service.event.EventHandler">
            <osgi:service-properties>
                <entry key="event.topics">
                    <array value-type="java.lang.String">
                        <value>eventQueue</value>
                    </array>
                </entry>
            </osgi:service-properties>
    </osgi:service>

| Use Spring 3.x `<array>` element to create an nested array on the fly.

The Gemini Blueprint roadmap includes support for exporting properties registered in the OSGi Configuration Administration service as properties of the registered service. See Appendix D, Roadmap for more details.

### 9.1.5. The depends-on Attribute

Spring will manage explicit dependencies of a service element, ensuring for example that the bean to be exported as a service is fully constructed and configured before exporting it. If a service has implicit dependencies on other components (including other service elements) that must be fully initialized before the service can be exported, then the optional `depends-on` attribute can be used to express these dependencies.

    <service ref="beanToBeExported" interface="com.xyz.MyServiceInterface"
         depends-on="myOtherComponent"/>

### 9.1.6. The context-class-loader Attribute

The OSGi Service Platform Core Specification (most current version is 4.x at time of writing) does not specify what types and resources are visible through the context class loader when an operation is invoked on a service obtained via the service registry. Since some services may use libraries that make certain assumptions about the context class loader, Gemini Blueprint enables you to explicitly control the context class loader during service execution. This is achieved using the option `context-class-loader` attribute of the service element.

The permissible values for the `context-class-loader` attribute are `unmanaged` (the default) and `service-provider`. When the `service-provider` value is specified, Spring Dynamic Modules ensures that the context class loader can see all of the resources on the class path of the bundle exporting the service.

When setting `context-class-loader` to `service-provider`, the service object will be proxied to handle the class loader. If the service advertises any concrete class then CGLIB library is required .

### 9.1.7. The `ranking` Attribute

When registering a service with the service registry, you may optionally specify a service ranking (see section 5.2.5 of the OSGi Service Platform Core Specification). When a bundle looks up a service in the service registry, given two or more matching services the one with the highest ranking will be returned. The default ranking value is zero. To explicitly specify a ranking value for the registered service, use the optional `ranking` attribute.

    <service ref="beanToBeExported" interface="com.xyz.MyServiceInterface"
      ranking="9"/>

### 9.1.8. The `cache-target` Attribute

By default, services exported are being retrieved from the container each time they are requested. This allows scoped beans to behave correctly depending on the context available when the request is being performed. However, there are cases when the target bean (the entity being exported) needs to be cached no matter its scope. The Blueprint spec for example requires this behaviour for all exported services.

To accommodate both cases one, Gemini Blueprint 1.0/Spring DM 2.0 introduces a new attribute, `cache-target` which, as the name suggests, enables the caching of the exported bean. The instance of the bean retrieved, for the first service registration is cached internally by the exporter which will later reuse it.

    <service ref="beanToBeExported" interface="com.xyz.MyServiceInterface"
      cache-target="true"/>

### 9.1.9. `service` Element Attributes

As a summary, the following table lists the attributes names, possible values and a short description for each of them.

Table 9.1. OSGi <service> attributes

Name | Values | Description
--- | --- | ---
interface | fully qualified class name (such as `java.lang.Thread`) | the fully qualified name of the class under which the object will be exported
ref | any bean name | Reference to the named bean to be exported as a service in the service registry.
context-class-loader | unmanaged | service-provider | Defines how the context class loader will be managed when an operation is invoked on the exported service. The default value is `unmanaged` which means that no management of the context class loader is attempted. A value of `service-provider` guarantees that the context class loader will have visibility of all the resources on the class path of bundle exporting the service.
auto-export | disabled | interfaces | class-hierarchy | all-classes | Enables Spring to automatically manage the set of service interfaces advertised for the service. By default this facility is `disabled`. A value of `interfaces` advertises all of the Java interfaces supported by the exported service. A value of `class-hierarchy` advertises all the Java classes in the hierarchy of the exported service. A value of `all-classes` advertises all Java interfaces and classes.
ranking | any integer value | Specify the service ranking to be used when advertising the service. Default value is 0.
cache-target | true | false | Specify whether the bean exported as an OSGi service is cached (on first registration) or not. Default value is `false`

### 9.1.10. Service Registration And Unregistration Lifecycle

The service defined by a `service` element is registered with the OSGi service registry when the application context is first created. It will be unregistered automatically when the bundle is stopped and the application context is disposed. Additionally, based on the mandatory service import availability, the service can be unregistered and registered at runtime (see ???).

If you need to take some action when a service is unregistered because its dependencies are not satisfied (or when it is registered), then you can define a listener bean using the nested `registration-listener` element.

The declaration of a registration listener must use either the `ref` attribute to refer to a top-level bean definition, or declare an anonymous listener bean inline. For example:

    <service ref="beanToBeExported" interface="SomeInterface">
      <registration-listener ref="myListener"
        registration-method="serviceRegistered"
        unregistration-method="serviceUnregistered"/>
      <registration-listener
         registration-method="register">
         <bean class="SomeListenerClass"/>
      </registration-listener>
    </service>

| Listener declaration referring to a top-level bean declaration.
| Indicate the `registration` and `unregistration` methods.
| Declare only a `registration` custom method for this listener.
| Nested listener bean declaration.

The optional `registration-method` and `unregistration-method` attributes specify the names of the methods defined on the listener bean that are to be invoked during registration and unregistration. A registration and unregistration callback methods must have a signature matching one of the following formats:

    public void anyMethodName(ServiceType serviceInstance, Map serviceProperties);

    public void anyMethodName(ServiceType serviceInstance, Dictionary serviceProperties);

where `ServiceType` can be any type compatible with the exported service interface of the service.

The register callback is invoked when the service is initially registered at startup, and whenever it is subsequently re-registered. The unregister callback is invoked during the service unregistration process, no matter the cause (such as the owning bundle stopping).

Gemini Blueprint/Spring DM will use the declared `ServiceType` argument type and invoke the registration/unregistration method only when a service of a compatible type will be registered/unregistered.

`serviceProperties` represents a map holding all the properties of the registered/unregistered service. To preserve compatibility with the OSGi specification this argument can be cast, if needed, to a `java.util.Dictionary`.

#### 9.1.10.1. Using `OsgiServiceRegistrationListener` Interface

While we discourage, it is possible to implement a Gemini Blueprint/Spring DM specific interface, namely `org.eclipse.gemini.blueprint.service.exporter.OsgiServiceRegistrationListener` which avoids the need to declare the `registration-method` and `unregistration-method`. However, by implementing `OsgiServiceRegistrationListener`, your code becomes Gemini Blueprint/Spring DM aware (which goes against the POJO philosophy).

It is possible for a listener to implement `OsgiServiceRegistrationListener` interface and declare custom methods. In this case, the Gemini Blueprint/Spring DM interface methods will be called first, followed by the custom methods.

#### 9.1.10.2. Blueprint `service` Comparison

The Blueprint Container offers a `service` element, identical in functionality with the one in Gemini Blueprint/Spring DM. In most cases, the configuration should be identical. Below is a summary of the configuration options available in Gemini Blueprint/Spring DM and Blueprint:

Table 9.2. Spring DM / Blueprint `<service>` Configuration Comparison

Gemini Blueprint/Spring DM | Blueprint
--- | ---
interface | interface
ref | ref
auto-export | auto-export
ranking | ranking
context-class-loader | -
cache-target | - (caching is always enabled)

Since the `registration-listener` declaration is identical in declaration and functionality between Blueprint and Gemini Blueprint/Spring DM, this section does not mention it.

## 9.2. Defining References To OSGi Services

To use services, clients need to look for them inside the OSGi service registry. If found, the platform returns a reference which can be used to get the actual service instance. Consumers should return the service instance as soon as possible and not hold on to it since the service provider can unpublish the service at any point. Since there is no mechanism in Java to force such cleanup, the OSGi specification uses the service references and the aforementioned protocol to decouple service providers from service consumers. Please see chapter 5, the Service Layer inside the OSGi Core spec for an in-depth discussion.

Gemini Blueprint facilitates the consumption of OSGi services by taking care of not just of the retrieval of service references and instances but also considering the service dynamics. With Gemini Blueprint/Spring DM, imported OSGi services become Spring beans which can be injected, as usual, into other application components. The service lookup is made using the service interface type that the service is required to support, plus an optional filter expression that matches against the service properties published in the registry. The service instance retrieval is done on demand, on the first request. Once the service becomes unavailable, Gemini Blueprint/Spring DM automatically unregisters the service to avoid using stale references.

As a consumer, one can find zero, one or multiple services matching the desired description. In most scenarios, a single matching service is all that is needed; for those the `reference` element defines a reference to a single service that meets the required specification. In other cases, especially when using the OSGi whiteboard pattern, references to all available matching services are required. Gemini Blueprint supports the management of this group of references as either a `List` or a `Set` collection.

### 9.2.1. Imported Service Availability

Due to the dynamic nature of OSGi, services can come and go, be available or unavailable at certain points in time. Depending on the type of service, this can have a negative impact on the consumers. Gemini Blueprint/Spring DM alleviates this problem by introducing the notion of `availability` (formerly known as `cardinality`) which indicates whether an imported service is `mandatory` or `optional`.

As the name implies, a `mandatory` service implies a crucial application dependency: the service is required and its presence can heavily impact the application, in a negative way.

An `optional` service means just the opposite. The service is tracked and bound (if present), just like a `mandatory` reference, but its presence is not required. It is fine, from an application perspective if the service is not available - its existence (or lack of) does not impact the application functionality.

As an example, an application could have a `mandatory` dependency on a `DataSource` and an `optional` one for a logging service: the application can run fine if it cannot log (it does not impact the runtime) but it fails if the backing database is not available.

In Gemini Blueprint/Spring DM, a `mandatory` service import that is unsatisfied (there are no services matching the description) can either prevent an application context from starting up or, if already started, cause the unregistration of the exported services dependent on it.

#### 9.2.1.1. Mandatory Services and Application Startup

The availability of a service impacts the startup of an Spring-powered application and the publication of any exported services that depend on it. As mentioned in Section 7.2.1, “Mandatory Service Dependencies”, a SpringDM application will not start unless all `mandatory` services are available, at the same time. Before initializing the context, Gemini Blueprint/Spring DM discovers all the `mandatory` service declarations and waits for a period of time (5 minutes by default unless otherwise specified by each bundle - see the `timeout` directive in Section 8.1, “Bundle Format And Manifest Headers”) for all imports to be satisfied, at the same time. If the timeout occurs, the application initialization fails (since the required or mandatory services are not available) or succeeds, meaning the application context is being initialized.

This way, the framework prevents the application from starting up only to fail since its required services are unavailable. This feature avoids the need for ordering the bundle startup sequence as the configuration already acts as a service barrier blueprint: no matter the order of the services started, on whether they come and go, only when all of them are present, will the context initialization commence.

| Note
The fact that an application has mandatory service references, gives no guarantee that a valid service object is available when the service reference is used, since services can get unregistered at any time. Gemini Blueprint/Spring DM guarantees that all the mandatory services were present, at the same time, before the application was started but it cannot prevent or guarantee that this services will not be disappear during the application life span.

| Warning
It is an error to declare a mandatory reference to a service that is also exported by the same bundle, this behaviour can cause application context creation to fail through either deadlock or timeout.

#### 9.2.1.2. Relationship Between The Service Exporter And Service Importer

An exported service may depend, either directly or indirectly, on other (imported) services in order to perform its function. If one of these services is marked as a mandatory dependency and the dependency can no longer be satisfied (because the backing service has gone away and there is no suitable replacement available), then the exported service that depends on it will be automatically unregistered from the service registry - meaning that it is no longer available to clients. If the mandatory dependency becomes satisfied once more (by registration of a suitable service), then the exported service will be re-registered in the service registry.

This automatic publication management ensures that only when the exported service can work reliable, it is made available for potential OSGi clients. This behaviour takes advantage of the OSGi dynamic nature allowing an application to cope with the ongoing changing without being restarted.

This automatic unregistering and re-registering of exported services based on the availability of mandatory dependencies only takes into account declarative dependencies. If exported service `S` depends on bean `A`, which in turn depends on mandatory imported service `M`, and these dependencies are explicit in the Spring configuration file as per the example below, then when `M` becomes unsatisfied `S` will be unregistered. When `M` becomes satisfied again, `S` will be re-registered.

    <osgi:service id="S" ref="A" interface="SomeInterface"/>

    <bean id="A" class="SomeImplementation">
       <property name="helperService" ref="M"/>
    </bean>

    <!-- the reference element is used to refer to a service
         in the service registry -->
    <osgi:reference id="M" interface="HelperService" availability="mandatory"/>

If however the dependency from `A` on `M` is not established through configuration as shown above, but instead at runtime through for example passing a reference to `M` to `A` without any involvement from the Spring container, then Gemini Blueprint will not track this dependency.

### 9.2.2. Referencing An Individual Service

The `reference` element is used to define a reference to a service in the service registry.

Since there can be multiple service matching a given description, the service returned is the service that would be returned by a call to `BundleContext.getServiceReference`. This means that the service with the highest ranking will be returned, or if there is a tie in ranking, the service with the lowest service id (the service registered first with the framework) is returned (please see Section 5 from the OSGi spec for more information on the service selection algorithm).

#### 9.2.2.1. Controlling The Set Of Advertised Interfaces For The Imported Service

The `interface` attribute identifies the service interface that a matching service must implement. For example, the following declaration creates a bean `messageService`, which is backed by the service returned from the service registry when querying it for a service offering the `MessageService` interface.

    <reference id="messageService" interface="com.xyz.MessageService"/>

Just like the `service` declaration, when specifying multiple interfaces, use the nested `interfaces` element instead of `interface` attribute:

    <osgi:reference id="importedOsgiService">
      <osgi:interfaces>
         <value>com.xyz.MessageService</value>
         <value>com.xyz.MarkerInterface</value>
      </osgi:interfaces>
    </osgi:reference>

It is illegal to use both `interface` attribute and `interfaces` element at the same time - use only one of them.

The bean defined by reference element implements all of the advertised interfaces of the service that are visible to the bundle (called greedy proxying). If the registered service interfaces include Java class types (as opposed to interface types) then support for these types is subject to the restrictions of Spring's AOP implementation (see the Spring Reference Guide). In short, if the specified interfaces are classes (rather then interfaces), then `cglib` library must be available, and `final` methods are not supported.

#### 9.2.2.2. The `filter` Attribute

The optional `filter` attribute can be used to specify an OSGi filter expression and constrains the service registry lookup to only those services that match the given filter.

For example:

    <reference id="asyncMessageService" interface="com.xyz.MessageService"
      filter="(asynchronous-delivery=true)"/>

will match only OSGi services that advertise `MessageService` interface and have the property named `asynchronous-delivery` set to value `true`.

#### 9.2.2.3. The `bean-name` Attribute

The `bean-name` attribute is a convenient short-cut for specifying a filter expression that matches on the `bean-name` property automatically set when exporting a bean using the `service` element (see Section 9.1, “Exporting A Spring Bean As An OSGi Service”).

Consider the following exporter/importer declarations:

    <bean id="messageServiceBean" scope="bundle" class="com.xyz.MessageServiceImpl"/>
    <!-- service exporter -->
    <osgi:service id="messageServiceExporter" ref="messageServiceBean" interface="com.xyz.MessageService"/>

    <osgi:reference id="messageService" interface="com.xyz.MessageService"
       bean-name="messageServiceBean"/>

| the name used with `bean-name` attribute

will match only OSGi services that advertise `MessageService` interface and have the property named `org.eclipse.gemini.blueprint.bean.name` set to value `messageServiceBean`. In short, this means finding all Gemini Blueprint/Spring DM exported beans that implement interface `MessageService` and are named `messageServiceBean`.

#### 9.2.2.4. The `availability` Attribute

The `availability` attribute is used to specify whether or not a matching service is required at all times. An `mandatory` availability (the default) indicates that a matching service must always be present. A value of `optional` indicates that a matching service is not required at all times (see Section 9.2.2.9, “`reference` And OSGi Service Dynamics” for more details). The differences in behaviour between `mandatory` and `optional` services are explained at length in Section 9.2.1, “Imported Service Availability”.

#### 9.2.2.5. The `depends-on` Attribute

The `depends-on` attribute is used to specify that the service reference should not be looked up in the service registry until the named dependent bean has been instantiated.

#### 9.2.2.6. The `context-class-loader` Attribute

The OSGi Service Platform Core Specification (latest version is 4.1 at time of writing) does not specify what types and resources are visible through the context class loader when an operation is invoked on a service obtained via the service registry. Since some services may use libraries that make certain assumptions about the context class loader, Gemini Blueprint enables you to explicitly control the context class loader during service invocation. This is achieved using the option `context-class-loader` attribute of the `reference` element.

The permissible values for the `context-class-loader` attribute are:

- `client` - during the service invocation, the context class loader is guaranteed to be able to see types on the classpath of the invoking bundle. This is the default option.

- `service-provider` - during the service invocation, the context class loader is guaranteed to be able to see types on the classpath of the bundle exporting the service.

- `unmanaged` - no context class loader management will occur during the service invocation

#### 9.2.2.7. The `sticky` Attribute

Newly introduced in DM 2.x, the `sticky` attribute specifies whether an importer will use a backing service until it becomes unavailable or whether it will consider other better candidates (defined as services matching the importer criteria but with a higher ranking or a lower service id) that might appear. In Spring DM 1.x, the importer would always select the best service available at any point in time. Thus, if a service with a higher ranking id becomes available, the proxy would automatically bind to it. In highly dynamic environments, this lack of service affinity becomes problematic so in DM 2.x/Gemini Blueprint, the behaviour has changed (aligning itself with the Blueprint spec). Thus, service importers become `sticky` by default meaning that a proxy will use the bound backing service until it becomes unavailable, ignoring any other service updates. Only when the backing service goes down, the proxy will look for a replacement selecting the best candidate at that point in time. To revert to the Spring DM 1.x behaviour, mark the importers as being non-sticky.

#### 9.2.2.8. `reference` Element Attributes

As a summary, the following table lists the `reference` element attributes names, possible values and a short description for each of them.

Table 9.3. OSGi <reference> attributes

Name | Values | Description
--- | --- | ---
interface | fully qualified class name (such as `java.lang.Thread`) | The fully qualified name of the class under which the object will be exported.
filter | OSGi filter expression (such as `((asynchronous-delivery=true)`) | OSGi filter expression that is used to constrain the set of matching services in the service registry.
bean-name | any string value | Convenient shortcut for specifying a filter expression that matches on the bean-name property that is automatically advertised for beans published using the <service> element.
context-class-loader | client | service-provider | unmanaged | Defines how the context class loader is managed when invoking operations on a service backing this service reference. The default value is `client` which means that the context class loader has visibility of the resources on this bundle's classpath. Alternate options are `service-provider` which means that the context class loader has visibility of resources on the bundle classpath of the bundle that exported the service, and `unmanaged` which does not do any management of the context class loader.
availability | optional | mandatory | Defines the desired availability of the relationship to the backing service. If not specified, the `default-availability` attribute will apply. 'mandatory' value (the default) means that a backing service must exist at all times. The 'optional' value indicates that it is acceptable to be for an importer to have no backing service.
timeout | any positive long | The amount of time (in milliseconds) to wait for a backing service to be available when an operation is invoked. If not specified, the `default-timeout` attribute will apply.
sticky | true | false | Indicates the stickiness of the service import. If 'true' (default), the proxy will rebind only if the backing service is no longer available. If 'false' (Spring DM 1.x behaviour), the rebind will occur every time a 'better' candidate appears. A better service is defined by having either a higher ranking or the same ranking and a lower service id.

#### 9.2.2.9. `reference` And OSGi Service Dynamics

The bean defined by the `reference` element is unchanged throughout the lifetime of the application context (the object reference remains constant). However, the OSGi service that backs the reference may come and go at any time. For a mandatory service reference, the creation of the application context will block until a matching service is available. Section 9.2.1, “Imported Service Availability” provides more details.

When the service backing a `reference` bean goes away, Gemini Blueprint tries to replace the backing service with another service matching the reference criteria. An application may be notified of a change in backing service by registering a `reference-listener`. If no matching service is available, then the `reference` is said to be unsatisfied. An unsatisfied mandatory service causes any exported service (`service` bean) that depends on it to be unregistered from the service registry until such time as the reference is satisfied again. See Section 9.2.1.2, “Relationship Between The Service Exporter And Service Importer” for more information.

When an operation is invoked on an unsatisfied `reference` bean (either optional or mandatory), the invocation blocks until the reference becomes satisfied. The optional `timeout` attribute of the `reference` element enables a timeout value (in milliseconds) to be specified. If no matching service becomes available within the timeout period, an unchecked `ServiceUnavailableException` is thrown.

#### 9.2.2.10. Getting A Hold Of The Managed Service Reference

Gemini Blueprint/Spring DM can automatically convert a managed OSGi service to service reference. That is, if the property into which a reference bean is to be injected, has type `ServiceReference` (instead of the service interface supported by the reference), then the managed OSGi `ServiceReference` for the service will be injected in place of the service itself:

    public class BeanWithServiceReference {
    	private ServiceReference serviceReference;
    	private SomeService service;

    	// getters/setters ommitted
    }

    <reference id="service" interface="com.xyz.SomeService"/>

    <bean id="someBean" class="BeanWithServiceReference">
      <property name="serviceReference" ref="service"/>
      <property name="service" ref="service"/>
    </bean>

| Automatic managed service to `ServiceReference` conversion.
| Managed service is injected without any conversion

| Note
The injected `ServiceReference` is managed by Gemini Blueprint/Spring DM and will change at the same time as the referenced backing OSGi service instance.

There are cases when the managed `ServiceReference` is needed to get a hold of the OSGi service. Unfortunately, most of the OSGi frameworks expect their own `ServiceReference` classes and will fail when the Gemini Blueprint/Spring DM managed reference is used. For such cases, one can get a hold of the native `ServiceReference` bound at that moment, by casting the reference object to `ServiceReferenceProxy` and then calling `getTargetServiceReference`. Using the example context above, one might use the following code:

    ServiceReference nativeReference = ((ServiceReferenceProxy)serviceReference).getTargetServiceReference()

The returned `nativeReference` can be safely passed to the OSGi framework however, since it is not managed by Gemini Blueprint/Spring DM, in time, it might refer to a service different then the one backing the imported OSGi service.

To avoid this desynchronization, consider using managed `ServiceReference` objects mainly for reading the bound OSGi service properties rather then getting a hold of OSGi services (which can be simply injected by Gemini Blueprint/Spring DM).

### 9.2.3. Referencing A Collection Of Services

Sometimes an application needs access not simply to any service meeting some criteria, but to all services meeting some criteria. Gemini Blueprint/Spring DM allows the matching services may be held in a `List` or `Set` (optionally sorted).

The difference between using a `List` and a `Set` to manage the collection is one of equality. Two or more services published in the registry (and with distinct service ids) may be "equal" to each other, depending on the implementation of equals used by the service implementations. Only one such service will be present in a set, whereas all services returned from the registry will be present in a list. For more details on collections, see this tutorial.

The `set` and `list` schema elements are used to define collections of services with set or list semantics respectively.

These elements support the attributes `interface`, `filter`, `bean-name`, `availability`, and `context-class-loader`, with the same semantics as for the `reference` element. The allowable values for the `availability` attribute are `mandatory` and `optional`.

An availability value of `optional` indicates that it is permissible to be no matching services. An availability value of `mandatory` indicates that at least one matching service is required at all times. Such a reference is considered a required reference and any exported services from the same bundle (`service` defined beans) that depend on a mandatory reference will automatically be unregistered when the reference becomes unsatisfied, and reregistered when the reference becomes satisfied again. See Section 9.2.1, “Imported Service Availability” for more details.

The bean defined by a `list` element is of type `java.util.List`. The bean defined by a `set` element is of type `java.util.Set`.

| Note
Make sure the Gemini Blueprint/Spring DM collections are injected into properties of compatible types ( for example `set` into `Set` or `Collection`) since otherwise the container will automatically perform type conversion, transforming the Gemini Blueprint/Spring DM managed collection into a 'normal' one, unaware of the OSGi dynamics.

The following example defines a bean of type `List` that will contain all registered services supporting the `EventListener` interface:

    <list id="myEventListeners" interface="com.xyz.EventListener"/>

The members of the collection defined by the bean are managed dynamically by Spring. As matching services are registered and unregistered in the service registry, the collection membership will be kept up to date. Each member of the collection supports the service interfaces that the corresponding service was registered with and that are visible to the bundle.

Gemini Blueprint/Spring DM supports sorted collections as well, both for set and list.

It is possible to specify a sorting order using either the `comparator-ref` attribute, or the nested `comparator` element. The `comparator-ref` attribute is used to refer to a named bean implementing `java.util.Comparator`. The `comparator` element can be used to define an inline bean. For example:

    <set id="myServices" interface="com.xyz.MyService"
      comparator-ref="someComparator"/>

    <list id="myOtherServices"
      interface="com.xyz.OtherService">
      <comparator>
         <beans:bean class="MyOtherServiceComparator"/>
      </comparator>
    </list>

To sort using a natural ordering instead of an explicit comparator, you can use the `natural` element inside of `comparator`. You need to specify the basis for the natural ordering: based on the service references, following the `ServiceReference` natural ordering defined in the OSGi Core Specification release 4, version 4.1, section 6.1.23; or based on the services themselves (in which case the services must be `Comparable`).

    <list id="myServices" interface="com.xyz.MyService">
      <comparator><natural basis="services"/></comparator>
    </list>

    <set id="myOtherServices"interface="com.xyz.OtherService">
      <comparator><natural basis="service-references"/></comparator>
    </set>

| Note
For a sorted set, a `SortedSet` implementation will be created. However, since the JDK API does not provide a dedicated `SortedList`interface, the sorted list will implement only the `List` interface.

#### 9.2.3.1. Greedy Proxying

All OSGi services imported by a Gemini Blueprint/Spring DM service collection publish and are type-compatible with the classes declared by the `interfaces` property. However, some services might expose additional (optional) classes that could be relevant to your application.

For these cases, Gemini Blueprint/Spring DM collections offer a dedicated attribute called `greedy-proxying` which will cause the creates proxies to use all the classes advertised by the imported services, visible to the consuming importing bundle. Thus, it is possible to cast the imported proxies to classes different then those specified in the `interfaces`. For example, with the following list definition:

    <list id="services" interface="com.xyz.SomeService" greedy-proxying="true"/>

one can do the following iteration (assuming `MessageDispatcher` type is imported by the bundle):

    for (Iterator iterator = services.iterator(); iterator.hasNext();) {
    	SomeService service = (SomeService) iterator.next();
    	service.executeOperation();
    	// if the service implements an additional type
    	// do something extra
    	if (service instanceof MessageDispatcher) {
    		((MessageDispatcher)service).sendAckMessage();
    	}
    }

| Note
Before using greedy proxies and `instanceof` statements, consider using a different interface/class for your services which provides better polymorphism and is more object-oriented.

#### 9.2.3.2. Member Type

Since Spring DM 2.x/Gemini Blueprint, service collections can contain either service instances (default) or service references. The latter is useful if the services themselves are not relevant but rather their properties and availability. For example, to track the service references, the following configuration can be used:

    <list id="services" interface="com.xyz.SomeService" member-type="service-reference"/>

Note that the collection contains native service references which can be used by client to retrieve the backing service (if needed). However, when using Gemini Blueprint/Spring DM this use case is discouraged since one can let the framework track the services instead and get the (native) associated service reference from the proxy directly (see Section 9.2.2.10, “Getting A Hold Of The Managed Service Reference” for more details).

#### 9.2.3.3. Collection (`list` And `set`) Element Attributes

`list` and `set` elements support all the attributes available to `reference` element except the `timeout` attribute. See the following table as a summary of the `list` and `set` element attribute names, possible values and a short description for each of them.

Table 9.4. <list>/<set> attributes

Name | Values | Description
--- | --- | ---
interface | fully qualified class name (such as `java.lang.Thread`) | The fully qualified name of the class under which the object will be exported.
filter | OSGi filter expression (such as `((asynchronous-delivery=true)`) | OSGi filter expression that is used to constrain the set of matching services in the service registry.
bean-name | any string value | Convenient shortcut for specifying a filter expression that matches on the bean-name property that is automatically advertised for beans published using the <service> element.
context-class-loader | client | service-provider | unmanaged | Defines how the context class loader is managed when invoking operations on a service backing this service reference. The default value is `client` which means that the context class loader has visibility of the resources on this bundle's classpath. Alternate options are `service-provider` which means that the context class loader has visibility of resources on the bundle classpath of the bundle that exported the service, and `unmanaged` which does not do any management of the context class loader.
availability | optional | mandatory | Defines the desired availability of the relationship to the backing service. If not specified, the `default-availability` attribute will apply. 'mandatory' value (the default) means that a backing service must exist at all times. The 'optional' value indicates that it is acceptable to be for an importer to have no backing service.
comparator-ref | any string value | Named reference to a bean acting as comparator for the declaring collection. Declaring a comparator automatically makes the declaring collection sorted.
greedy-proxying | true | false | Indicates whether the proxies created for the imported OSGi services will be generated using just the classes specified (`false`) or all the classes exported by the service and visible to the importing bundle (`true`). The default value is `false`.
member-type | service-object | service-reference | Indicates the type of object that will be placed within the reference collection. `service-object` (the default) indicates the collection contains service proxies for imported services. `service-reference` indicates the collection contains `ServiceReference` objects matching the target service type.

The table below lists the attributes available for the `comparator/natural` sub element.

Table 9.5. collection <comparator> attributes

Name | Values | Description
--- | --- | ---
basis | service | service-reference | Indicate the element on which natural ordering should apply - `service` for considering the service instance and `service-reference` for considering the service reference instead of the service.

#### 9.2.3.4. `list` / `set` And OSGi Service Dynamics

A collection of OSGi services will change its content during the lifetime of the application context since it needs to reflect the state of the OSGi space. As service are registered and unregistered, they will be added or removed from the collection.

While a `reference` declaration will try to find a replacement if the backing service is unregistered, the collection will simply remove the service from the collection. Like `reference`, a collection of services can have a specified `availability`. As opposed to `reference`s though, since Spring DM 2.x/Gemini Blueprint, a collection content can be queried, no matter its availability and the number of services held.

Just like `reference`, mandatory collections will trigger the unregistration of any exported service that depends upon it. See Section 9.2.1.2, “Relationship Between The Service Exporter And Service Importer” for more information.

#### 9.2.3.5. `Iterator` Contract And Service Collections

The recommend way of traversing a collection is by using an `Iterator`. However, since OSGi services can come and go, the content of the managed service collection will be adjusted accordingly. Gemini Blueprint/Spring DM will transparently update all `Iterator`s held by the user so it is possible to safely traverse the collection while it is being modified. Moreover, the `Iterator`s will reflect all the changes made to the collection, even if they occurred after the `Iterator`s were created (that is during the iteration). Consider a case where a collection shrinks significantly (for example a big number of OSGi services are shutdown) right after an iteration started. To avoid dealing with the resulting 'dead' service references, Gemini Blueprint/Spring DM iterators do not take collection snapshots (that can be inaccurate) but rather are updated on each service event so they reflect the latest collection state, no matter how fast or slow the iteration is.

It is important to note that a service update will only influence `Iterator` operations that are executed after the event occurred. Services already returned by the iterator will not be updated even if the backing service has been unregistered. As a side note, if an operation is invoked on such a service that has been unregistered, a `ServiceUnavailableException` will be thrown.

To conclude, while a `reference` declaration will search for candidates in case the backing service has been unregistered, a service collections will not replace unregistered services returned to the user. However, it will remove the unregistered services from the collection so future iterations will not encounter them.

Please note that the `Iterator` contract is guaranteed meaning that `next()` method always obey the result of the previous `hasNext()` invocation.

Table 9.6. Dynamic service collection `Iterator` contract

hasNext() returned value | next() behaviour
--- | ---
true | Always return a non-null value, even when the collection has shrunk as services when away.
false | per `Iterator` contract, `NoSuchElementException` is thrown. This applies even if other services are added to the collection

The behaviour described above, offers a consistent view over the collection even if its structure changes during iteration. To simply refresh the iterator, call `hasNext()` again. This will force the `Iterator` to check again the collection status for its particular entry in the iteration.

In addition, any elements added to the collection during iteration over a sorted collection will only be visible if the iterator has not already passed their sort point.

### 9.2.4. Dealing With The Dynamics Of OSGi Imported Services

Whether you are using `reference` or `set` or `list`, Spring Dynamic Modules will manage the backing service. However there are cases where the application needs to be aware when the backing service is updated.

Such applications, that need to be aware of when the service backing a `reference` bean is bound and unbound, can register one or more listeners using the nested `reference-listener` (or `listener`) element. This element is available on both `reference` and `set`, `list` declarations. In many respects, the service importer listener declaration is similar to the service exporter listener declaration (Section 9.1.10, “Service Registration And Unregistration Lifecycle”). The `reference-listener` element refers to a bean (either by name, or by defining one inline) that will receive bind and unbind notifications. If this bean implements Gemini Blueprint/Spring DM's `org.eclipse.gemini.blueprint.service.importer.OsgiServiceLifecycleListener` interface, then the `bind` and `unbind` operations in this interface will be invoked. Instead of implementing this interface (or in addition), custom bind and unbind callback methods may be named.

An example of declaring a listener that implements `OsgiServiceLifecycleListener`:

    <reference id="someService" interface="com.xyz.MessageService">
      <reference-listener ref="aListenerBean"/>
    </reference>

An example of declaring an inline listener bean with custom bind and unbind methods:

    <reference id="someService" interface="com.xyz.MessageService">
      <reference-listener bind-method="onBind" unbind-method="onUnbind">
         <beans:bean class="MyCustomListener"/>
      </reference-listener>
    </reference>

If the listener bean implements the `OsgiServiceLifecycleListener` interface and the listener definition specifies custom bind and unbind operations then both the `OsgiServiceLifecycleListener` operation and the custom operation will be invoked, in that order.

The signature of a custom bind or unbind method must be one of:

    public void anyMethodName(ServiceType service, Dictionary properties);

    public void anyMethodName(ServiceType service, Map properties);

    public void anyMethodName(ServiceReference ref);

where `ServiceType` can be any type. Please note that bind and unbind callbacks are invoked only if the backing service matches the type declared in the method signature( `ServiceType`). If you want the callbacks to be called no matter the type, use `java.lang.Object` as a `ServiceType`.

The `properties` parameter contains the set of properties that the service was registered with.

If the method signature has a single argument of type `ServiceReference` then the `ServiceReference` of the service will be passed to the callback in place of the service object itself.

When the listener is used with a `reference` declaration:

- A bind callback is invoked when the reference is initially bound to a backing service, and whenever the backing service is replaced by a new backing service.
- An unbind callback is only invoked when the current backing service is unregistered, and no replacement service is immediately available (i.e., the `reference` becomes unsatisfied).

When the listener is used with a collection declaration (`set` or `list`):

- A bind callback is invoked when a new service is added to the collection.
- An unbind callback is invoked when a service is unregistered and is removed from the collection.

Again note that service collections there is no notion of service rebind: services are added or removed from the collection.

Bind and unbind callbacks are made synchronously as part of processing an OSGi `serviceChanged` event for the backing OSGi service, and are invoked on the OSGi thread that delivers the corresponding OSGi `ServiceEvent`.

The table below lists the attributes available for the `reference` `listener` sub element.

Table 9.7. OSGi <reference-listener> attributes

Name | Values | Description
--- | --- | ---
ref | bean name reference | Name based reference to another bean acting as listener.
bind-method | string representing a valid method name | The name of the method to be invoked when a backing service is bound.
unbind-method | string representing a valid method name | The name of the method to be invoked when a backing service is bound.

### 9.2.5. Blueprint `reference` Comparison

Similar to Gemini Blueprint/Spring DM, the Blueprint Container offers a `reference` and `list` elements, identical in functionality with the those in Gemini Blueprint/Spring DM. Below is a summary of the configuration options available in Gemini Blueprint/Spring DM and Blueprint:

Table 9.8. Spring DM / Blueprint Service Importer Configuration Comparison

Gemini Blueprint/Spring DM | Blueprint
--- | ---
Common Elements/Attributes |
interface | interface
interfaces | - (multiple interfaces not supported)
ref | ref
filter | filter
bean-name | component-name
availability | availability
context-class-loader | -
`<reference>` |
timeout | timeout
sticky | - (the importer is always sticky)
`<list>` |
member-type | member-type
comparator-ref | -
greedy-proxying | -

Since the `registration-listener` declaration is identical in declaration and functionality between Blueprint and Gemini Blueprint/Spring DM, this section does not mention it.

## 9.3. Listener And Service Proxies

While the importer listener provides access to the OSGi service bound at a certain point, it is important to note that the given argument is not the actual service but a proxy. This can have subtle side effects especially with regards to service class name and identity. The reason behind using a proxy is to prevent the listener from holding strong reference to the service (which can disappear at any point). Listeners interested in tracking certain services should not rely on instance equality (`==`). Object equality (`equals`/`hashcode`) can be used but only if the backing service has exposed the aforementioned methods as part of its contract (normally by declaring them on a certain published interface/class). If these methods are not published, the proxy will invoke its own method, not the targets. This is on purpose since, while the proxy tries to be as transparent as possible, it is up to the developer to define the desired semantics.

Thus, it is recommended (especially for `reference` importers) to do tracking based on just the service interface/contract (not identity), service properties (see `org.osgi.framework.Constants#SERVICE_ID`) or service notification (bind/unbind).

## 9.4. Accessing The Caller `BundleContext`

It is sometimes useful for an imported service to know which bundle is using it at a certain time. To help with this scenario, in Gemini Blueprint/Spring DM imported services publish the importing bundle `BundleContext` through `LocalBundleContext` class. Each time a method on the importer is invoked, the caller `BundleContext` will be made available, using a `ThreadLocal`, through `getInvokerBundleContext()`.

Please be careful when using this class since it ties your code to Gemini Blueprint/Spring DM API.

## 9.5. Exporter/Importer Listener Best Practices

As mentioned above, Gemini Blueprint/Spring DM exporter and importer allow listeners to be used for receiving notifications on when services are bound, unbound, registered or unregistered. Below you can find some guidance advices when working with listeners:

- Do not execute long activity tasks inside the listener. If you really have to, use a separate thread for executing the work. The listener are called synchronously and so try to be as fast as possible. Doing work inside the listener prevents other the event to be sent to other listeners and the OSGi service to resume activity.
- Use listener custom declaration as much as possible - it doesn't tie your code to Gemini Blueprint/Spring DM API and it doesn't enforce certain signature names.
- If find yourself repeating bind/unbind method declarations for your listener definitions, consider using Spring bean definition inheritance to define a common definition that can be reused and customized accordingly.
- Prefer `java.util.Map` instead of `java.util.Dictionary` class. The first is an interface while the latter is a deprecated, abstract class. To preserve compatibility, Gemini Blueprint/Spring DM will pass to the listeners a `Map` implementation that can be casted, if needed, to a `Dictionary`.
- Be careful when using overloaded methods: all methods matching a certain service type will be called which is not always expected. Consider the following listener:

      public class MyListener {
          void register(Object service, Map properties);
          void register(Collection dataService, Map properties);
          void register(SortedSet orderedDataService , Map properties);
      }

  | `Object` type - will match all services for which the listener is triggered. This method will be always called.
  | `Collection` type - if this method is called, the `Object` method is also called.
  | `SortedSet` type - if this method is called, then both the `Object` and `Collection` methods are called.

### 9.5.1. Listener And Cyclic Dependencies

There are cases where an exporter/importer listener needs a reference back to the bean it is defined on:

    <bean id="listener" class="cycle.Listener">
        <property name="target" ref="importer" />
    </bean>

    <osgi:reference id="importer" interface="SomeService">
        <osgi:listener bind-method="bind" ref="listener" />
    </osgi:reference>

| Listener bean
| Dependency listener -> importer
| Importer declaration
| Dependency importer -> listener

The declaration above while valid, creates a dependecy between the `listener` and the importer it is defined upon. In order to create the importer, the `listener` has to be resolved and created but in order to do that, the importer called `service` needs to be retrieved (instantiated and configured). This cycle needs to be broken down so that at least one bean can be fully created and configured. This scenario is supported by Gemini Blueprint/Spring DM for both exporter and importers however, if the listener is defined as a nested bean, the cycle cannot be resolved:

    <osgi:reference id="importer" interface="SomeService">
        <osgi:listener bind-method="bind">
            <bean class="cycle.Listener">
                <property name="target" ref="importer" />
            </bean>
        </osgi:listener>
    </osgi:reference>

| OSGi service importer
| Dependency between importer -> listener
| Nested listener declaration
| Dependency nested listener -> importer

The example above will fail since `service` bean cannot be initialized as it depends on the listener. The same cycle was seen before but in this case there is subtle yet big different from the container perspective - the listener is declared as a nested/inner-bean (hence the missing bean `id`). Inner beans have the same life cycle as their declaring parents and do not have any name. By definition, they are not tracked by the container and are simply created on demand. Since the importer cannot be partially created and the nested listener cannot be cached, the container cannot break the cycle and create the beans. While the two configurations shown above seem similar, one works while the other does not. Another reason to not use cycles unless you really, really have to.

To conclude, if you need inside the listener to hold a reference to the exporter/importer on which the listener is declared, either declare the listener as a top-level bean (as shown before) or consider doing dependency lookup. However, the latter approach requires extra contextual information such as the `BeanFactory` to use and the bean name and is more fragile then dependency injection.

| Note
For those interested in the technical details, neither the exporter and importer cannot be partially initialized since they require the application context `ClassLoader` which is requested through the `BeanClassLoaderAware` which relies on a buit-in `BeanPostProcessor` which is applied only after the bean has been configured and is ready for initialization. If the `ClassLoader` was not required then the exporter/importer could have been partially initialized and the case above supported.

## 9.6. Service Importer Global Defaults

The `osgi` namespace offers two global attributes for specifying default behaviours for all importers declared in that file.

Thus, when using the `osgi` namespace to enclose `set`, `list` or `reference` elements, one can use:

- `default-timeout` - can be used to specify the default timeout (in milliseconds) for all importer elements that do not explicitly specify one. For example:

      <beans xmlns="http://www.springframework.org/schema/beans"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns:osgi="http://www.springframework.org/schema/osgi"
                osgi:default-timeout="5000">

        <reference id="someService" interface="com.xyz.AService"/>

        <reference id="someOtherService" interface="com.xyz.BService"
             timeout="1000"/>

      </beans:beans>

  | Declare `osgi` namespace prefix.
  | Declare `default-timeout`(in miliseconds) on the root element. If the default is not set, it will have a value of 5 minutes. In this example, the default value is 5 seconds.
  | This `reference` will inherit the default timeout value since it does not specify one. This service reference will have a timeout of 5 seconds.
  | This `reference` declares a timeout, overriding the default value. This service reference will have a timeout of 1 second.

- `default-availability` - can be used to specify the default availability for all importer elements that do not explicitly specify one. Possible values are `optional` and `mandatory`. The `default-cardinality` attribute, used by Spring DM 1.x, is still available but it has been deprecated.

  Consider the following example:

      <beans:beans
            xmlns="http://www.springframework.org/schema/osgi"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns:beans="http://www.springframework.org/schema/beans"
            xmlns:osgi="http://www.springframework.org/schema/osgi"
               osgi:default-availability="optional"
               default-lazy-init="false">

        <reference id="someService" interface="com.xyz.AService"/>

        <set id="someSetOfService" interface="com.xyz.BService"/>

        <list id="anotherListOfServices" interface="com.xyz.CService"
                     availability="mandatory"/>

      </beans:beans>

  | Declare Gemini Blueprint schema as the default namespace.
  | Import Spring Framework beans schema and associate a prefix with its namespace (`beans` in this example).
  | Import Gemini Blueprint schema and associate a prefix with its namespace (`osgi` in this example). This is required since the global attributes have to be declared to an element (`beans`) belonging to another schema. To avoid ambiguity, the Gemini Blueprint/Spring DM schema is imported under a specified prefix as well.
  | Declare `default-availability` on the root element. If the default is not set, it will have a value of `mandatory`. In this example, the default value is `optional`. Note the `osgi` prefix added to the global attribute.
  | `beans` element attributes (such as `default-lazy-init`) do not need a prefix since they are declared as being local and unqualified (see the beans schema for more information).
  | The `reference` declaration will inherit the default availability value since it does not specify one.
  | The `set` declaration will inherit the default availability value since it does not specify one.
  | The `list` declaration specifies its availability (`mandatory`), overriding the default value.

The `default-*` attributes allow for concise and shorter declarations as well as easy propagation of changes (such as increasing or decreasing the timeout).

Prev | Home | Next
Chapter 8. Packaging and Deploying Spring-based OSGi applications | Sponsored by SpringSource | Chapter 10. Working With Bundles