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="http://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 declared inline within 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
declared inline within 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.