Chapter 6. OSGi 4.2 Blueprint Container

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

Existing and new users have the freedom to mix and match the programming model they want, since Eclipse Gemini Blueprint supports both the Spring DM 1.x declarations and the Blueprint one, inside the same application, provided the default namespace is Blueprint and the Blueprint files are stored in the folder META-INF/spring.

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

6.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. Gemini Blueprint 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/Gemini Blueprint.

[Note]Note
On environments prior to OSGi 4.2, Gemini Blueprint 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

6.2. Blueprint/Gemini Blueprint Differences

There are a lot of similarities in terms of functionality and configuration between Gemini Blueprint 1.x and Blueprint which should be no surprise considering that Spring 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/Gemini Blueprint configurations and Blueprint. Additional comparison information is available throughout the documentation (such as Section 8.2, “Blueprint Manifest Configuration Comparison” or Section 9.1.10.2, “Blueprint service Comparison”). Again, one can simply switch between the two definition styles, if need be.

6.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, Gemini Blueprint, 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 6.1. XML Configuration Differences

Element/AttributeGemini BlueprintBlueprint
Namespace Declaration

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

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

http://www.osgi.org/xmlns/blueprint/v1.0.0
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-method
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 Gemini Blueprint one can mix and match the namespaces provided the default namespace is Blueprint and the Blueprint files are stored in the folder META-INF/spring:

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
  xmlns:beans="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  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">
       
    <beans:bean id="anInteger" class="java.lang.Integer">
      <beans:constructor-arg value="10"/>
    </beans:bean>
    
    <service ref="anInteger" interface="java.lang.Comparable" />
</blueprint>

The example above uses the Gemini Blueprint and Spring beans namespaces.

6.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 6.2. Container Capabilities Differences

FeatureGemini BlueprintBlueprint
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 Gemini Blueprint 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.

6.3. Using Blueprint

There are no extra jars or steps that need to be executed to enable the Blueprint functionality in Gemini Blueprint. This is built directly into the core, in fact the Blueprint APIs are exported by the Gemini Blueprint core. Please see the next section for information on how to install Gemini Blueprint 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 Gemini Blueprint jars (io, core, extender) and their dependencies (namely Spring and slf4j) and you should be all set: Gemini Blueprint will automatically detect the running environment and the types of bundles started.