Blueprint XML

A Blueprint XML file is identified by a top-level blueprint element and contains definitions of component managers such as a bean manager, a service manager, and service reference managers.

A Blueprint XML file is identified by a top-level Blueprint element, as shown in the following blueprint.xml example code.

<?xml version="1.0" encoding="UTF-8"?> 
<blueprint xmlns="https://www.osgi.org/xmlns/blueprint/v1.0.0">
   ... 
</blueprint>

The XML namespace identifies that the document conforms to the Blueprint version 1.0.0. The top-level Blueprint element identifies the document as a Blueprint module definition.

The Blueprint XML file contains definitions of various component managers. The Blueprint Container specification defines four main component managers:
  • A bean manager creates an instance of a Java™ object with the given arguments and properties. A bean manager can create single or multiple object instances, depending on the scope settings. It can also manage the life cycle of an object and notify it when all properties have been injected or when it is being destroyed.
  • A service manager registers and unregisters a service in the OSGi service registry.
  • Two service reference managers provide access to the services registered in the OSGi service registry:
    • A reference manager provides an object that is a proxy to the service that is registered in the service registry.
    • A reference-list manager provides a dynamic list of either service proxy objects or service reference objects that are currently in the service registry.
Each component manager creates components and manages the life cycle of those components. When requested, the managers provide a component instance. Each manager has a corresponding XML element that describes the manager properties. The managers can be top-level managers or they can be defined by using inline declarations in other manager definitions. All component managers can have the following attributes:
id
This optional attribute defines the ID of a top-level manager. The ID must be unique for all top-level managers in the Blueprint Container. If you do not specify this attribute, a unique ID is generated automatically. Managers use the ID to refer to each other. For example, during injection, the manager asks the referenced managers to provide an object that is injected into the component that the manager is creating.

You do not set the id attribute for managers that are defined by using inline declarations in other manager definitions, because these managers are considered to be anonymous.

activation
This optional attribute defines the activation mode of the manager. The following activation modes are supported:
  • eager. The manager is activated during initialization of the Blueprint Container. This is the default.

    A service manager is published into the service registry and activates the bean manager that underlies the service.

  • lazy. The manager is activated on demand. A manager is activated when it is requested to provide its first component instance.

    For a bean manager, the bean is instantiated only when another bean manager first accesses it. For a service manager, the service manager is published into the service registry, but it does not activate the bean manager that underlies the service.

To change the default activation mode for all managers in the Blueprint XML file, set the default-activation attribute on the Blueprint element.

Each manager has its own activation and deactivation steps. A manager is deactivated when the Blueprint Container is destroyed.

dependsOn
This optional attribute defines the explicit dependencies of a manager. It specifies a list of manager IDs, where those managers must be activated before this manager is activated. A manager can also have implicit dependencies, which are defined by the references to other managers in a manager definition.