# OSGi components, configuration and Context-Aware Configuration

> **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

```java
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

```java
@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[]"`.

```json
{
  "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.

```java
@Configuration(label = "Acme Site Settings")
public @interface SiteConfig {
    @Property(label = "Contact form recipient") String contactRecipient() default "web@example.com";
}
```

```java
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.
