Spring DM uses heavily Spring framework's core functionalty, such as the IoC container, resource abstract or AOP infrastructure. While it is not important to know the Spring APIs, understanding the concepts behind them is. At a minimum, the idea behind IoC should be familiar. These being said, the more knowledge one has about the Spring, the faster she will pick Spring Dynamic Modules. Besides the very comprehensive (and sometimes disarming) documentation that explains in detail the Spring Framework, there are a lot of articles, blog entries and books on the matter - take a look at the Spring framework home page for more information. In general, this should be the starting point for OSGi (or Eclipse plugin) developers wanting to try Spring DM.

Java developers, new to OSGi, can start by reading the OSGi Alliance introduction, the OSGi specifications or one of the articles/blogs available on the internet (such as the SpringSource blogs). Additionally, the Spring DM home page hosts various links to useful materials.

As an alternative to the recommended Spring documentation, if OSGi 4.2 is an option, one can read the Blueprint Container specification for a quick introdution to dependency injection and Spring DM functionality. Note that Blueprint is a subset of Spring and Spring DM and we recommend the official documentation to get access to the whole set of features.

Once one is familiar with the concepts behind Spring and OSGi, she can start reading the Spring DM reference documentation (this document) and take the Spring DM samples for a spin. The samples are available either in the .zip distribution or from the Spring DM repository. The samples are a convenient way to get started quickly with Spring DM as they show various features of Spring DM and help one get pass the initial struggles with OSGi. However, they are not meant as the definitive guide in using OSGi rather, they aim to be a launching pad for "newbies" trying out OSGi in Spring.

The current distribution contains:

Each project contains instructions regarding its content and startup procedure. Users are encouraged to experiment with the samples to get a better understanding of the technologies used.

The Spring DM forum is a message board for all Spring DM users to share information and help each other. Note that registration is needed only for posting.

Professional, from-the-source support, with guaranteed response time, is available from SpringSource, the company behind Spring Dynamic Modules and Spring.

Spring DM served as the basis for the Blueprint Container specification, introduced by OSGi 4.2. Spring DM 2.0 stands as the RI for the aforementioned specification, providing the Blueprint API and implementation out of the box. Various aspect of Spring DM have been adjusted for consistency to the Blueprint specification. For more information on the two models, see Chapter 5, OSGi 4.2 Blueprint Container for more information.

As of 2.x, Spring DM requires JDK 5 to run (or compile). The framework code has been revised to take advantage of the JDK 5 features such as language improvements, concurrency and generics: for example, various enum-like classes used by the exporter and importer API have been deprecated and replaced with proper Java 5enums. Considerable effort has been spent to keep the code backwards compatible however, it is recommended to compile the code against the Spring DM 2.x code and perform sanity checks before upgrading.

Besides the Java 5 upgrade, DM 2.0 requires Spring 3.x to get access to the latest framework features and JDK optimizations.

2.0.x provides several improvements for service imports (whether single or collection based) in terms of speed, configuration and service lifecycle. Section 8.2, “Defining References To OSGi Services” provides more details.

Continuing the work in 1.2.x, Spring DM 2.0 executes all user code using its credentials (the managed bundle permissions). See Appendix B, Security Integration for more information.

Since 1.2.x, Spring Dynamic Modules is aware of secured environments by making use of dedicated privileged blocks for executing security sensitive code. Thus, Spring DM can run as a trusted library without requiring escalated permissions for its managed bundles. See Appendix B, Security Integration for more information.

1.2.x provides integration with the Configuration Admin, part of the OSGi compendium services. Chapter 11, Compendium Services provides more details on the topic.

Since 1.2.0 M2, the Spring DM bundles symbolic names have been aligned with Spring's 2.5.6+. Thus the prefix org.springframework.bundle.osgi has been changed to org.springframework.osgi; for example Spring DM extender symbolic name was changed from org.springframework.bundle.osgi.extender to org.springframework.osgi.extender (notice the missing bundle word). Additionally, the documentation has been updated to reflect Spring 2.5.6+ symbolic names.

To minimize the number of repositories used and the confusion caused by OSGified vs non-OSGified artifacts especially to users using Spring dm Server, after 1.2.0 RC1, Spring Dynamic Modules aligned as many of its dependencies as possible with SpringSource EBR. In practice this means that Spring framework artifacts, such as spring-aop.jar can be now found as org.springframework.aop.jar; We apologize for any inconvenience created to users relying on these naming conventions.

