Apache Felix 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:

<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-scr-plugin</artifactId>
        <version>1.9.0</version>
        <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):

specVersion
Default: Automatically detected
Since: 1.4.0
The plugin will generate a descriptor for the Declarative Service version (e.g. 1.0, 1.1, or 1.2). If no value is specified, the plugin will detect the version and only use 1.1 if features from this version are used.

generateAccessors
Default: true
Since:
If this switch is turned on, the bind and unbind methods for unary references are automatically generated by the plugin.

processAnnotations
Default: true
Since: 1.2.0
If this switch is turned on, the java code is scanned for the scr annotations (see below).

sourceIncludes
Default: true
Since: 1.7.4
Comma separated list of classes to include when processing the source.

sourceExcludes
Default: true
Since:
Comma separated list of classes to exclude when processing the source.

strictMode
Default: false
Since:
The plugin distinguishes between errors and warnings. In strict mode warnings are treated as errors and cause the plugin to fail.

properties
Default: None
Since: 1.2.0
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.

finalName
Default: serviceComponents.xml or scr.descriptor.name system property
Since: 1.0.0
The name of the descriptor file to create. This property only applies if the generateSeparateDescriptors is set to false.

metaTypeName
Default: metatype.xml
Since: 1.0.0
The name of the descriptor file to create.

outputDirectory
Default: ${project.build.directory}/scr-plugin-generated
Since: 1.0.0
The directory where all files are generated in.

generateSeparateDescriptors
Default: true
Since: 1.9.0
If set to false, a single descriptor will be created.

supportedProjectTypes
Default: jar, bundle
Since: 1.8.0
Project types which this plugin supports.

scanClasses
Default: false
Since: 1.9.0
By default the plugin scans the java source tree, if this is set to true, the generated classes directory is scanned instead.

The Metatype file is generated in the OSGI-INF/metatype/ directory and the Declarative Services descriptor file in the OSGI-INF directory.

Note: The location of the Metatype 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 unless the scanClasses property indicates the class files are to be scanned instead. This is usefull if the annotations are actually defined in JVM-based languages such as Groovy or Scala.

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:

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