Custom blueprint namespace handlers

The Blueprint Container specification, introduced in the OSGi Enterprise Specification Release 5, provides a simple and easy programming model for creating dynamic applications in the OSGi environment without adding complexity to the Java code.

For more information about the OSGi Enterprise Release specification, see OSGi Specifications. Stabilized feature: Support for OSGi applications is stabilized. Java Platform, Enterprise Edition (Java EE) 8 technologies are not enabled for OSGi applications and features that support OSGi development. As an alternative, develop applications using the Java Platform, Enterprise Edition (Java EE) or Microprofile features. For more information, see Stabilized Liberty features and feature capabilities.

The Blueprint Container specification defines a Dependency injection framework for OSGi. It is designed to handle the dynamic nature of OSGi, where services can become available and unavailable at any time. The specification is also designed to work with plain old Java objects (POJOs) so that the same objects can be used within and outside the OSGi framework. The Blueprint XML files that define and describe the various components of an application are key to the Blueprint programming model. The specification describes how the components get instantiated and wired together to form a running application.

See information about OSGi Blueprint Container Specification in the WebSphere Developer Tools documentation. Each blueprint bundle must contain a blueprint XML file in order for the blueprint runtime to process the blueprint component of the bundle. The standard blueprint element is defined by the OSGi blueprint specification, and required in every blueprint xml document. It sets the default document namespace to http://www.osgi.org/xmlns/blueprint/v1.0.0, for example:

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

Other namespaces can be added to the blueprint using standard XML rules, either as prefixed entries, or directly within the custom XML elements. These namespaces can be added either at the top-level or they can be inline with the custom XML elements. If it is valid XML, it is parsed correctly. For example, defined in the top-level blueprint element:

<blueprint 
  xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
  xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0">

For example, inline in a custom element:

<transaction method="*" value="Required"
  xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0"/>

The Blueprint runtime implementation provided by Apache Aries project is used to support Blueprint bundles that are contained in OSGi Applications for Liberty.

See Apache Aries. The Aries Blueprint runtime provides an extension mechanism called namespace handlers. A namespace handler provides a processor for custom blueprint extensions or namespaces. A namespace handler implements the org.apache.aries.blueprint.NamespaceHandler interface and must be registered in the OSGi service registry with an associated osgi.service.blueprint.namespace service property. This property denotes the namespace URIs this handler can process. For example: http://aries.apache.org/xmlns/transactions/v1.0.0. The service property value can either be a single String or URI, or a Collection, or an array of String or URI.

The blueprint runtime parses the blueprint descriptors twice. The first pass is fast, and finds only every namespace used by the blueprint bundle. If the blueprint bundle uses a non-standard namespace, then the blueprint container attempts to locate NamespaceHandler services in the OSGi service registry for each custom namespace. A NamespaceHandler service advertises every xml namespace that it can process using OSGi service properties. The blueprint runtime does not parse the blueprint xml until NamespaceHandler services can be found for every custom namespace used in the bundle. Unless NamespaceHandler services can be found for every custom namespace, the blueprint container is unable to process the bundle. This result can mean that the blueprint container waits indefinitely if no NamespaceHandler exists. If this situation is encountered, then the blueprint container issues a warning to the log. When the blueprint parser begins to parse the blueprint xml files, it parses any standard blueprint elements. When the parser reaches a custom element, the parser calls out to the NamespaceHandler that advertised support for the namespace of the custom element. Here, the NamespaceHandler has the opportunity to process the information in the custom element, modify the runtime blueprint model, or do any other operation. If there is a typing error in any of the namespace definitions, then the blueprint almost certainly fails to start.

A custom NamespaceHandler service can be provided by any bundle running in Liberty, including Liberty Feature bundles , and OSGI Applications bundles.