Versions Compared

Old Version 17

changes.mady.by.user Carsten Ziegeler

Saved on

compared with

New Version 18

changes.mady.by.user Carsten Ziegeler

Saved on

Key

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

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.

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

...

No Format
<dependency>
    <groupId>org.apache.felix</groupId>
    <artifactId>org.apache.felix.scr.annotations</artifactId>
    <version>1<version>0.09.0</version>
</dependency>

...

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

ds

true

no

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.

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 true for abstract classes and false for concrete classes.

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

no

component.immediate

Whether the component is immediately activated

inherit

true

no

Whether any service, property and reference declarations from base classes should be inherited by this class.

metatype

false

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.

createPid

true

no

service.pid

Generate the service.pid property if non is declared.

Abstract Service Descriptions

...

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. 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 This can either be a single value or an array.

longValue

type

String

no

property.typevalue

AD.typedefault

The type long value 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.

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.

...

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="bb0c247e-efb7-4cd0-8c76-58fd054dce34"><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.

  • 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
/** @scr.property @Property(value="default value" */)
static final String CONSTANT_NAME = "property.name";

and defining the scr.property tag 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 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.

...

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

ds

true

no

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.

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 true for abstract classes and false for concrete classes.

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

no

component.immediate

Whether the component is immediately activated

inherit

true

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 % sign to the name.

create-pid

true

no

service.pid

Generate the service.pid property if non is declared.

Abstract Service Descriptions

...

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="fd4c70cf-bea9-4da5-a4ef-37260f28f34e"><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. , 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.

...

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

See description

no

reference.bindunbind

The name of the method to be called when the service is to be bound to unbound from the component. The default value is the name created by appending the reference name to the string bind unbind. The method must be declared public or protected and take single argument which is declared with the service interface type

Notes:

  • If you define a reference on a field and there is no bind or 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

  • method, the plugin will create the necessary methods.

.h2 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 metatype flag 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.component tag. With the annotations the super class is required to have the Component annotation.
  • 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, intValue and so on). This is because of a limitation in the Java annotations which only allow typed parameters

Notes:

  • If you define a reference on a field and there is no bind or unbind method, the plugin will create the necessary methods.

.h2 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 metatype flag 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.