Page History

Introduction

In OSGi based systems functionality is mainly provided through services. Unlike traditional systems but comparable to Spring, a service is not reqiured to implement a framework defined interface. Instead services implement one or more interfaces, which stipulate the type of service provided. It is the lifetime of the bundle, which defines the lifetime of the service: A service object may be instantiated when the bundle is started and will automatically be removed when the bundle is stopped (and the service has not already been unregistered).

...

1. Declarative Services provides a means to define components (and services) through one or more XML files. Each component may get default configuration from its own definition.
2. The Configuration Admin Service provides functionality to provide configuration to components and services as well as to support management tools to update (and create) configuration data.
3. The Metatype Service provides a description suitable for management tools to manage configurations provided by the Configuration Admin Service. The descriptions of the data is provided in one or more XML files and associated languag binding files.

Maven Scr Plugin

Use

Support for automatic generation of the compenent and metadata descriptors is embeded in the org.apache.felix:maven-scr-plugin plugin. To use this plugin, it has to be declared in the project descriptor as a <plugin> element:

...

The plugin will look for component definition tags in all Java files found in the source directories of the project.

Using the descriptor

Currently the maven-scr-plugin only creates the component descriptor file. Adding the descriptor to the bundle and setting the Service-Component manifest header accordingly is a different task. However, if you're using the org.apache.felix:maven-bundle-plugin to construct the bundle and its manifest, then the maven-scr-plugin will add the following settings automatically for the org.apache.felix:maven-bundle-plugin (given default maven-scr-plugin configuration), so you don't have to configure this yourself:

...
<Include-Resource>
    src/main/resources,
    target/scr-plugin-generated
</Include-Resource>
<Service-Component>
  OSGI-INF/serviceComponents.xml
</Service-Component>
...

JavaDoc tags

The scr goal of the maven-scr-plugin looks for the following JavaDoc tags when building component descriptors:

...

scr.component

The scr.component tag is the only required tag. If this tag is not declared in the Java class comment, the class is not declared as a component.

...

scr.property

The scr.property tag defines properties which are made available to the component through the ComponentContext.getProperties() method. These tags are not strictly required but may be used by components to defined initial configuration. Additionally properties may be set here to identify the component if it is registered as a service, for example the service.description and service.vendor properties.

...

• Generating <properties> elements referring to bundle entries is not currently supported.

Naming the property

It is important to carefully define the name of properties. By using a constant of the form

...

and defining the scr.property tag on this constant, the name of the property is taken from the constant value. Thus it may easily be ensured, that both the property in the descriptor files and the property used by the implementation are actually the same.

The options parameter

Some properties may only be set to a set of possible values. To support user interfaces which provide a selection list of values or a list of checkboxes the option values and labels may be defined as parameters to the scr.property tag. All parameters in the form of name-value pairs occurring after the options parameter are used to build the list of available value options. The parameter name is used as the value while the parameter value is used as the label in the user interface. This label may be prepended with a % sign to localize the string.

...

Please note, that all parameters of the scr.property tag occurring after the options parameter are used to build the options list. Hence no non-option value parameters should actually follow the options parameter.

Multivalue properties

Generally the value of a property is scalar, that is a property has a single value such as true, 5 or "This is a String". Such scalar values are defined with the value parameter of the scr.property tag. In the case of a scalar property value, the cardinality parameter value is assumed to be 0 (zero) unless of course set otherwise.

...

scr.service

The scr.service tag defines whether and which service interfaces are provided by the component.

...

scr.reference

The scr.reference tag defines references to other services made available to the component by the Service Component Runtime. This tag

...

• It is not currently possible to declare a reference without bind or unbind methods.

Abstract Service Descriptions

If the scr.component tag contains the parameter abstract with a value of true, the containing class is regarded as an abstract class. It is not added to the service descriptor and the tags are not validated. The information about this class is added to the bundle. Classes from other bundles (or the same) can extends this abstract class and do not need to specify the references of the abstract class if they set the inherit parameter on the scr.component tag to true.

...