Apache Sling Context Aware Configuration in AEM

PublishedAugust 23, 2025

Context-aware configurations are related to a content resource, allows different configs for different content resources. Parameters within nested contexts allow hierarchical based inheritance and global fallback values when required. Leveraging the Context-Aware Configuration Java API, one can retrieve the appropriate configuration for each content resource without concerning where it is stored or how the inheritance works.

Create Configuration Interface

Define the configuration interface using Java annotations to specify the configuration properties:

configs / SiteConfig.java

@Configuration(name = "siteConfig", label = "AEM Demo Site Configuration")
public @interface SiteConfig {
    @Property(label = "Content Path")
    String contentPath();

    @Property(label = "Site Domain")
    String siteDomain();

    @Property(label = "Content Approver Group")
    String approverGroup();
}

Implement Configuration Service

Create a service to retrieve context-aware configuration using the ConfigurationBuilder:

services / impl / SiteConfigServiceImpl.java

@Component(service = { SiteConfigService.class })
public class SiteConfigServiceImpl implements SiteConfigService {
  @Override
  public SiteConfig getSiteConfig(Resource resource) {
    ConfigurationBuilder configurationBuilder = resource.adaptTo(ConfigurationBuilder.class);
    return configurationBuilder != null ? configurationBuilder.as(SiteConfig.class) : null;
  }
}

Configure in /conf Directory

Create the configuration in the /conf directory structure:

Navigate to /conf/aem-demo/sling:configs
Create a node with your configuration name: com.aem.demo.core.configs.SiteConfig
Add the configuration properties as shown below:

/conf / aem-demo / sling:configs / com.aem.demo.core.configs.SiteConfig / .content.xml

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:sling="http://sling.apache.org/jcr/sling/1.0" 
    xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
  jcr:primaryType="nt:unstructured"
  contentPath="/content/aem-demo"
  siteDomain="http://local.aemdemo.com"
  approverGroup="aem-demo-content-approver"/>

Connect Content with Configuration

Link your content to the configuration using cq:conf and sling:configRef properties:

/content / aem-demo / .content.xml

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" 
    xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
  jcr:primaryType="cq:Page">
  <jcr:content jcr:primaryType="cq:PageContent"
    cq:conf="/conf/aem-demo"
    cq:redirectTarget="/content/aem-demo/us/en"
    cq:template="/conf/aem-demo/settings/wcm/templates/page-content"
    jcr:title="AEM Demo"
    sling:configRef="/conf/aem-demo"
    sling:redirect="{Boolean}true"
    sling:redirectStatus="{Long}302"
    sling:resourceType="aem-demo/components/page"/>
</jcr:root>

Using Configuration in Components

Access the configuration in your AEM components or services:

components / internal / models / impl / PageConfigImpl.java

@Model(
  adaptables = { SlingHttpServletRequest.class }, 
  adapters = { PageConfig.class })
public class PageConfigImpl implements PageConfig {

    @Reference
    private SiteConfigService configService;

    @SlingObject
    protected Resource resource;

    private SiteConfig config;

    @PostConstruct
    protected void init() {
      this.config = configService.getSiteConfig(resource);
    }

    @Override
    public String getContentPath() {
        return config != null ? config.contentPath() : null;
    }

    @Override
    public String getSiteDomain() {
        return config != null ? config.siteDomain() : null;
    }
}

With context-aware configurations, you can easily manage different settings for different content areas . This approach provides flexible configuration management that scales with your AEM project structure.