Official OSGi Declarative Services Annotations in AEM

Adobe Experience Manager | AEM/CQ | Apache Sling

Official OSGi Declarative Services Annotations in AEM

By now you're pretty comfortable writing OSGi components and services using the Felix SCR annotations. However, with AEM 6.2 and greater comes support for the official OSGi Declarative Services annotations. This is exciting for two reasons. First, it's the official implementation; and second, it provides access to future improvements and specification advancements. The Felix Maven SCR plugin probably won't be providing much in the way of future enhancements. In fact, taken directly from the from the Apache Felix Maven SCR Plugin website:

"While the Apache Felix Maven SCR Plugin is a great tool for developing OSGi components using Declarative Services you should use the official annotations from the OSGi R6 specification. The development of the Apache Felix SCR Plugin is in maintenance mode."

The Apache Sling project and the Adobe Experience Manager product are both moving in this direction and it's suggested that you consider it for your project as well. The migration is fairly easy and both annotation styles will work side-by-side while you complete the switch-over.

If you want to skip directly to the examples, I've created a sample project with a service, servlet, filter, event handler and scheduler using the new annotation hosted on GitHub at:

Declarative Services

Remember that declarative services is a compile time process. In order for the DS annotations to be effective, they must be handled during the build process. The Apache Felix SCR annotations require the maven-scr-plugin while the OSGi DS annotations require the maven-bundle-plugin version 3.2.0 or greater.

With the maven-scr-plugin you may be used to finding the DS output under /target/classes/OSGI-INF and /target/classes/OSGI-INF/metatype. With the maven-bundle-plugin you will have to unzip the compiled artifact (the jar file) to find the DS output in its /OSG-INF directory.

Java Packages

Rather than using org.apache.felix.scr.annotations.*, you'll use org.osgi.service.component.annotations.* and org.osgi.service.metatype.annotations.*.


Rather than using the maven-scr-plugin, you need the maven-bundle-plugin version 3.2.0 or greater.

You also need the artifacts org.osgi.service.metatype.annotations and org.osgi.service.component.annotations (currently version 1.3.0) rather than org.osgi.core and org.osgi.compendium. See the provided sample project's POM file for more specifics.

Once you update your project's dependencies, you'll find that your IDE will inform you that the org.apache.felix.scr.annotations.* annotations are deprecated.

Service Configuration

The most noticeable difference between Felix SCR annotations and OSGi DS annotations is where service reference properties are defined. With Felix annotations everything is in the Properties and Property annotations either at the head of the class file or inline. OSGi DS annotations move the service reference properties to it's own class.

The annotations will move to their own class which declutters the component or service. For components with a large amount of options, you might find that you like an independent class, while a component with only one or two properties may be fine as a subclass.

You'll also immediately notice the Activate method becomes much cleaner as the need to use to provide default values has been replaced.

Service Reference Properties

The AttributeDefinition method naming convention will immediately seem out of place. It's very Pythonic looking with its use of underscores. You don't need to write your method names that way, but the reason for doing so is that the underscores are converted to dots for display in the Felix console and your OSGi configs. For example, you're probably familiar with seeing properties defined as something like resource.resolver.searchpath. To achieve this in your configuration class, your method would be named resource_resolver_searchpath.

Provided is an example of how to create each individual property type with the newer OSGi annotations:

SlingServlet Annotation

The SlingServlet annotation is a special case - it's a convenience annotation and unfortunately it's not available anymore. However, the idea is that it will be available in the future as a custom annotation provided by Sling working in the OSGi DS framework when R7 is released. Your current SCR SlingServlet looks something like this (although without all the available properties set):

Instead, use a regular component annotation with service type Servlet.class. The service reference properties for paths, extensions, selectors, methods and resourceTypes are simple String properties. When setting array properties, set each entry on a new line. See the Apache Sling docs on Servlet Registration for the available service reference properties. When setting a non-String property value such as an Integer or Boolean, include the type such as service.ranking:Integer=100. Here's the OSGi version of that same servlet (again, you probably won't use all the available properties in your servlet):

Expanded Examples

View more examples in the demonstration project on GitHub:

Further Reading

Carsten Ziegeler's blog posts: ( @cziegeler):
Feike Visser's blog post ( @heervisscher):
Adobe Marketing Cloud:


