Chapter 5. OSGi 4.2 Blueprint Container

Based on the Spring DM programming model, the OSGi Alliance introduced in OSGi 4.2 Release the Blueprint Container specification (part of the Compendium Service). Spring DM 2.0 serves as the Blueprint Reference Implementation - the official, complete implementation of the spec.

For this reason, users familiar with Spring DM, will find Blueprint very familiar and vice versa. In fact, we recommend that the Blueprint specification is used as a complement to this documentation. It should be mentioned that various aspects of Spring DM 1.x have been adjusted or slightly changed in 2.0, for consistency reason, to closely follow the Blueprint specification. As a general rule, unless mentioned otherwise, the Spring DM 2.x and Blueprint behaviour should be the same.

Existing and new users have the freedom to mix and match the programming model they want, since Spring DM 2.0 supports both the Spring/Spring DM 1.x declarations and the Blueprint one, inside the same application. That is, one can declare inside the same configuration, beans using both namespaces, at any point, without having to make an up-front choice.

Please note that this documentation will focus on Spring DM specific configurations and option; for Blueprint specific behaviour please refer to the OSGi 4.2 Compendium spec, section 121.

5.1. Blueprint Requirements

The Blueprint Container spec is part of the OSGi 4.2 release and relies on it, in its API. Thus, in order to use Blueprint, one must use an OSGi 4.2 compatible platform as a runtime environment. Spring DM itself requires only an OSGi 4.0 framework so if 4.2 is not an option, one can safely downgrade at the loss of the Blueprint model which can be built on top of Spring/Spring DM.

[Note]Note
On environments prior to OSGi 4.2, Spring DM will disable the Blueprint functionality automatically - users will be notified through a log message similar to the following:
Pre-4.2 OSGi platform detected; disabling Blueprint Container functionality

5.2. Blueprint/Spring DM Differences

There are a lot of similarities in terms of functionality and configuration between Spring DM 1.x and Blueprint which should be no surprise considering that DM was the basis of the Blueprint spec. In addition to fully supporting the Blueprint configuration schema, DM 2.x enhanced its declarations by providing option that allow for Blueprint specific behaviour. The table below aggregates the most important user facing differences between Spring/Spring DM configurations and Blueprint. Additional comparison information is available throughout the documentation (such as Section 7.2, “Blueprint Manifest Configuration Comparison” or Section 8.1.10.2, “Blueprint service Comparison”). Again, one can simply switch between the two definition styles, if need be.

5.2.1. XML Declarations

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.

Table 5.1. XML Configuration Differences

Element/AttributeSpring DMBlueprint
Namespace Declarationhttp://www.osgi.org/xmlns/blueprint/v1.0.0

http://www.springframework.org/schema/beans

or http://www.springframework.org/schema/osgi

Root Element<beans><blueprint>
Default Lazydefault-lazydefault-activation
Default Init Methoddefault-init-method-
Default Destroy Methoddefault-destroy-method-
Default Autowire Strategydefault-autowire, default-autowire-candidates-
Root Element<beans><blueprint>
Bean IDidid
Bean Name/Aliasname/<alias>-
Bean Classclassclass
Bean Scope Namescopescope
Built-in Scopessingleton, prototype, request, session, bundlesingleton, prototype
Lazy Initialization Name/Valueslazy-init=true/falseactivation=lazy/eager
Dependsdepends-ondepends-on
Init Methodinit-methodinit-method
Destroy Methoddestroy-methoddestroy-method
Factory Methodfactory-methodfactory-bean
Factory Beanfactory-beanfactory-ref
Bean Inheritanceparent-
Autowire Strategyautowire, autowire-candidate-
Constructor<constructor-arg><argument>
Property<property><property>
Value<value><value>
Service Exporter<service><service>
Service Importer<reference>/<list>/<set><reference>/<list>

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.

5.2.2. Container Capabilities

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:

Table 5.2. Container Capabilities Differences

FeatureSpring DMBlueprint
Object Instantiation
Constructor InstantiationYY
Static Factory InstantiationYY
Instance Factory InstantiationYY
Dependency Injection
Constructor InjectionYY
Setter InjectionYY
Field InjectionYN
Method InjectionYN
Arbitrary Method InjectionYN
AutowiringYN
Component Lifecycle
Lazy InitializationYY
Bean ScopesYY
Custom Bean ScopesYN
Built-in CallbacksYN
Custom CallbacksYY
Initialization ProcessingYN

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.

Note that additional information on Blueprint is available through out the documentation. These being said, it is highly recommended to read and use the Blueprint specification as guidance, if the Blueprint Container becomes the programming model of choice.

5.3. Using Blueprint

There are no extra jars or steps that need to be executed to enable the Blueprint functionality in Spring DM. This is built directly into the core, in fact the Blueprint APIs are exported by the Spring DM core. Please see the next section for information on how to install Spring DM and the OSGi compendium spec (section 121) for Blueprint related information such as bootstrapping and configuration locations. For those in a hurry, simply install and start the Spring DM jars (io, core, extender) and their dependencies (namely Spring and slf4j) and you should be all set: Spring DM will automatically detect the running environment and the types of bundles started.