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, whichmaven-bundle-plugin/bndmust not export. Only exported packages are API you have to keep stable. @Activate @Modifiedon one method means a config change re-configures the component instead of restarting it. Store the config in avolatilefield — other threads read it concurrently.@Deactivatereleases what@Activateacquired (HTTP clients, listeners). Pods are recycled, so deactivation runs often.- A component with no
service =is an immediate component; addimmediate = trueonly when it must start without a consumer (for example aRunnablescheduler).
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 asconfig.publish.uatis never applied. - More specific folders win:
config.publish.prodbeatsconfig.publishbeatsconfig. AEM picks one folder, it does not merge the files. - File names:
<PID>.cfg.jsonfor a singleton,<factoryPID>~<name>.cfg.jsonfor 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 — seeaem-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 aconfig.devfolder.sling:OsgiConfignodes and.configfiles are legacy 6.5 formats. Cloud Service requires.cfg.jsoninui.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/contenttree viasling:configRefon the site root'sjcr:content. - From a Sling Model, inject with
@OSGiService ConfigurationResolveror adapt the current resource as above; never read/confpaths by string. - The
org.apache.sling.caconfig.impl.def.DefaultConfigurationPersistenceStrategyand 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
ConfigurationAdminwrites from code are not available — everything ships through the pipeline.