## 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 2.0 serves as the Blueprint Reference Implementation - the official, complete implementation of the spec.

For this reason, users familiar with Gemini Blueprint, 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 Gemini Blueprint 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 Gemini Blueprint 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 Eclipse Gemini Blueprint supports both the 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 Gemini Blueprint specific configurations and option; 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
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/Attribute | Gemini Blueprint | Blueprint
--- | --- | ---
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 Lazy | `default-lazy` | `default-activation`
Default Init Method | `default-init-method` | `-`
Default Destroy Method | `default-destroy-method` | `-`
Default Autowire Strategy | `default-autowire`, `default-autowire-candidates` | `-`
Root Element | `<beans>` | `<blueprint>`
Bean ID | `id` | `id`
Bean Name/Alias | `name`/`<alias>` | `-`
Bean Class | `class` | `class`
Bean Scope Name | `scope` | `scope`
Built-in Scopes | `singleton`, `prototype`, `request`, `session`, `bundle` | `singleton`, `prototype`
Lazy Initialization Name/Values | `lazy-init`=`true/false` | `activation`=`lazy/eager`
Depends | `depends-on` | `depends-on`
Init Method | `init-method` | `init-method`
Destroy Method | `destroy-method` | `destroy-method`
Factory Method | `factory-method` | `factory-method`
Factory Bean | `factory-bean` | `factory-ref`
Bean Inheritance | `parent` | `-`
Autowire Strategy | `autowire`, `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:

    <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 Gemini Blueprint namespace.

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

Feature | Gemini Blueprint | Blueprint
--- | --- | ---
Object Instantiation
Constructor Instantiation | Y | Y
Static Factory Instantiation | Y | Y
Instance Factory Instantiation | Y | Y
Dependency Injection
Constructor Injection | Y | Y
Setter Injection | Y | Y
Field Injection | Y | N
Method Injection | Y | N
Arbitrary Method Injection | Y | N
Autowiring | Y | N
Component Lifecycle
Lazy Initialization | Y | Y
Bean Scopes | Y | Y
Custom Bean Scopes | Y | N
Built-in Callbacks | Y | N
Custom Callbacks | Y | Y
Initialization Processing | Y | N

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.

Prev | Home | Next
Part II. Reference Documentation | Sponsored by SpringSource | Chapter 7. Bundles and Application Contexts