The biggest feature in Spring Dynamic Modules 1.1.x is the transparent support for web applications on OSGi platforms. By integrating directly with web containers (such as Apache Tomcat and Jetty), Spring DM allows WARs using Servlet, JSP and taglib technologies to be used with little or no effort at all. Please see Chapter 10, Web Support for details.

1.1.x adds support for classpath: and classpath*: prefixes to the OSGi Resource abstraction. This allows the discovery of classpath resources (such as Spring's component scanning) to work out-of-the-box across multiple bundles on the supported OSGi platforms. See Section 6.4, “The Resource Abstraction” for more information.

1.1.x makes it easy to change the default configuration for the various extenders used by Spring DM. By using fragments, users can customize the way application contexts are started, the web container used for web deployment or the thread-pool for running Spring applications. Additionally, it is possible to receive events regarding the OSGi Spring application contexts lifecycle. Section 6.1, “The Spring Dynamic Modules Extender Bundle” lists the available options and explains them in detail.

In 1.1.x, the proxy creation has been improved, leading to better package wiring for the managed bundles. See the FAQ for more information.

Most of the XML declarations are similar between Spring and Blueprint. Using the Spring namespace mechanism, the same configuration can contain both Spring, Spring DM, Blueprint and other namespaces. Moreover, custom elements can be used for virtually all elements of a Spring configuration (namespace, bean declaration, decoration, etc...). The table below focuses only on the usual, standard Spring namespaces and their Blueprint equivalent.

The configurations below are equivalent in terms of functionality:

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" default-activation="lazy">
    <bean id="object" class="java.lang.Object"/>
    
    <bean id="length" class="java.lang.Integer">
        <argument value="4"/>
    </bean>
    
    <bean id="buffer" class="java.lang.StringBuffer" depends-on="simple">
    	<property name="length" ref="length"/>
    </bean>
    
    <bean id="current-time" class="java.lang.System" factory-method="currentTimeMillis" scope="prototype"/>
    
    <bean id="list" class="java.util.ArrayList" destroy-method="clear" activation="eager">
    	<argument ref="length"/>
    </bean>
</blueprint>

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"
    default-lazy-init="true">
    
    <bean id="object" class="java.lang.Object"/>
    
    <bean id="length" class="java.lang.Integer">
        <constructor-arg value="4"/>
    </bean>
    
    <bean id="buffer" class="java.lang.StringBuffer" depends-on="simple">
    	<property name="length" ref="length"/>
    </bean>
    
    <bean id="current-time" class="java.lang.System" factory-method="currentTimeMillis" scope="prototype"/>
    
    <bean id="list" class="java.util.ArrayList" destroy-method="clear" lazy-init="false">
    	<constructor-arg ref="length"/>
    </bean>
</beans>

As mentioned before, in Spring DM one can mix and match the namespaces:

<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:bp="http://www.osgi.org/xmlns/blueprint/v1.0.0"
	xmlns:p="http://www.springframework.org/schema/p"
	xmlns:osgi="http://www.springframework.org/schema/osgi"
	xmlns:task="http://www.springframework.org/schema/task"
	xmlns:util="http://www.springframework.org/schema/util"
	xsi:schemaLocation="
		http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
		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
		http://www.springframework.org/schema/task http://www.springframework.org/schema/task/spring-task.xsd		
		http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">
    
    <util:constant id="thread-priority" static-field="java.lang.Thread.MIN_PRIORITY"/>
    
    <bean id="exampleThread" class="java.lang.Thread" p:priority-ref="thread-priority">
    	<constructor-arg>
    	   <bp:bean class="org.example.SomeRunnable"/>
    	</constructor-arg>
    </bean>
    
    <task:executor id="rangeWithBoundedQueue" size="7-42" queue-capacity="#{ T(java.lang.Math).random() * 30.0 }"/>

    <bp:reference-list id="cloneableServices" interface="java.lang.Cloneable" />
<beans>

The example above, uses the Spring beans, util, p, Spring Expression Language (SpEL) and the task namespace introduced in Spring 3.x, and Spring DM namespace.

From a container perspective, the Blueprint spec standardizes the a subset of the Spring container. A high-level view comparison, by no means comprehensive, is summarized in the table below:

As with the XML configuration, since Spring DM translates the Blueprint configuration into Spring metadata, one can rely on Spring for features beyond the Blueprint container. For example, one can configure a bean using Blueprint and use annotation on the same instance, for field injection. The same object can implement Spring's Aware interfaces or rely on other post processors for certain behaviour.

If an application context declares mandatory availability for certain imported OSGi services, the creation of the application context is blocked until all the mandatory dependencies can be satisfied through matching services available in the OSGi service registry. In practice, for most enterprise applications built using Spring Dynamic Modules services, the set of available services and bundles will reach a steady state once the platform and its installed bundles are all started. In such a world, the behaviour of waiting for mandatory dependencies simply ensures that bundles A and B, where bundle A depends on services exported by bundle B, may be started in any order.

A timeout applies to the wait for mandatory dependencies to be satisfied. By default the timeout is set to 5 minutes, but this value can be configured using the timeout directive. See Section 7.1, “Bundle Format And Manifest Headers” for details.

Blueprint users could achieve the same result through the blueprint.timeout attribute declared on the Bundle-SymbolicName

It is possible to change the application context creation semantics so that application context creation fails if all mandatory services are not immediately available upon startup (see the aforementioned section for more information). Again, note that regardless of the configuration chosen, the failure of the application context will not change the bundle state.

For more information on the availability of imported services, see Section 8.2.1, “Imported Service Availability”

Once the application context creation for a bundle has completed, the application context object is automatically exported as a service available through the OSGi Service Registry. The context is published under the interface org.springframework.context.ApplicationContext (and also all of the visible super-interfaces and types implemented by the context). The published service has a service property named org.springframework.context.service.name whose value is set to the bundle symbolic name of the bundle hosting the application context. In case of a Blueprint bundle, the container will be published under org.osgi.service.blueprint.container.BlueprintContainer while the bundle symbolic name will be published under osgi.blueprint.container.symbolicname property.

It is possible to prevent publication of the application context as a service using a directive in the bundle's manifest. See Section 7.1, “Bundle Format And Manifest Headers” for details.

Note: the application context is published as a service primarily to facilitate testing, administration, and management. Accessing this context object at runtime and invoking getBean() or similar operations is discouraged. The preferred way to access a bean defined in another application context is to export that bean as an OSGi service from the defining context, and then to import a reference to that service in the context that needs access to the service. Going via the service registry in this way ensures that a bean only sees services with compatible versions of service types, and that OSGi platform dynamics are respected.

There are cases when the failure or succesful startup of an application context needs to be acknowledged for logging purposes (for example). For these cases, Spring DM offers a dedicated package org.springframework.osgi.context.event which defines the events that OSGi application contexts can send during their lifecycle. At the moment, the following events are available:

Parties interested in receiving these events should implement OsgiBundleApplicationContextListener and then publish it as an OSGi service. The Spring DM extender will automatically detect the listener and will send the events to it. By taking advantage of the OSGi service registry, the extender decouples the received from the event publisher and moreover, makes the registration/unregistration process easier. For example, there is nothing special a client should do to unregister the listener - simply stopping the bundle will automatically unregister all its published services (including the listener), an event which will detected by the extender which will remove the listener. Of course, it is also possible for the client to unregister the listener manually during a bundle lifecycle.

	Note
	The Spring DM events semantics are slightly different then Spring's. The OSGi events are not sent to beans inside the causing application context but to other parties (possible beans in other application contexts) interested in monitoring its behaviour.

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.

When installing a WAR bundle, for static resources, Spring DM will only consider what is available in the bundle space - this means what is available in the bundle jar and its attached fragments. Conforming to the Servlet spec, resources under WEB-INF folder will be available through the ServletContext API but not to remote clients connecting to the web application. In addition, any resource available in the classpath (imported packages, required bundles or dynamic imports) can be loaded and used by the application code but cannot be seen outside of it.

The main difference from the traditional WAR deployment is that the Servlet packages need to be imported so they are available to the WAR bundle. To do that, add the following packages to the Import-Package entry:

Import-Package: javax.servlet,javax.servlet.http,javax.servlet.resources

Additionally, the servlet specification defines the classpath of a WAR, based on some predefined locations. To quickly recap, these are:

In addition, each container implementation can provide common libraries that are appended to the war classpath. Since OSGi, with its class wiring, versioning, reloading, superseeds the WAR classpath, Spring DM will ignore the WAR predefined locations and will always use the OSGi classpath instead. This means that classes imported by a WAR bundle can be used even if they are not present under WEB-INF/classes folder or inside a jar under WEB-INF/lib. This also means that any class under WEB-INF/classes will not be considered if it's not available in the WAR OSGi classpath.

One of the easiest ways to support the pre-defined WAR locations, is to add them to the bundle classpath, by adding them to the bundle manifest:

Bundle-Classpath: .,WEB-INF/classes,WEB-INF/lib/some.jar,WEB-INF/lib/lib.jar

Make sure the default Bundle-Classpath location (.) is present and there are no whitespaces between the commas.

	Note
	Since the OSGi API doesn't provide a hook for bundles to be pre-processed, Spring DM cannot automate this process in a reliable way. However, we are working on finding a suitable solution. Note that there are tools (bnd) that can add these entries during packaging.

Before creating entries for embedded libraries, consider whether they can be installed as OSGi bundles - doing so allows them to be shared with other WARs if needed and since OSGi allows versioning, it is perfectly okay to have multiple versions of the same library inside the same VM.

For JSPs, Spring DM integrates with Tomcat Jasper 2 Engine which means JSP 1.2, 2.0 and 2.1 are supported. OSGified versions for Jasper (from Tomcat 5.5.x and 6.0.x distribution respectively) are available in the Spring DM OSGi repository. No imports on Jasper classes are required for the OSGi bundle.

10.3.3.1. Tag Libraries

The JSP spec allows the creation of tag libraries to “define declarative, modular functionality that can be reused by any JSP page”. Also known as taglibs, these reusable components consist of Java classes (the tag implementation) and description files that indicate how the tags can be used. Spring DM extends the JSP convention, of placing the taglibs either packed as a jar under WEB-INF/lib or unpacked under WEB-INF/classes, by detecting any taglib defined in the bundle classpath (imported packages or required bundles).

Spring DM will automatically look for any taglib file (*.tld) available in the bundle classpath and will make them available to the Jasper engine. However, while the tag definitions are automatically discovered, the tag classes are not - again, the OSGi classpath takes priority. This means that in order to use a tag, the war bundle would have to import the tag corresponding classes since otherwise, they are not seen by the bundle and the tag cannot be used.

When dealing with libraries that export a lot of tags, one can use the Require-Bundle header instead of Import-Package for importing the tags:

Require-Bundle: org.springframework.osgi.jstl.osgi

Using the manifest entry above, all the classes (and thus tag implementations) exported by the JSP Standard Tag Library (or JSTL in short), are seen by the war bundle and thus can be used inside the JSPs.

	Warning
	Before using Require-Bundle on a large scale, please read the OSGi specification (section 3.13) for an in-depth review of its implications.

To change the Tomcat deployer to Jetty for example, one can create a configuration file META-INF/spring/extender/jetty-deployer.xml with the following content:

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

    <bean id="warDeployer"                                                               
        class="org.springframework.osgi.web.deployer.jetty.JettyWarDeployer" />          
</beans>

	Pre-defined bean name used by the web extender
	Bean implementing org.springframework.osgi.web.deployer.WarDeployer interface

Once the file is created, it should be bundled in an OSGi fragment attached to the Spring DM Web Extender bundle by adding the Fragment-Host header:

Fragment-Host: org.springframework.osgi.web.extender

Now the fragment can be deployed alongside spring-osgi-web.jar bundle to plug in Jetty.

A pre-packed Jetty fragment is available in the Spring DM maven repository under jetty.web.extender.fragment.osgi artifactId (make sure to use version 1.0.1+).

Spring DM web support expects the web containers to be installed as OSGi services. Since neither the Tomcat nor the Jetty distribution do this, Spring DM offers two simple yet useful OSGi Activators for both containers at the Spring DM OSGi repository. Once installed, these will programmatically start the appropriate web container based on a default configuration (which can be customized and publish it as an OSGi service. While the activators are generic, they can be easily customized for advance usages or even replaced - it's up to each deployer to decide how the server instances are looked up.

	Note
	The activator binaries and sources can be found either in the Spring DM repository (see below) or under the lib/ folder inside the Spring DM (with-dependencies) distribution

All entries in the repository belong to the org.springframework.osgi group and have an .osgi termination to differentiate them from the original jars.

Fragment-Host: org.springframework.osgi.catalina.start.osgi

Fragment-Host: org.springframework.osgi.jetty.start.osgi

Just like the extender, each activator uses a default configuration if the user doesn't provide one. For the latter case, one should use fragments (as mentioned above) to provide a customized configuration and to avoid modifying the distribution jar.

The Servlet, Java Server Pages, Standard Taglib, Commons-EL and other web libraries are available as well in the Spring DM repository. When browsing use an S3 compatible application .

In its simplest form, the CM can be seen as a configuration source, namely a Dictionary whose keys are always Strings. Spring DM can expose entries in the CM as a Properties object, through the cm-properties element. A minimal declaration looks as follows:

<osgix:cm-properties id="ds.cfg" persistent-id="data.source.office.1"/>

The configuration above, exposes the properties available in the CM under data.source.office.1 entry as a bean named ds.cfg.

	Note
	The persistent-id attribute must refer to the persistent-id of an OSGi ManagedService, it is a configuration error to specify a factory persistent id referring to a ManagedServiceFactory.

Those familiar with Spring's util namespace will find <osgi:cm-properties/> element similar to <util:properties/>.

It is possible to specify a default set of property values to be used in the event that the configuration dictionary does not contain an entry for a given key. The declaration is similar to the props element inside the Spring beans namespace:

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

   <osgix:cm-properties id="cfg.with.defaults" persistent-id="data.source.office.2">
      <beans:prop key="host">localhost</beans:prop>
      <beans:prop key="port">3306</beans:prop>
   </osgix:cm-properties>

</beans:beans>

By default, the properties found in the Configuration Admin entry will override the local properties. Thus, for the previous example, if the data.source.office.2 configuration contains a host entry, its value will override the locally defined localhost. For cases where this behaviour is undesired, the attribute local-override (default false) allows one to revert the merging algorithm, forcing the local properties to override the entries in the CM.

Since cm-properties exposes the CM entries as Properties, it can be used with Spring's PropertyPlaceholderConfigurer and PropertyOverrideConfigurer to externalize and customize environment-specific properties:

<?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:osgix="http://www.springframework.org/schema/osgi-compendium"
   xmlns:ctx="http://www.springframework.org/schema/context"
   xsi:schemaLocation="
	http://www.springframework.org/schema/beans 
	  http://www.springframework.org/schema/beans/spring-beans.xsd
	http://www.springframework.org/schema/context 
	  http://www.springframework.org/schema/context/spring-context.xsd
	http://www.springframework.org/schema/osgi-compendium 
	  http://www.springframework.org/schema/osgi-compendium/spring-osgi-compendium.xsd">

   <!-- Configuration Admin entry -->
   <osgix:cm-properties id="cmProps" persistent-id="com.xyz.myapp">
      <prop key="host">localhost</prop>
   </osgix:cm-properties>

   <!-- placeholder configurer -->
   <ctx:property-placeholder properties-ref="cmProps" />

   <bean id="dataSource" ...>
      <property name="host" value="${host}"/>
      <property name="timeout" value="${timeout}"/>
   </bean>
	
</beans>

An important aspect of cm-properties is does not reflect any that any subsequent changes made to the entry it represents, made through the Configuration Admin API. That is, once resolved, the cm-properties content remains the same, regardless of any updates made the to CM entry it represents.

Based on a configuration admin entry, Spring DM can autowire by name, the properties of a given bean. To use this feature, define a nested managed-properties inside the bean definition:

<bean id="managedComponent" class="MessageTank">
   <osgix:managed-properties persistent-id="com.xyz.messageservice"/> 
</bean>

For each key in the dictionary stored by Configuration Admin under the given persistent id, if the bean type has a property with a matching name (following JavaBeans conventions), then that component property will be dependency injected with the value stored in Configuration Admin under the key. If the definition of SomeClass from the example above is as follows:

public class MessageTank {
  private int amount;
  public int getAmount() { return this.amount; }
  public void setAmount(int amount) { this.amount = amount; }
}

and the configuration dictionary stored under the pid com.xyz.messageservice contains an entry amount=200, then the setAmount method will be invoked on the bean instance during configuration, passing in the value 200.

If a property value is defined both in the configuration dictionary stored in the Configuration Admin service and in a property element declaration nested in the component element, then the value from Configuration Admin takes precedence:

<bean id="managedComponent" class="MessageTank">
   <osgix:managed-properties persistent-id="com.xyz.messageservice"/>
   <property name="amount" value="100"/>
   <property name="threshold" value="500"/> 
</bean>

Property values specified via property elements can therefore be treated as default values to be used if none is available through Configuration Admin.

	Warning
	Do not share the same persistent-id (PID) between multiple bundles or definitions, as only one of them will receive notifications. managed-properties relies on org.osgi.service.cm.ManagedService contract which mandates that each ManagedService instance must be identified with its own unique PID. Please see the Configuration Admin spec, specifically section 104.3 and 104.5

public void anyMethodName(Map properties)
public void anyMethodName(Map<String,?> properties); // for Java 5

public class ContainerManagedBean {
  // will be reinjected (since it has a setter)
  private Integer integer;
  // will not be reinjected (no setter present)
  private Long waitTime; 
  
  public void setInteger(Integer integer) { this.integer = integer; }
}


public class SelfManagedBean {
  
  // update callback
  public void updateCallback(Map properties) {
	System.out.println("Received properties " + properties);
	System.out.println("Props can be used as a Dictionary " + (Dictionary) properties);
	// do more work ... 
  }
}

<bean id="containerManaged" class="ContainerManagedBean">
   <osgix:managed-properties persistent-id="labX" update-strategy="container-managed"/>
   <property name="integer" value="23"/>
</bean>
	
<bean id="beanManaged" class="SelfManagedBean">
   <osgix:managed-properties persistent-id="labY" update-strategy="bean-managed" update-method="updateCallback"/>
</bean>

The Configuration Admin service supports a notion of a managed service factory(see section 104.6 in the Compendium Specification). A managed service factory is identified by a factory pid which allows multiple Configuration objects to be associated with the factory. Configuration objects associated with the factory can be added or removed at any point. The main intent of a factory is to create an OSGi service for each configuration: adding a new Configuration entry results in a new OSGi service being registered, removing a Configuration, unregisters the service. Spring DM provides support for the managed service factory concept through the managed-service-factory element. Once defined, the configuration associated with the factory pid will automatically create (or remove) bean instances which will be registered (or unregistered) in the OSGi space based on a template bean definition and the CM configuration.

This might sound more complicated then it actually is, so let's look at a simplistic example:

<osgix:managed-service-factory id="simple-msf" 
   factory-pid="com.xyz.messageservice"                                                            
   auto-export="all-classes">                                                                      
	
   <bean class="com.xyz.MessageTank"/>                                                             
</osgix:managed-service-factory>

	factory persistent id (pid)
	Shortcut flag used to determine under what interfaces the OSGi service is published (more info below)
	bean definition template. For each detected configuration, a new service will be created using the bean definition template.

In its simplest form, the managed-service-factory requires the factory pid, a bean definition used as a template and some information on how possible bean instances are published as services. Basically, the definition above instructs Spring DM to to monitor the given factory pid (through a dedicated ManagedServiceFactory implementation (see the Compendium Spec for more info)) and for every Configuration object associated with the factory pid, to create a new, anonymous instance of the nested bean declared and export that instance as an OSGi service. The lifecycle of these beans instances is tied to the lifecycle of the associated Configuration objects. If a new configuration is added, a new bean is created and exported. If a configuration object is deleted or disassociated from the factory pid then the corresponding bean instance is destroyed.

In many regards, managed-service-factory acts as a specialized service exporter, similar to the service element but supporting the concept of managed properties. In fact, many of service's attributes that indicate how a bean is exported, are found in managed-service-factory (as you saw in the previous example with auto-export) as are the managed-properties attributes.

The list of attributes can be found below:

Similar to the service element, a list of interfaces or/and registration listeners can be declared to be notified when a service is being registered/unregistered. For more information on the semantics, please see Section 8.1.3, “Controlling The Set Of Advertised Service Interfaces For An Exported Service” and Section 8.1.10, “Service Registration And Unregistration Lifecycle” chapters.

Now that the managed-service-factory options have been explained, let's look at a more complex configuration:

<bean id="queueTracker" class="org.xyz.queue.QueueTracker"/>
			
<osgix:managed-service-factory id="data-msf" 
   factory-pid="org.xyz.labX"                                                                      
   update-strategy="bean-managed"                                                                  
   update-method="refresh">                                                                        
   <osgix:interfaces>
       <value>java.util.Collection</value>                                                         
       <value>java.util.Queue</value>                                                              
   </osgix:interfaces>
   <osgix:registration-listener ref="queueTracker"                                                 
       registration-method="track"                                                                 
       unregistration-method="untrack"/>                                                           
		
   <bean class="com.xyz.ResizableQueue">                                                           
       <property name="size" value="100"/>
       <property name="concurrency" value="10"/>
       <property name="fair" value="false"/>
   </bean>
</osgix:managed-service-factory>

	ManagedServiceFactory factory persistent id
	how should Spring DM behave when a Configuration is updated
	the method to invoke when for bean-managed updates
	the interfaces under which the nested beans are published as OSGi services
	listener notified when a service (based on the CM Configuration) is registered/unregistered
	custom (optional) service registration method
	custom (optional) service unregistration method
	bean definition template

The example above, creates a imaginary ResizeableQueue instance for each Configuration entry present under the org.xyz.labX factory pid. Each instance has default values assigned to size, concurrency and fair parameters. However, just like managed-properties, during the bean creation, the values received from the Configuration Admin will be injected by name, possibly overriding existing settings. Once created and configured, each nested, anonymous bean instance is registered as an OSGi service under the java.util.Collection and java.util.Queue interfaces. The OSGi service lifecycle is monitored by a registration listener, namely the bean queueTracker. Finally, due to the specified update-strategy, any updates executed to each CM configuration will cause the refresh callback to be invoked on the associated bean instance.

The simplest way to work directly with the configuration data stored under a given persistent id or factory persistent id, is to register a service that implements either the ManagedService or ManagedServiceFactory interface and specify the pid that you are interested in as a service property (for more information, see the Configuration Admin chapter in the OSGi compendium spec). For example:

<osgi:service interface="org.osgi.service.cm.ManagedService" ref="myManagedService">
   <osgi:service-properties>
     <entry key="service.pid" value="my.managed.service.pid"/>
   </osgi:service-properties>
</osgi:service>

<bean id="myManagedService" class="com.xyz.MyManagedService"/>

While the testing framework contains several classes that offer specific features, it is most likely that your test cases will extend org.springframework.osgi.test.AbstractConfigurableBundleCreatorTests (at least this is what we use in practice).

Let's extend this class and interact with the OSGi platform through the bundleContext field:

public class SimpleOsgiTest extends AbstractConfigurableBundleCreatorTests {

public void testOsgiPlatformStarts() throws Exception {
	System.out.println(bundleContext.getProperty(Constants.FRAMEWORK_VENDOR));
	System.out.println(bundleContext.getProperty(Constants.FRAMEWORK_VERSION));
	System.out.println(bundleContext.getProperty(Constants.FRAMEWORK_EXECUTIONENVIRONMENT));
	}
}

Simply execute the test as you normally do with any JUnit test. On Equinox 3.2.x, the output is similar to:

Eclipse
1.3.0
OSGi/Minimum-1.0,OSGi/Minimum-1.1,JRE-1.1,J2SE-1.2,J2SE-1.3,J2SE-1.4}

It is likely that you will see different log statements made by the testing framework during your own test execution, but these can be disabled as they only have an informative value and do not affect the actual execution.

Note that you did not have to create any bundle, write any MANIFEST or bother with imports or exports, let alone starting and shutting down the OSGi platform. The testing framework takes care of these automatically when the test is executed.

Let's do some quering and figure out what the environment in which the tests run is. A simple way to do that is to query the BundleContext for the installed bundles:

public void testOsgiEnvironment() throws Exception {
	Bundle[] bundles = bundleContext.getBundles();
	for (int i = 0; i < bundles.length; i++) {
		System.out.print(OsgiStringUtils.nullSafeName(bundles[i]));
		System.out.print(", ");
	}
	System.out.println();
}

The output should be similar to:

OSGi System Bundle, ObjectWeb ASM, log4j.osgi, spring-test, spring-osgi-test, spring-osgi-core, 
    spring-aop, spring-osgi-io, slf4j-api, 
spring-osgi-extender, etc... TestBundle-testOsgiPlatformStarts-com.your.package.SimpleOsgiTest, 

As you can see, the testing framework installs the mandatory requirements required for running the test such as the Spring, Spring DM, slf4j jars among others.

Besides the Spring DM jars and the test itself is highly likely that you depend on several libraries or your own code for the integration test.

Consider the following test that relies on Apache Commons Lang:

import org.apache.commons.lang.time.DateFormatUtils;
    ...
  	public void testCommonsLangDateFormat() throws Exception {
		System.out.println(DateFormatUtils.format(new Date(), "HH:mm:ssZZ"));
	}
}

