Apache Felix Maven SCR Plugin
The Apache Felix Maven SCR Plugin is a great tool to ease the development of OSGi components and services. Components and services are defined through annotations and the plugin creates the necessary descriptors for the OSGi Declarative Services, Config Admin and Metatype services. Starting with version 1.4.0 of the plugin, OSGi Declarative Services versions 1.0 and 1.1 are supported.
Make sure to see the FAQ for known problems.
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
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.
- 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.
- 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.
- 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.
Where to go from here
- Using the Apache Felix Maven SCR Plugin to generate Declarative Services and Metatype Service descriptors during a Maven Build
- Using the Apache Felix SCR Ant Task to generate Declarative Services and Metatype Service descriptors during an Ant driven Build.
- Using Java 5 Annotations to describe the component or service.
- Using JavaDoc Tags to describe the component or service.
- How add new Annotations extending the base Annotations
Differences between JavaDoc tags and annotations
In general both mechanisms provide the same functionality. There are some subtle difference which are listed in this section:
- JavaDoc tags are not supported in recent versions of the plugin. New features will only be implemented as annotations.
- While the
metatypeflag is turned on by default for the JavaDoc tags, the default for the annotations is to generate no metadata. The reason for this is, that it turned out that services with metadata are less often used.
- The JavaDoc support adds properties and references from super classes if the source is in the same module to a component even if the super class does not have the
@scr.componenttag. With the annotations the super class is required to have the
- Property values are handled differently. While the JavaDoc version has an auto detection of types together with an explicit type parameter, the annotations version has several attributes. Each type has its own attribute (like
intValueand so on). This is because of a limitation in the Java annotations which only allow typed parameters.