Versions Compared

Old Version 33

changes.mady.by.user Carsten Ziegeler

Saved on

compared with

New Version 34

changes.mady.by.user Felix Meschberger

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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:

noformat
Code Block
xml
xml
<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>

...

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:

Code Blocknoformat
xml
xml
...
<Include-Resource>
    src/main/resources,
    target/scr-plugin-generated
</Include-Resource>
<Service-Component>
  OSGI-INF/serviceComponents.xml
</Service-Component>
...

...

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:

noformat
Code Block
xml
xml
<dependency>
    <groupId>org.apache.felix</groupId>
    <artifactId>org.apache.felix.scr.annotations</artifactId>
    <version>1.2.0</version>
</dependency>

...

...

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.

...

policy

OPTIONAL

no

component.policy

–

The configuration policy for this component: OPTIONAL, IGNORE, or REQUIRE

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.

...

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).anchorscran.servicescran.service

Service

The Service annotation defines whether and which service interfaces are provided by the component. This is a class annotation.

...

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. Anchorscran.propertyscran.property

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.

...

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 if the field is of type String.

value

–

no

property.value

AD.default

The string value of the property. This can either be a single value or an array.

longValue

–

no

property.value

AD.default

The long value of the property. This can either be a single value or an array.

doubleValue

–

no

property.value

AD.default

The double value of the property. This can either be a single value or an array.

floatValue

–

no

property.value

AD.default

The float value of the property. This can either be a single value or an array.

intValue

–

no

property.value

AD.default

The int value of the property. This can either be a single value or an array.

byteValue

–

no

property.value

AD.default

The byte value of the property. This can either be a single value or an array.

charValue

–

no

property.value

AD.default

The char value of the property. This can either be a single value or an array.

boolValue

–

no

property.value

AD.default

The boolean value of the property. This can either be a single value or an array.

shortValue

–

no

property.value

AD.default

The short value of the property. This can either be a single value or an array.

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.

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

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="206c482a89a46955-d5adcea2-4f874ace-bb99aec4-5d785a263025645a92eeb371"><ac:plain-text-body><![CDATA[

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.

]]></ac:plain-text-body></ac:structured-macro>

options

–

no

–

See below

See below for a description of the options attribute.

...

It is important to carefully define the name of properties. By using a constant of the form

noformat
Code Block
xml
xml
@Property(value="default value")
static final String CONSTANT_NAME = "property.name";

...

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. Anchorscran.referencescran.reference

Reference

The Reference annotation defines references to other services made available to the component by the Service Component Runtime.

...

...

scr.component

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 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. Anchorscr.propertyscr.property

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.

...

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 if the field is of type String.

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.

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="573d10682897bc86-42aa7bfb-49f84a10-8e1bbd65-b3cc19fe71ffa536a0eed503"><ac:plain-text-body><![CDATA[

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.

]]></ac:plain-text-body></ac:structured-macro>

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.

valueRef

–

no

–

AD.default

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 values attribute with the difference that it acts like the valueRef attribute and the value points to a constants defining the multi value for the property.

...

It is important to carefully define the name of properties. By using a constant of the form

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

...

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. Anchorscr.servicescr.service

scr.service

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

...

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. Anchorscr.referencescr.reference

scr.reference

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

...