Running the test however yields an exception:

java.lang.IllegalStateException: Unable to dynamically start generated unit test bundle
     ...
Caused by: org.osgi.framework.BundleException: The bundle could not be resolved. 
Reason: Missing Constraint: Import-Package: org.apache.commons.lang.time; version="0.0.0"
    ...
	... 15 more
	

The test requires org.apache.commons.lang.time package but there is no bundle that exports it. Let's fix this by installing a commons-lang bundle (make sure you use at least version 2.4 which adds the proper OSGi entries to the jar manifest).

One can specify the bundles that she wants to be installed using getTestBundlesNames or getTestBundles method. The first one returns an array of String that indicate the bundle name, package and versioning through as a String while the latter returns an array of Resources that can be used directly for installing the bundles. That is, use getTestBundlesNames when you rely on somebody else to locate (the most common case) the bundles and getTestBundles when you want to locate the bundles yourself.

By default, the test suite performs a lookup for artifacts, similar to the one used by Maven2, searching first the items as being relative to the current project and then falling back to the local repository. The locator expects the bundle String to be a comma separated values containing the artifact group, name, version and (optionally) type. It's likely that in the future, various other locators will be available. One can plug in their own locator through the org.springframework.osgi.test.provisioning.ArtifactLocator interface.

Let's fix our integration test by installing the required bundle (and some extra osgi libraries):