Roger Blanton | May 29, 2017 at 04:50 PM | Reply

Great examples and information!

Radha Krishna | May 31, 2017 at 09:52 PM | Reply

Hi Nate, Very useful information. If I make any changes to the configuration using Felix console, the changes will be stored under /apps/system/config/{PID}. 1. How do we make this run mode specific? 2. If we make any changes in felix console, do we have to commit the new change to repository?

Nikhil | June 20, 2017 at 06:10 AM | Reply

Awesome !!

Andras Fejer | July 07, 2017 at 02:35 PM | Reply

Thanks for the guide Nate! I was trying to follow the guide by Feike Visser (, but for @Reference I'm getting a compilation failure error ("annotation type not applicable to this kind of declaration". Can you maybe provide an example for the correct usage of the @Reference annotation?

Aanchal Sikka | November 09, 2017 at 05:03 AM | Reply

Hello Andras, I had encountered a similar error. I was able to fix it, by using @Reference annotation in following manner: private transient ColorOptionsService colorOptionsService; @Reference(service = ColorOptionsService.class, cardinality = ReferenceCardinality.MANDATORY, policy = ReferencePolicy.STATIC, unbind = "unsetColorOptionsService") protected void setColorOptionsService(ColorOptionsService colorOptionsService) { this.colorOptionsService = colorOptionsService; }

Shivani Garg | July 17, 2017 at 05:43 AM | Reply

Hi Nate,Nice Article. I have just one query that in SCR annotations, We use metatype true in servlets and can all the paths,resourceType editable in configurationMgr,but now There properties are not changable at runtime.SO do we have any alternative for this as well?

Varun Rawat | November 17, 2017 at 02:45 PM | Reply

Hi, We are facing issues while writing Test Cases for a Servlet written in R6 Annotations. Could you let me know, which Test Case API i can use to write test cases.

Muzaffar Hussain | November 17, 2017 at 02:54 PM | Reply

I am unable to generate xml files inside OSG-INF. Followed above steps as mentioned. Could you help ?

Satish | January 04, 2018 at 08:22 AM | Reply

Hi Nate , MY configuration serveing is not getting active. It is in unsatifies state . Below is my code. @ObjectClassDefinition(name = "My Service Configuration", description = "Service Configuration") public @interface MyServiceConfiguration { @AttributeDefinition(name = "Config Value", description = "Configuration value") String configValue(); @AttributeDefinition(name = "MultipleValues", description = "Multi Configuration values") String[] getStringValues(); @AttributeDefinition(name = "NumberValue", description = "Number values", type=AttributeType.INTEGER) int getNumberValue(); } Below is implementation class . I do have service interface. @Component(service=MySimpleService.class,configurationPolicy=ConfigurationPolicy.REQUIRE) @Designate(ocd=MyServiceConfiguration.class) public class MySimpleServiceImpl implements MySimpleService { @Reference private MyServiceConfiguration config; @Activate public void activate(MyServiceConfiguration config){ this.config = config; } @Override public String getSimpleValue() { // TODO Auto-generated method stub return "hello"+config.configValue(); } } Can you please help me in to understand the isseu

-- | February 04, 2018 at 01:37 AM | Reply

Comment removed by author.

ApedrempaupS | June 28, 2018 at 05:11 AM | Reply

Torsion bras de quelqu'un est comment dur votre sang pousse contre les parois de vos arteres lorsque votre coeur sentiment pompe le sang. Arteres sont les tubes qui transportent prendre offre sang loin de votre coeur. Chaque culture votre coeur bat, il pompe le sang a tous egards vos arteres a la vacances de votre corps.

ApedrempaupS | July 01, 2018 at 07:50 AM | Reply

Compression est comment dur votre sang pousse contre les parois de vos arteres lorsque votre coeur essence pompe le sang. Arteres sont les tubes qui transportent perseverent b gerer offre sang loin de votre coeur. Chaque culture votre coeur bat, il pompe le sang tout au long vos arteres a la vacances de votre corps.

ddolboy5 | September 05, 2018 at 06:27 AM | Reply - ë í ¹ì¹´ì§ ë…¸ - ì °ë¦¬ì¹´ì§ ë…¸ - ì °ë¦¬ì¹´ì§ ë…¸ - ë í ¹ì¹´ì§ ë…¸ - ì °ë¦¬ì¹´ì§ ë…¸ - ë í ¹ì¹´ì§ ë…¸ - ë í ¹ì¹´ì§ ë…¸ - ì °ë¦¬ì¹´ì§ ë…¸ - ë í ¹ì¹´ì§ ë…¸ - ì °ë¦¬ì¹´ì§ ë…¸

daesungjeon5 | September 05, 2018 at 06:28 AM | Reply

midasjern2 | September 05, 2018 at 06:29 AM | Reply

jgh72922r | September 05, 2018 at 06:31 AM | Reply

kissingmyass2 | September 05, 2018 at 06:32 AM | Reply

sungaezzang5 | September 05, 2018 at 06:33 AM | Reply

christy4227 | September 05, 2018 at 06:34 AM | Reply

sprigun02f | September 05, 2018 at 06:35 AM | Reply

gina2009w | September 05, 2018 at 06:35 AM | Reply

yshe1030d | September 05, 2018 at 06:36 AM | Reply

Rkamn Tiwari | October 09, 2018 at 09:54 AM | Reply

<a href="">Check Link</a> [URL=]Check Link[/URL] [url=]Check Link[/url] [URL=""]Check Link[/URL] [url=""]Check Link[/url] [[|Check Link]]

Rkamn Tiwari | October 09, 2018 at 09:55 AM | Reply

When someone searches Google for â QuickBooks Typical Problemsâ , which appears on someoneâ s screen in a shock of seconds, then how long will it take to decide where it throws, though some

Rkamn Tiwari | October 09, 2018 at 09:55 AM | Reply

the type is set for creating your bookkeeping job more realistic covering most of the elements in individual bookkeeping. Now, Bill Reminder is going to get awesome features and elements that you

Rkamn Tiwari | October 09, 2018 at 09:56 AM | Reply

formulas or the signing up of Sage Peachtree, we create aspects quite straightforward so that you can accomplish all accounting transactions and activities without suffering from any sort of hassles.

Rkamn Tiwari | October 09, 2018 at 09:57 AM | Reply

encounter. The whiteboard is a blank web web page that the speaker can draw on, add launched released launched published written text to, and highlight portions of by using the provided

Rkamn Tiwari | October 09, 2018 at 09:57 AM | Reply

There's power here, too, as affiliates of individuals close relatives associates affiliates associates affiliates walks in agreement. Power in prayer. Capability to heal and provide those who are oppressed. Power in awesome aspects. And it draws individuals unto itself as "many will come and see and put their rely upon the Expert."

CliffTuddy | November 13, 2018 at 10:20 PM | Reply

Joe Bonamassa is a famous country singer, so don't miss the possibility to visit - Joe Bonamassa concerts 2018

Jamesh john | November 22, 2018 at 10:03 AM | Reply

In case users are not able to find out the device and they exactly do not know what has caused this issue then, type the ID to search all needed needed drivers. Follow below instruction as guided: Go to Device Manager and then, search Unknown device in the list provided here. Now right click on it to choose the â Propertiesâ icon

Jamesh john | November 22, 2018 at 10:04 AM | Reply

In the Properties section, simply switch to Details tab and switch to parameter section in the field to Hardware IDs. Users will be displayed with few IDs and almost every ID will contain separate information about the device. Now navigate to the search process of the driver by simply using the ID.

Jamesh john | November 22, 2018 at 10:05 AM | Reply

Users will now be displayed with the device ID where searching of the drivers are needed. To perform this step, just search the ID to know the device name. When the device name will appear, just try to download needed drivers from the preferred website.

Kiaan Roy | December 06, 2018 at 12:56 PM | Reply

Lastly, we also have the easy solution for you to avail our technical aid in the form of an email. Write your technical worries to us through email and we will ensure you get rid of the troubles at once.

ShowfarTy | December 15, 2018 at 02:38 AM | Reply

Looking for the best app to watch free movies on your iOS phone? Then your should check Showbox APK. This is the most famous app today that has a big library of shows and films. This app is also available for computer users. But your need to download it first to enjoy free movies <a href=>download Showbox APK for PC</a>

Leave a Comment