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 specification download.

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. For more information, 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 by 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 that is provided by Apache Aries project is used to support Blueprint bundles that are contained in OSGi Applications for Liberty. For more information, 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 that is 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 by using OSGi service properties. The blueprint runtime does not parse the blueprint xml until NamespaceHandler services can be found for every custom namespace that is 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 that is running in Liberty, including Liberty Feature bundles , and OSGI Applications bundles.


Icon that indicates the type of topic Reference topic

File name: rwlp_blueprint_namespace_handler.html