protected String[] getTestBundlesNames() {
	 return new String[] { "net.sourceforge.cglib, com.springsource.net.sf.cglib, 2.1.3",
	 	"javax.transaction, com.springsource.javax.transaction, 1.1.0",
	 	"commons-lang, commons-lang, 2.4" };
	 };
}

Rerunning the test should show that these bundles are now installed in the OSGi platform.

	Note
	The artifacts mentioned above have to exist in your local maven repository.

The testing framework allows a lot of customization to be made. This chapter details some of the existing hooks that you might want to know about. However, these are advanced topics as they increase the complexity of your test infrastructure.

protected Manifest getManifest() {
      // let the testing framework create/load the manifest
      Manifest mf = super.getManifest();
      // add Bundle-Classpath:
      mf.getMainAttributes().putValue(Constants.BUNDLE_CLASSPATH, ".,bundleclasspath/simple.jar");
      return mf;
}

protected String getManifestLocation() {
      return "classpath:com/xyz/abc/test/MyTestTest.MF";
}

Import-Package: junit.framework,
  org.osgi.framework,
  org.apache.commons.logging,
  org.springframework.util,
  org.springframework.osgi.service,
  org.springframework.osgi.util,
  org.springframework.osgi.test,
  org.springframework.context

Spring DM testing suite builds on top of Spring testing classes. To create an application context (OSGi specific), one should just override getConfigLocations[] method and indicate the location of the application context configuration. At runtime, an OSGi application context will be created and cached for the lifetime of the test case.

