THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
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.
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).
...
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 SCR Plugin helps in the generation of these files by means of JavaDoc tags embedded in the Java source code of the components.
...
- 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
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:
| No Format |
|---|
<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 OSGI-INF/metatype/metatype.xml file for all components found in the project.
The plugin may be configured with the following properties:
Property | Description |
| The name of the descriptor file to create. This property defaults to the value of the |
Note: The name and location of the Metatype descriptor may not be changed as the OSGi Metatype Service Specification prescribes the location of the descriptors and there is no use in providing functionality to define a custom descriptor file name.
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:
| No Format |
|---|
...
<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.
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:
...
Name
...
Default Value
...
Required
...
SCR
...
Metatype
...
Description
...
name
...
Fully qualified name of the Java class
...
no
...
component.name
...
OCD.id
...
Defines the Component name also used as the PID for the Configuration Admin Service
...
abstract
...
false
...
no
...
This marks an abstract service description which is not added to the descriptor but intended for reuse through inheritance
...
enabled
...
true
...
no
...
component.enabled
...
Whether the component is enabled when the bundle starts
...
factory
...
no
...
component.factory
...
Whether the component is a factory component
...
immediate
...
true
...
no
...
component.immediate
...
Whether the component is immediately activated
...
inherit
...
false
...
no
...
Whether any service, property and reference declarations from base classes should be inherited by this class.
...
metatype
...
true
...
no
...
Whether Metatype Service data is generated or not. If this parameter is not set or set to true Metatype Service data is generated in the metatype.xml file for this component. Otherwise no Metatype Service data is generated for this component.
...
label
...
%<name>.name
...
no
...
OCD.name
...
This is generally used as a title for the object described by the meta type. This name may be localized by prepending a % sign to the name.
...
description
...
%<name>.name
...
no
...
OCD.description
...
This is generally used as a description for the object described by the meta type. This name may be localized by prepending a % sign to the name.
...
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:
...
Name
...
Default Value
...
Required
...
SCR
...
Metatype
...
Description
...
name
...
The name of constant
...
yes
...
property.name
...
AD.id
...
The name of the property. If this tag is defined on a field with an initialization expression, the value of that expression is used as the name.
...
value
...
no
...
property.value
...
AD.default
...
The value of the property. If the property type is not String, parsing of the value is done using the valueOf(String) method of the class defined by the property type
...
type
...
String
...
no
...
property.type
...
AD.type
...
The type of the property value. This must be one of String, Long, Double, Float, Integer, Byte, Char, Boolean and Short.
...
label
...
%<name>.name
...
no
...
AD.name
...
The label to display in a form to configure this property. This name may be localized by prepending a % sign to the name.
...
description
...
%<name>.description
...
no
...
AD.description
...
A descriptive text to provide the client in a form to configure this property. This name may be localized by prepending a % sign to the name.
...
private
...
Depending on the name
...
no
...
See description
...
Boolean flag defining whether a metatype descriptor entry should be generated for this property or not. By default a metatype descriptor entry, i.e. an AD element, is generated except for the properties service.pid, service.description, service.id, service.ranking, service.vendor, service.bundlelocation and service.factoryPid. If a property should not be available for display in a configuration user interface, this parameter should be set to true.
...
cardinality
...
Depends on property value(s)
...
no
...
AD.cardinality
...
Defines the cardinality of the property and its collection type. If the cardinality is negative, the property is expected to be stored in a java.util.Vector (primitive types such as boolean are boxed in the Wrapper class), if the cardinality is positive, the property is stored in an array (primitve types are unboxed, that is Boolean type values are stored in boolean[]). The actual value defines the maximum number of elements in the vector or array, where Integer.MIN_INT describes an unbounded Vector and Integer.MAX_INT describes an unbounded array. If the cardinality is zero, the property is a scalar value. If the defined value of the property is set in the value attribute, the cardinality defaults to 0 (zero for scalar value). If the property is defined in one or more properties starting with values, the cardinality defaults to Integer.MAX_INT, that is an unbounded array.
...
options
...
no
...
See below
...
See below for a description of the options parameter.
...
values*
...
no
...
See below
...
See below for a description of parameters starting with values.
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
| No Format |
|---|
/** @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:
Name | Default Value | Required | Descriptor | Description |
interface | All implemented interfaces | no | | The fully qualified name of the service interface provided by the component. If this property is not set |
servicefactory | | no | | Whether the component is registered as a |
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:
...
Name
...
Default Value
...
Required
...
Descriptor
...
Description
...
name
...
Name of the field
...
yes
...
reference.name
...
The local name of the reference. If the scr.reference tag is declared in the class comment, this parameter is required. If the tag is declared in the field comment, the default value for the name parameter is the name of the field
...
interface
...
Type of the field
...
yes
...
reference.interface
...
The name of the service interface. This name is used by the Service Component Runtime to access the service on behalf of the component. If the scr.reference tag is declared in the class comment, this parameter is required. If the tag is declared in the field comment, the default value for the interface parameter is the type of the field
...
cardinality
...
1..1
...
no
...
reference.cardinality
...
The cardinality of the service reference. This must be one of 0..1, 1..1, 0..n, and 1..n
...
policy
...
static
...
no
...
reference.policy
...
The dynamicity policy of the reference. If dynamic the service will be made available to the component as it comes and goes. If static the component will be deactivated and re-activated if the service comes and/or goes away. This must be one of static and dynamic
...
target
...
no
...
reference.target
...
A service target filter to select specific services to be made available. In order to be able to overwrite the value of this value by a configuration property, this parameter must be declared. If the parameter is not declared, the respective declaration attribute will not be generated
...
bind
...
See description
...
no
...
reference.bind
...
The name of the method to be called when the service is to be bound to the component. The default value is the name created by appending the reference name to the string bind. The method must be declared public or protected and take single argument which is declared with the service interface type
...
unbind
...
See description
...
no
...
reference.unbind
...
The name of the method to be called when the service is to be unbound from the component. The default value is the name created by appending the reference name to the string unbind. The method must be declared public or protected and take single argument which is declared with the service interface type
Notes:
- It is not currently possible to declare a reference without
bindorunbindmethods.
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.
...
Apache Felix Maven SCR Plugin UseExcerpt Include Apache Felix Maven SCR Plugin Use Apache Felix Maven SCR Plugin Use nopanel true
Apache Felix SCR Ant Task UseExcerpt Include Apache Felix SCR Ant Task Use Apache Felix SCR Ant Task Use nopanel true
SCR AnnotationsExcerpt Include SCR Annotations SCR Annotations nopanel true
SCR JavaDoc TagsExcerpt Include SCR JavaDoc Tags SCR JavaDoc Tags nopanel true
Extending SCR AnnotationsExcerpt Include Extending SCR Annotations Extending SCR Annotations nopanel true
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:
- 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 theComponentannotation. - 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
shortValue,intValueand so on). This is because of a limitation in the Java annotations which only allow typed parameters.