SCR 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.24.0 and make sure that you add a dependency to the annotations to your POM:
<dependency> <groupId>org.apache.felix</groupId> <artifactId>org.apache.felix.scr.annotations</artifactId> <version>1.12.0</version> </dependency>
The following annotations are supported:
The annotations itself do not support the new features from R6 or above. It is suggested to use the official OSGi annotations for Declarative Services instead.
@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:
ds
Default: true
SCR Descriptor: --
Metatype Descriptor: --
Whether Declarative Services descriptor is generated or not. If this parameter is not set or set to true the Declarative Services descriptor is generated in the service descriptor file for this component. Otherwise no Declarative Services descriptor is generated for this component.
specVersion
Default: 1.0
SCR Descriptor: --
Metatype Descriptor: --
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 specVersion attribute may be set to the correct version. Currently supported values for this attribute are 1.0 and 1.1. Since version 1.4.1 of the Maven SCR Plugin and version 1.0.1 of the SCR Annotations.
metatype
Default: false
SCR Descriptor: --
Metatype Descriptor: --
Whether Metatype Service data is generated or not. If this parameter is 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.
componentAbstract
Default: see description
SCR Descriptor: --
Metatype Descriptor: --
This marks an abstract service description which is not added to the descriptor but intended for reuse through inheritance. This attribute defaults to true for abstract classes and false for concrete classes.
inherit
Default: true
SCR Descriptor: --
Metatype Descriptor: --
Whether any service, property and reference declarations from base classes should be inherited by this class.
createPid
Default: true
SCR Descriptor: service.pid
Metatype Descriptor: --
Generate the service.pid property if non is declared.
name
Default: Fully qualified name of the Java class
SCR Descriptor: component.name
Metatype Descriptor: OCD.id
Defines the Component name also used as the PID for the Configuration Admin Service
enabled
Default: true
SCR Descriptor: component.enabled
Metatype Descriptor: --
Whether the component is enabled when the bundle starts
factory
Default: --
SCR Descriptor: component.factory
Metatype Descriptor: --
Whether the component is a factory component
immediate
Default: --
SCR Descriptor: component.immediate
Metatype Descriptor: --
Whether the component is immediately activated
policy
Default: OPTIONAL
SCR Descriptor: component.policy
Metatype Descriptor: --
The configuration policy for this component: OPTIONAL, IGNORE, or REQUIRE. This attribute is supported since version 1.4.0 of the plugin and requires a Declarative Service implementation 1.1 or higher.
label
Default: %<name>.name
SCR Descriptor: --
Metatype Descriptor: 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
Default: %<name>.name
SCR Descriptor: --
Metatype Descriptor: 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.
configurationFactory
Default: false
SCR Descriptor: --
Metatype Descriptor: Designate.factoryPid
Is this a configuration factory? (since 1.4.0)
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).
These annoations have no attribues.
@Service¶
The @Service annotation defines whether and which service interfaces are provided by the component. This is a class annotation.
This annotation 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:
value
Default: All implemented interfaces
SCR Descriptor: provide.interface
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 provide elements will be generated for all interfaces generated by the class
serviceFactory
Default: false
SCR Descriptor: service.servicefactory
Whether the component is registered as a ServiceFactory or not
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 annotation can be applied on the component class level or on a field defining a constant with the name of the property.
This annotation 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 attributes:
name
Default: The name of constant
SCR Descriptor: property.name
Metatype Descriptor: 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 if the field is of type String.
value
Default: --
SCR Descriptor: property.value
Metatype Descriptor: AD.default
The string value of the property. This can either be a single value or an array.
longValue
Default: --
SCR Descriptor: property.value
Metatype Descriptor: AD.default
The long value of the property. This can either be a single value or an array.
doubleValue
Default: --
SCR Descriptor: property.value
Metatype Descriptor: AD.default
The double value of the property. This can either be a single value or an array.
floatValue
Default: --
SCR Descriptor: property.value
Metatype Descriptor: AD.default
The float value of the property. This can either be a single value or an array.
intValue
Default: --
SCR Descriptor: property.value
Metatype Descriptor: AD.default
The int value of the property. This can either be a single value or an array.
byteValue
Default: --
SCR Descriptor: property.value
Metatype Descriptor: AD.default
The byte value of the property. This can either be a single value or an array.
charValue
Default: --
SCR Descriptor: property.value
Metatype Descriptor: AD.default
The char value of the property. This can either be a single value or an array.
boolValue
Default: --
SCR Descriptor: property.value
Metatype Descriptor: AD.default
The boolean value of the property. This can either be a single value or an array.
shortValue
Default: --
SCR Descriptor: property.value
Metatype Descriptor: AD.default
The short value of the property. This can either be a single value or an array.
label
Default: %<name>.name
SCR Descriptor: --
Metatype Descriptor: 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
Default: %<name>.description
SCR Descriptor: --
Metatype Descriptor: 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.
propertyPrivate
Default: Depending on the name
SCR Descriptor: --
Metatype Descriptor: 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
Default: Depends on property value(s)
SCR Descriptor: --
Metatype Descriptor: 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
Default: --
SCR Descriptor: --
Metatype Descriptor: See below
See below for a description of the options attribute.
Generating <properties> elements referring to bundle entries is not currently supported.
Multiple property annotations on the class level can be embedded in the @Properties annotation. For example:
@Properties({ @Property(name = "prop1", value = "value1"), @Property(name = "prop2", value = "value2") })
Naming the Property¶
It is important to carefully define the name of properties. By using a constant of the form
@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 refer to another constant.
The options Attribute¶
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.
The value of the options attribute is a list of @PropertyOptions annotations:
@Property(name = "sample", options = { @PropertyOption(name = "option1", value = "&option.label.1"), @PropertyOption(name = "option2", value = "&option.label.2") } )
The @PropertyOption's 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.
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: Name of the field
SCR Descriptor: reference.name
The local name of the reference. If the Reference annotation is declared in the class comment, this parameter is required. If the annotation is declared on a field, the default value for the name parameter is the name of the field
interfaceReference
Default: Type of the field
SCR Descriptor: 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 Reference annotation is declared on a class level, this parameter is required. If the annoation is declared on a field, the default value for the interfaceReference parameter is the type of the field
cardinality
Default: 1..1
SCR Descriptor: reference.cardinality
The cardinality of the service reference. This must be one of value from the enumeration ReferenceCardinality
policy
Default: static
SCR Descriptor: 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
Default: --
SCR Descriptor: 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
Default: See description
SCR Descriptor: 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
Default: See description
SCR Descriptor: 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
strategy
Default: event
SCR Descriptor: reference.strategy
The strategy used for this reference, one of event or lookup. If the reference is defined on a field with a strategy of event and there is no bind or unbind method, the plugin will create the necessary methods.