Org Skills

OSGi components, configuration and Context-Aware Configuration

Supporting material for aem-backend-development. Agents load it on demand; it ships inside the skill folder.

RawSource

Verified: 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/developing/configuring-osgi and https://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration.html

Open this when writing a Declarative Services component, deciding where a config value lives, or laying out ui.config.

A complete DS component with configuration

package com.acme.core.services.impl;

import com.acme.core.services.PriceService;
import org.osgi.service.component.annotations.*;
import org.osgi.service.metatype.annotations.*;

@Component(service = PriceService.class)
@Designate(ocd = PriceServiceImpl.Config.class)
public class PriceServiceImpl implements PriceService {

    @ObjectClassDefinition(name = "Acme Price Service")
    public @interface Config {
        @AttributeDefinition(name = "Endpoint") String endpoint() default "https://api.example.com";
        @AttributeDefinition(name = "Socket timeout (ms)") int timeout() default 5000;
        @AttributeDefinition(name = "API key", type = AttributeType.PASSWORD) String apiKey();
    }

    private volatile Config config;

    @Activate
    @Modified
    protected void activate(Config config) {
        this.config = config;   // never block, never do I/O here
    }
}
  • The interface lives in an exported package (com.acme.core.services); the implementation in …services.impl, which maven-bundle-plugin/bnd must not export. Only exported packages are API you have to keep stable.
  • @Activate @Modified on one method means a config change re-configures the component instead of restarting it. Store the config in a volatile field — other threads read it concurrently.
  • @Deactivate releases what @Activate acquired (HTTP clients, listeners). Pods are recycled, so deactivation runs often.
  • A component with no service = is an immediate component; add immediate = true only when it must start without a consumer (for example a Runnable scheduler).

References

@Reference private ResourceResolverFactory resolverFactory;                       // static, mandatory
@Reference(cardinality = ReferenceCardinality.OPTIONAL, policy = ReferencePolicy.DYNAMIC)
private volatile Externalizer externalizer;                                        // dynamic → volatile
@Reference(cardinality = ReferenceCardinality.MULTIPLE, policy = ReferencePolicy.DYNAMIC,
           policyOption = ReferencePolicyOption.GREEDY)
private volatile List<PriceProvider> providers;

Keep references static and mandatory unless the dependency is genuinely optional — a static reference guarantees the field is set before @Activate and re-binds by restarting the component.

Where configuration lives

ui.config/src/main/content/jcr_root/apps/acme/osgiconfig/
├── config/                      all runmodes
├── config.author/               author only
├── config.publish/              publish only
├── config.author.dev/           author on dev
├── config.publish.prod/         publish on prod
└── config.rde/                  Rapid Development Environment (inherits dev)
  • Runmodes on Cloud Service are fixed: author, publish, dev, stage, prod, rde. Custom runmodes do not exist; a folder such as config.publish.uat is never applied.
  • More specific folders win: config.publish.prod beats config.publish beats config. AEM picks one folder, it does not merge the files.
  • File names: <PID>.cfg.json for a singleton, <factoryPID>~<name>.cfg.json for a factory config. Values are typed by suffix: "timeout:Integer", "enabled:Boolean", "topics:String[]".
{
  "endpoint": "$[env:PRICE_ENDPOINT;default=https://api.example.com]",
  "apiKey": "$[secret:PRICE_API_KEY]",
  "timeout:Integer": 5000
}
  • $[env:NAME;default=…] and $[secret:NAME] are resolved at runtime from Cloud Manager environment variables, so one file covers every environment. Variables are set per environment (and optionally per service, author or publish) in Cloud Manager — see aem-cloud-manager.
  • $[secret:…] values are write-only in Cloud Manager and never appear in the repository or in logs. Never commit a real key, not even in a config.dev folder.
  • sling:OsgiConfig nodes and .config files are legacy 6.5 formats. Cloud Service requires .cfg.json in ui.config; the Repository Modernizer converts them (aem-cloud-migration).

Prefer Context-Aware Configuration for per-site values

Environment-scoped values (endpoints, credentials, timeouts) belong in OSGi. Values that differ per site or per brand (a feature flag, a form recipient, a CDN prefix) belong in Sling Context-Aware Configuration under /conf, so authors and site owners can own them without a deployment.

@Configuration(label = "Acme Site Settings")
public @interface SiteConfig {
    @Property(label = "Contact form recipient") String contactRecipient() default "web@example.com";
}
SiteConfig cfg = resource.adaptTo(ConfigurationBuilder.class).as(SiteConfig.class);
  • Values are stored under /conf/<site>/sling:configs/<config-name> and inherited down the /content tree via sling:configRef on the site root's jcr:content.
  • From a Sling Model, inject with @OSGiService ConfigurationResolver or adapt the current resource as above; never read /conf paths by string.
  • The org.apache.sling.caconfig.impl.def.DefaultConfigurationPersistenceStrategy and the resource-collection variant (ConfigurationBuilder#asCollection) cover multi-valued cases (a list of redirect rules, for example).

Things that behave differently on Cloud Service

  • The OSGi web console is not reachable on production; inspect bundles and configs through the AEM Developer Console (Status → OSGi configuration dumps).
  • SlingSettingsService#getRunModes() works, but branching business logic on run modes hides bugs that only appear on publish. Branch on configuration instead.
  • Bundle start levels, installing bundles at runtime via the Felix console, and ConfigurationAdmin writes from code are not available — everything ships through the pipeline.