Migrating from the Apache Felix SCR Annotations to the OSGi Declarative Services Annotations

The Java annotations of the Apache Felix SCR Plugin were one of the first options to use annotations to create the descriptors for OSGi Declarative Services components and OSGi metatype descriptions for the configuration of such components. With the OSGi R6 release from 2015, the annotations of the OSGi specifications provide the same functionality and go even beyond.

Migrating from the Apache Felix SCR Annotations

Whenever there are competing solutions for the same problem, the question of which one to use arises. In this case, the answer is clear: use the official annotations from the OSGi specifications – for one, they are defined in a standard, but equally important these annotations support all features of Declarative Services R6 – while the Apache Felix annotations only support R5 and it is very unlikely that they will be updated. And that’s the other reason why you should not use the Apache Felix annotations – they are in maintenance mode. Of course, should any bug or problem arise, this will be fixed.

The second question usually is: Should I migrate existing code? There is no need to bulk migrate existing code. As said, the Apache Felix plugin is still maintained, is open source and simply works. However, if you have to touch your code, migrating the annotations might be a good idea. It also gives you the chance to simplify your code by leveraging the R6 features. That said, if you do so, this of course ties your implementation to an R6 implementation of Declarative Services, like Apache Felix SCR, version 2.0 or higher.

Mapping to OSGi Declarative Services Annotations

The below table gives you an overview of how to map the annotations.

Annotation Mapping

Apache Felix SCR AnnotationDescriptionOSGi Declarative Services AnnotationDescription
@ComponentThe @Component annotation marks a Java class to be used as a component.@ComponentThis is more or less a strict one-to-one replacement. Only difference is the default behavior for services. See below.
@ServiceMarks the component as a service and optionally lists the provided services (classes)@ComponentThe OSGi annotation has a service attribute which should be used to list the provided services. Be careful, if your component should not provide any service, set this attribute to an empty array.
@ReferenceReference to services, can be used on unary fields or on class level with bind/unbind methods.@ReferenceField references can directly be migrated, for event based references (methods), the @Reference annotation must be put on the bind method. In addition, more options for field references exist.
@Activate, @Deactivate, and @ModifiedMark a method being the activation, deactivation or modified method@Activate, @Deactivate, and @ModifiedStraight one-to-one migration.
@PropertyConfiguration properties and metatype.Component Property Type and metatype annotationsInstead of using a set of @Property annotations, the configuration is described through an annotation (component property type) and OSGi Metatype annotations can be used to add the metatype info.
Mapping between Apache Felix SCR Annotations and OSGi Declarative Services Annotations

The above table is of course just a short reference. You’ll find more information in the OSGi specifications and in my Declarative Services Tutorials: Part I, Part II, and Part III.