Tag Archives: AEM OSGI Config

AEM Solution: AEM OSGi Config Resolution Order


In this post, will talk about simple concept what is OSGi (i.e open service gateway interface) resolution order & what does this order is different when AEM starts & when something we change from OSGi console.

OSGI Config Resolution Order: at Startup vs Runtime

AEM Apache Felix based OSGi runtime environment(aka system console) loads the configurations in two different ways and makes them available to the application. Read the section “How these configs are resolved?” in this post How AEM OSGi works?

The same OSGi Apache Felix framework loads configuration runtime different. The following order of precedence applies: 

  • If you have modified any config directly from system console (i.e AEM OSGi admin console) then AEM creates another .config file and this file gets precedence over your XML file, apps or libs.
  • If you have made changes in config file under apps and the same config has not been modified from system console then apps modified config would take the precedence over libs and will available to the application immediately.
  • If you have modified any config under libs & it is not overridden at the apps level & it is not modified from system console then modified config will take the precedence.

Config Resolution Order with multiple run modes:

For run mode specific configurations, multiple run modes can be combined. For example, you can create configuration folders in the following style:


Configurations in such folders will be applied if all run modes match a run mode defined at startup. For example, if an instance was started with the run modes author,dev,emea, configuration nodes in /apps/*/config.emea/apps/*/config.author.dev/ and /apps/*/config.author.emea.dev/ will be applied, while configuration nodes in /apps/*/config.author.asean/ and /config/author.dev.emea.noldap/ will not be applied.

If multiple configurations for the same PID are applicable, the configuration with the highest number of matching run modes is applied.

For example, if an instance was started with the run modes author,dev,emea, and both /apps/*/config.author/ and /apps/*/config.emea.author/ define a configuration for
com.day.cq.wcm.core.impl.VersionManagerImpl, the configuration in/apps/*/config.emea.author/ will be applied.

This rule’s granularity is at a PID level. You cannot define some properties for the same PID in/apps/*/config.author/ and more specific ones in /apps/*/config.emea.author/ for the same PID.
The configuration with the highest number of matching run modes will be effective for the entire PID.

AEM Solution: How does an AEM OSGi Config work?


In this post, would like to explain to the readers about how does an OSGi (i.e Open service gateway interface) Config work? Would like to clarify some doubts in this post.

What is AEM OSGi Config?

AEM OSGi config is a mechanism to maintain configurations which are bound to change & varies based on different scenarios. Like loading same config file with QA, Stage & Prod with different entries. OSGi configs are available within the OSGi runtime environment so those can be used by any other service at any time with help of OSGi service registry model. 

How to use OSGi Configs?

To use OSGi Config in your OSGi based application like AEM (i.e Adobe experience manager). Just have an XML File & bind configuration entries (i.e XML file) with Java service or component registered in the OSGi framework.  Here is the AEM example. See a simple XML file  & relative OSGi service.

# OSGi XML File naming convention


#XML File Content in source code.

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
package com.osgiConfig.example;
public class OsgiConfigExample implements SlingSafeMethodsServlet {
   @Property(label = "service path",value = "exmple.com")
   private static final String SERVICE_PATH = "servicePath";
   public void doGet(SlingHttpServletRequest req, SlingHttpServletResponse res) 
   {// your code goes here ...}

How these configs are resolved?

The following order of precedence is used:

  • Repository nodes under /apps/*/config….either with type sling:OsgiConfig or property files.
  • Repository nodes with type sling:OsgiConfig under /libs/*/config…. (out-of-the-box definitions).
  • Any .config files from <cq-installation-dir>/crx-quickstart/launchpad/config/…. on the local file system.

Is Naming convention of XML File necessary?

Yes. Your xml file must follow name convention and that is package name & service class name where the properties annotations are.

Do you really need XML File in our source code?

Yes. OSGi config files must be maintained & put in run mode config folders in your source code. Like config, config.author, config.author.QA etc. If those are not maintained that way, you need to open OSGi config from OSGi admin console & change the config. It becomes more difficult when you have to do the same in the production environment.

Is it really need to have property annotation at the class level?

This question is important because most of us think that if we have OSGi config XML in run mode & it matches the service package name & class then required configuration would be available to use. However, that is not the case. Property annotation gets resolved when an OSGi service/component becomes active in OSGi runtime environment. And OSGi service resolves these properties at the service level. So if you do not have these properties at the service level then Service or component do not load OSGI config’s from your run mode.

Final Thought

Here I tried to put some of the questions & their answers. But still there could be some questions which are not listed here. You can post in comment & I will get back to you.