protected String[] getConfigLocations() {
   return new String[] { "/com/xyz/abc/test/MyTestContext.xml" };
}

The testing framework supports out of the box, three OSGi 4.0 implementations namely: Equinox, Knopflerfish and Felix. To be used, these should be in the test classpath. By default, the testing framework will try to use Equinox platform. This can be configured in several ways:

A built-in feature of the testing framework is the ability to wait until all dependencies are deployed before starting the test execution. Since the OSGi platforms are concurrent by nature, installing a bundle doesn't mean that all its services are running. By running a test before its dependency services are fully initialized can cause sporadic errors that pollute the test results. By default, the testing framework inspects all bundles installed by the user and, if they are Spring-powered bundles, waits until they are fully started (that is their application context is published as an OSGi service). This behaviour can be disabled by overriding shouldWaitForSpringBundlesContextCreation method. Consult AbstractSynchronizedOsgiTests for more details.

Considering all the functionality offered by the testing framework, one might wonder if this doesn't become a performance bottleneck. First, it's worth noting that all the work done automatically by the testing infrastructure has to be done anyway (such as creating the manifest or creating a bundle for the test or installing the bundles). Doing it manually simply does not work as it's too error prone and time consuming. In fact, the current infrastructure started as way to do efficient, automatic testing without worrying about deployment problems and redundancy.

As for the numbers, the current infrastructure has been used internally for the last half a year - our integration tests (around 120) run in about 3:30 minutes on a laptop. Most of this time is spent on starting and stopping the OSGi platform: the "testing framework" takes around 10% (as shown in our profiling so far). For example, the manifest generation has proved to take less then 0.5 seconds in general, while the jar creation around 1 second.

However, we are working on making it even faster and smarter so that less configuration options are needed and the contextual information available in your tests is used as much as possible. If you have any ideas or suggestion, feel free to use our issue tracker or/and forum.