Apache Felix Maven SCR Plugin Use

The Apache Felix SCR Tooling is not supported anymore. Please use the official OSGi annotations and bnd based tooling instead.

Using the Apache Felix Maven SCR Plugin to generate Declarative Services and Metatype Service descriptors during a Maven Build

Support for automatic generation of the component and metadata descriptors is embedded 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.25.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 separate descriptor file for each component as well as a separate meta type file for each component which has metatype support enabled in the project.

However, in order to be able to process annotations, a dependency to an annotation processor needs to be added as well. There are two sets of annotations: the standard annotations as defined in the Declarative Services specification and the annotations defined in the Apache Felix project. If you want to use the annotations from the Apache Felix project, add this dependency to your pom:

 <project>
   ...
   <dependencies>
     ...
     <dependency>
          <groupId>org.apache.felix</groupId>
          <artifactId>org.apache.felix.scr.annotations</artifactId>
          <version>1.12.0</version>
          <scope>provided</scope>
     </dependency>
     ...
   </dependencies>
   ...
 </project>

If you want to process the standard annotations with the maven-scr-plugin add this dependency:

 <project>
   ...
   <dependencies>
     ...
     <dependency>
          <groupId>org.apache.felix</groupId>
          <artifactId>org.apache.felix.scr.ds-annotations</artifactId>
          <version>1.2.10</version>
          <scope>provided</scope>
     </dependency>
     ...
   </dependencies>
   ...
 </project>

These dependencies need to be specified in order to have an easy way to opt-out the processing of one set or use other tools to process them. It’s possible to specify both dependencies and use both annotations within a single project (however it’s better to stay with one set). 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 Default Since Description

Property	Default	Since	Description
`specVersion`	Automatically detected	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`	`true`		If this switch is turned on, the bind and unbind methods for unary references are automatically generated by the plugin.
`scanClasses`	`false`	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.
`sourceIncludes`	`true`	1.7.4	Comma separated list of classes to include when processing the source.
`sourceExcludes`	`true`		Comma separated list of classes to exclude when processing the source.
`strictMode`	`false`		The plugin distinguishes between errors and warnings. In strict mode warnings are treated as errors and cause the plugin to fail.
`properties`	None	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.
`outputDirectory`	`${project.build.outputDirectory}`	1.0.0	The directory where all files are generated in.
`supportedProjectTypes`	`jar, bundle`	1.8.0	Project types which this plugin supports.

specVersion

Automatically detected

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

true

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

scanClasses

false

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.

sourceIncludes

true

1.7.4

Comma separated list of classes to include when processing the source.

sourceExcludes

true

Comma separated list of classes to exclude when processing the source.

strictMode

false

The plugin distinguishes between errors and warnings. In strict mode warnings are treated as errors and cause the plugin to fail.

properties

None

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.

outputDirectory

${project.build.outputDirectory}

1.0.0

The directory where all files are generated in.

supportedProjectTypes

jar, bundle

1.8.0

Project types which this plugin supports.

The metatype files are generated in the OSGI-INF/metatype/ directory and the Declarative Services descriptor files in the OSGI-INF directory.

The plugin will look for component annotations 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 useful 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 files. 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>
 ...

Build with Java 17 and 21

The maven-scr-plugin is not directly compatible with Java 17 and 21. However, it remains possible to generate the descriptor files by updating the ASM dependency version within the plugin configuration.

 <project>
   ...
   <build>
     ...
     <plugins>
       ...
       <plugin>
         <groupId>org.apache.felix</groupId>
         <artifactId>maven-scr-plugin</artifactId>
         <version>1.26.4</version>
         <executions>
           <execution>
             <id>generate-scr-scrdescriptor</id>
             <goals>
               <goal>scr</goal>
             </goals>
           </execution>
         </executions>
         <dependencies>
           <dependency>
             <groupId>org.ow2.asm</groupId>
             <artifactId>asm-analysis</artifactId>
             <version>9.7.1</version>
             <scope>compile</scope>
           </dependency>
         </dependencies>
       </plugin>
       ...
     </plugins>
     ...
   </build>
   ...
 </project>