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 8.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.

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). 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 Spring DM which offers a instance-per-bundle contract (see Section 6.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"/>

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.

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

public interface SuperInterface {}

public interface SubInterface extends SuperInterface {}

As previously described, an exported service is always registered with the service property org.springframework.osgi.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 Spring Dynamic Modules roadmap includes support for exporting properties registered in the OSGi Configuration Administration service as properties of the registered service. See Appendix F, Roadmap for more details.

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"/>

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, Spring Dynamic Modules 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 .

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"/>

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, 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"/>

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

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).

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.

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

8.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 6.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, 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 7.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. 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.

<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"/>

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).

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

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

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

8.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 8.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.springframework.osgi.bean.name set to value messageServiceBean. In short, this means finding all Spring DM exported beans that implement interface MessageService and are named messageServiceBean.

8.2.2.10. Getting A Hold Of The Managed Service Reference

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 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 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 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 Spring DM).

Sometimes an application needs access not simply to any service meeting some criteria, but to all services meeting some criteria. 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 8.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 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 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.

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 SortedListinterface, the sorted list will implement only the List interface.

8.2.3.1. Greedy Proxying

All OSGi services imported by a 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, 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.

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

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 8.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 Spring DM's org.springframework.osgi.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:

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

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.

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

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

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