Maven Scr Plugin (Sandbox)

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).

Usually, the functionality of a bundle - be it the packages exported or be it the services provided - is made available to the rest of the system, when the bundle is started. To give the bundle a change to take action, a bundle may declare a BundleActivator class in the Bundle-Activato manifest header of the bundle. When the bundle is started, the start(BundleContext) method is called, while the stop(BundleContext) method is called when the bundle is stopped. These methods are one place to instantiate and register services with the service registry.

The drawback of this method of service registration is that the services have to acquire other services whose functionality is used themselves and also have to observe the presence as services may come and go at any time. Though this observation is rather easy as basically a ServiceListener is to be implemented which listens for service registration and unregistration events, this is somewhat tedious and repeating for each service using other services.

To overcome this situation, the OSGi Service Platform Compendium Specification provides the Declarative Services Specification. This specification enables the declaration of services in configuration files, which are read by the Declarative Services Runtime to observe dependencies and activate (register) and deactivate (unregister) services depending on whether requirements can be met. Additionally, the dependencies may be supplied through declared methods. The specification calls a class declared this way a component. A component may or may not be a service registered with the service registry.

Components are declared using XML configuration files contained in the respective bundle and listed in the Service-Component bundle manifest header. These configuration files may be handwritten and registered. To support automatic generation of the component descriptors, the Maven Scr Plugin helps in the generation of these files by means of JavaDoc tags embedded in the Java source code of the components.

Related to declarative services is configuration support. To support configuration of services and components, OSGi provides the Configuration Admin Service Specification. This specification defines a service, which is the center of providing configuration to services and components. As such the Configuration Admin Service cares for storing configuration and deliver the configuration automatically or on-demand to clients. Configuration objects are identified by so-called Persistent Identifiers (PID) and are bound to bundles when used. For services implementing the special ManagedService or ManagedServiceFactory interfaces the PID has to be provided in the service properties as a property with the name service.pid. For Declarative Services, the name of the component is used as the PID to retrieve the configuration from the Configuration Admin Service.

The Configuration Admin Service not only allows components to get or retrieve configuration, it also provides the entry point for Management Agents to retrieve and update configuration data. To help building Management Agents the OSGi Metatype Service Specification defines a descripton model which may be used to describe data used by components and services. The configuration properties and meta type description for a given PID together are used to build the user interface to configure the service and/or component.

To summarize:

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:

<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-scr-plugin</artifactId>
        <executions>
          <execution>
            <id>generate-scr-scrdescriptor</id>
            <goals>
              <goal>scr</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

The scr goal is bound to the generate-resources phase and will generate a single descriptor file as well as meta type file for all components found in the project.

The plugin may be configured with the following properties:

The meta type file is generated in the OSGI-INF/metatype/ directory and the scr descriptor file in the OSGI-INF directory.

Note: The location of the meta type descriptor may not be changed as the OSGi Metatype Service Specification prescribes the location of the descriptors.

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
• scr.property
• scr.service
• scr.reference

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.

This tag is used to declare the <component> element of the component declaration. See section 112.4.3, Component Element, in the OSGi Service Platform Service Compendium Specification for more information. The required <implementation> element is automatically generated with the fully qualified name of the class containing the scr.component tag.

Supported parameters:

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.

This tag may be defined in the Java Class comment of the component or in a coment to a field defining a constant with the name of the property.

This tag is used to declare <property> elements of the component declaration. See section 112.4.5, Properties and Property Elements, in the OSGi Service Platform Service Compendium Specification for more information.

Supported parameters:

Notes:

• 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

/** @scr.property value="default value" */
static final String CONSTANT_NAME = "property.name";

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.

The options are written to the metatype.xml file as Option elements inside the AD element defining the property. The name of the parameter will be used for the Option.value attribute while the value of the parameter defines the Option.label attribute.

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.

There may be properties, which have a list of values, such as a list of possible URL mappings for an URL Mapper. Such multiple values are defined in one more parameters whose name starts with values. Each parameter must of course have a unique name which is not in any except to differentiate the parameters.

If the cardinality of the property is not explicilty set with the cardinality property, it defaults to Integer.MAX_INT, i.e. unbound array, if multiple values with a series of values parameters are defined. Otherwise the cardinality parameter may be set for example to a negative value to store the values in a java.util.Vector instead.

scr.service

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

This tag is expected in the Java Class comment of the component.

This tag is used to declare <service> and <provide> elements of the component declaration. See section 112.4.6, Service Elements, in the OSGi Service Platform Service Compendium Specification for more information.

Supported parameters:

Omitting the scr.service tag will just define (and activate if required) the component but not register it as a service. Multiple scr.service tags may be declared each with its own interface. The component is registered as a ServiceFactory if at least on scr.service tag declares the servicefactory parameter as true.

scr.reference

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

This tag may be declared in the java Class comment or any Java Field to which it might apply. Depending on where the tag is declared, the parameters may have different default values.

This tag is used to declare <reference> elements of the component declaration. See section 112.4.7, Reference Element, in the OSGi Service Platform Service Compendium Specification for more information.

Supported parameters:

Notes:

• 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.

This allows to create abstract classes which already provide some valuable functionality without having to deal with the details like reference definitions in each and every subclass.