...
- 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
Excerpt Include Apache Felix Maven SCR Plugin Use
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 meta type file for all components found in the project.
The plugin may be configured with the following properties (Check the version column to make sure you use at least this version for the mentioned feature):
Property | Description | Version |
| The plugin will generate a descriptor for the Declarative Service version (either 1.0 or 1.1). If no value is specified, the plugin will detect the version and only use 1.1 if features from this version are used. | >= 1.4.0 |
| If this switch is turned on, the bind and unbind methods for unary references are automatically generated by the plugin. By default this is set to |
|
| If this switch is turned on, the java source code and its javadoc tags are scanned for the scr tags (see below). The default value is |
|
| If this switch is turned on, the java code is scanned for the scr annotations (see below). The default value is | >= 1.2.0 |
| Comma separated list of classes to exclude when processing the source. |
|
| The plugin distinguishes between errors and warnings. In strict mode warnings are treated as errors and cause the plugin to fail. The default value is |
|
| A map of predefined properties. These properties are set to each component (if the component does not define the property already). This is a map where the property name is made up by the included element name and the value is the value of the element. | >= 1.2.0 |
| The name of the descriptor file to create. This property defaults to the value of the |
|
| The name of the descriptor file to create. This property defauls to |
|
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:
No Format |
---|
...
<Include-Resource>
src/main/resources,
target/scr-plugin-generated
</Include-Resource>
<Service-Component>
OSGI-INF/serviceComponents.xml
</Service-Component>
...
|
Annotations
The maven-scr-plugin
uses the SCR
annotations from the corresponding subproject at Apache Felix. All annotations are in the org.apache.felix.scr.annotations
package. If you want to use the annotations in your project, you have to use a maven-scr-plugin
version >= 1.2.0 and make sure that you add a dependency to the annotations to your POM
:
No Format |
---|
<dependency>
<groupId>org.apache.felix</groupId>
<artifactId>org.apache.felix.scr.annotations</artifactId>
<version>1.2.0</version>
</dependency>
|
The following annotations are supported:
...
Apache Felix Maven SCR Plugin UseApache 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
...
Component
The Component
annotation is the only required annotation. If this annotation is not declared for a Java class, the class is not declared as a component.
This annotation 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 Component
annotation.
Supported attributes:
Name | Default Value | Required | SCR | Metatype | Description |
name | Fully qualified name of the Java class | no | | | Defines the Component name also used as the PID for the Configuration Admin Service |
ds | | no | – | – | Whether Declarative Services descriptor is generated or not. If this parameter is not set or set to |
specVersion | | no | – | – | Defines what Declarative Services specification the component is written against. Though the Maven SCR Plugin is very good at detecting whether components are written against the original or a newer specification, there are some cases, where the plugin may fail. For these cases, the |
componentAbstract | see description | no | – | – | This marks an abstract service description which is not added to the descriptor but intended for reuse through inheritance. This attribute defaults to |
enabled | | no | | – | Whether the component is enabled when the bundle starts |
factory | – | no | | – | Whether the component is a factory component |
immediate | – | no | | – | Whether the component is immediately activated |
inherit | | no | – | – | Whether any service, property and reference declarations from base classes should be inherited by this class. |
metatype | | no | – | – | Whether Metatype Service data is generated or not. If this parameter is set to |
label | | no | – | | This is generally used as a title for the object described by the meta type. This name may be localized by prepending a |
description | | no | – | | This is generally used as a description for the object described by the meta type. This name may be localized by prepending a |
createPid | | no | | – | Generate the |
configurationFactory | | no | – | | Is this a configuration factory? (since 1.4.0) |
The follwing attributes are supported since version 1.4.0 of the plugin and required a Declarative Service implementation 1.1:
policy | | no | component.policy | – | The configuration policy for this component: |
Abstract Service Descriptions
If the Component
annotations contains the attribute componentAbstract
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.
...
Activate
, Deactivate
, and Modified
The Declarative Service version 1.1 allows to specify the name for the activate, deactivate and modified method (see the spec for more information). The Activate
, Deactivate
, and Modified
annotation can be used to mark a method to be used for the specified purpose. However, as the DS specifies a method search algorithm, there are rare cases where the marked method is not used (if there is another method with the same name, but a different signature this might happen).
...
Service
The Service
annotation defines whether and which service interfaces are provided by the component. This is a class annotation.
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 attributes:
Name | Default Value | Required | Descriptor | Description |
value | All implemented interfaces | no | | The name of the service interface provided by the component. This can either be the fully qualified name or just the interface class name if the interface is either in the same package or is imported. If this property is not set |
serviceFactory | | no | | Whether the component is registered as a |
Omitting the Service
annotation will just define (and activate if required) the component but not register it as a service. Multiple Service
annotations may be declared each with its own value
. These annotations need to be wrapped into a Services
anotation. The component is registered as a ServiceFactory
if at least on Service
annotations declares the serviceFactory
attribute as true
.
...
Property
The Property
annotation 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 | | | 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 if the field is of type | ||
value | – | no | | | The string value of the property. This can either be a single value or an array. | ||
longValue | – | no | | | The long value of the property. This can either be a single value or an array. | ||
doubleValue | – | no | | | The double value of the property. This can either be a single value or an array. | ||
floatValue | – | no | | | The float value of the property. This can either be a single value or an array. | ||
intValue | – | no | | | The int value of the property. This can either be a single value or an array. | ||
byteValue | – | no | | | The byte value of the property. This can either be a single value or an array. | ||
charValue | – | no | | | The char value of the property. This can either be a single value or an array. | ||
boolValue | – | no | | | The boolean value of the property. This can either be a single value or an array. | ||
shortValue | – | no | | | The short value of the property. This can either be a single value or an array. | ||
label | | no | – | | The label to display in a form to configure this property. This name may be localized by prepending a | ||
description | | no | – | | A descriptive text to provide the client in a form to configure this property. This name may be localized by prepending a | ||
propertyPrivate | 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 | ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="fc4d5938-6c5e-4e58-9de2-9d4742a611b1"><ac:plain-text-body><![CDATA[ | cardinality | Depends on property value(s) | no | – | | Defines the cardinality of the property and its collection type. If the cardinality is negative, the property is expected to be stored in a | ]]></ac:plain-text-body></ac:structured-macro> |
options | – | no | – | See below | See below for a description of the |
- Generating
<properties>
elements referring to bundle entries is not currently supported. - Multiple property annotations can be embedded in the
Properties
annoation.
Naming the Property
It is important to carefully define the name of properties. By using a constant of the form
No Format |
---|
@Property(value="default value")
static final String CONSTANT_NAME = "property.name";
|
and defining the Property
annotation 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. In addition the value attribute can point to another constant.
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 Property
annotation. All parameters in the form of name-value pairs occurring after the options
attribute 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 Property
annotation 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 different value
attributes of the Property
annotation. 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 just by comma separate as the value of the annotation parameter.
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 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.
...
Reference
The Reference
annotation defines references to other services made available to the component by the Service Component Runtime.
This annotation may be declared on a Class level or any Java field to which it might apply. Depending on where the annotation is declared, the parameters may have different default values.
This annotation 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 | | The local name of the reference. If the |
interface | Type of the field | yes | | 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 |
cardinality | | no | | The cardinality of the service reference. This must be one of value from the enumeration |
policy | | no | | The dynamicity policy of the reference. If |
target | – | no | | 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 | | 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 |
unbind | See description | no | | 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 |
strategy | | no | | The strategy used for this reference, one of |
---|
Notes:
- If you define a reference on a field with a strategy of
event
and there is no bind or unbind method, the plugin will create the necessary methods.
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 | | | Defines the Component name also used as the PID for the Configuration Admin Service |
ds | | no | – | – | Whether Declarative Services descriptor is generated or not. If this parameter is not set or set to |
abstract | see description | no | – | – | This marks an abstract service description which is not added to the descriptor but intended for reuse through inheritance. This attribute defaults to |
enabled | | no | | – | Whether the component is enabled when the bundle starts |
factory | – | no | | – | Whether the component is a factory component |
immediate | – | no | | – | Whether the component is immediately activated |
inherit | | no | – | – | Whether any service, property and reference declarations from base classes should be inherited by this class. |
metatype | | no | – | – | Whether Metatype Service data is generated or not. If this parameter is not set or set to |
label | | no | – | | This is generally used as a title for the object described by the meta type. This name may be localized by prepending a |
description | | no | – | | This is generally used as a description for the object described by the meta type. This name may be localized by prepending a |
create-pid | | no | | – | Generate the |
configurationFactory | | no | – | | Is this a configuration factory? (since 1.4.0) |
The follwing attributes are supported since version 1.4.0 of the plugin and required a Declarative Service implementation 1.1:
policy | | no | component.policy | – | The configuration policy for this component: |
activate | | no | component.activate | – | The name of the component activation method. |
deactivate | | no | component.deactivate | – | The name of the component deactivation method. |
modified | – | no | component.modified | – | The name of the component modified method. |
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.
...
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 | | | 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 if the field is of type | ||
value | – | no | | | The value of the property. If the property type is not | ||
type | | no | | | The type of the property value. This must be one of | ||
label | | no | – | | The label to display in a form to configure this property. This name may be localized by prepending a | ||
description | | no | – | | A descriptive text to provide the client in a form to configure this property. This name may be localized by prepending a | ||
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 | ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="f55706f3-dbc9-456f-b428-9d5967c80c82"><ac:plain-text-body><![CDATA[ | cardinality | Depends on property value(s) | no | – | | Defines the cardinality of the property and its collection type. If the cardinality is negative, the property is expected to be stored in a | ]]></ac:plain-text-body></ac:structured-macro> |
options | – | no | – | See below | See below for a description of the | ||
values* | – | no | – | See below | See below for a description of parameters starting with | ||
valueRef | – | no | – | | A constant containing the value for this property. The constant can either be declared in the same class as this property or in any class that is imported. The type of the property is derived from the constant. | ||
valueRefs | – | no | – | See below | Same as the |
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 name of the service interface provided by the component. This can either be the fully qualified name or just the interface class name if the interface is either in the same package or is imported. 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 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 | | The local name of the reference. If the |
interface | Type of the field | yes | | 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 |
cardinality | | no | | The cardinality of the service reference. This must be one of |
policy | | no | | The dynamicity policy of the reference. If |
target | – | no | | 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 | | 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 |
unbind | See description | no | | 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 |
strategy | | no | | The strategy used for this reference, one of |
---|
Notes:
- If you define a reference on a field with the strategy
event
and there is no bind or unbind method, the plugin will create the necessary methods.
Differences between JavaDoc tags and annotations
...