OSGi Services in Practice

Writing a service

Define an interface, implement it, annotate the implementation. That is the whole pattern:

public interface AdventureService {
    List<Adventure> findByDifficulty(String difficulty);
}

@Component(service = AdventureService.class, immediate = true)
public class AdventureServiceImpl implements AdventureService {

    private static final Logger LOG =
            LoggerFactory.getLogger(AdventureServiceImpl.class);

    @Reference
    private ResourceResolverFactory resolverFactory;

    @Activate
    protected void activate() {
        LOG.info("AdventureService starting");
    }

    @Deactivate
    protected void deactivate() {
        LOG.info("AdventureService stopping");
    }

    @Override
    public List<Adventure> findByDifficulty(String difficulty) { ... }
}

• service = AdventureService.class publishes it under that interface. Omitting service registers the component without publishing a service — fine for something that only reacts to events.
• immediate = true activates it at startup rather than lazily on first use. Use it when the component must do something on its own, such as register a listener or start a scheduler.

The lifecycle

A DS component moves through a small set of states, and knowing them makes diagnosis quick:

• Unsatisfied — a mandatory reference cannot be bound. It will not activate.
• Satisfied — all mandatory references are available. For a lazy component, it waits here until first use.
• Active — @Activate has run and it is serving.

/system/console/components shows the state, and for unsatisfied components it names the reference that could not be bound. That single page answers most "why isn't my service running" questions.

Reference cardinality and policy

Two independent dimensions on @Reference:

• Cardinality — MANDATORY (default), OPTIONAL, MULTIPLE, AT_LEAST_ONE.
• Policy — STATIC (default: the component is deactivated and reactivated when the reference changes) or DYNAMIC (the field is swapped without restarting the component).

// Collect every implementation, and cope with them coming and going
@Reference(cardinality = ReferenceCardinality.MULTIPLE,
           policy = ReferencePolicy.DYNAMIC)
private volatile List<AdventureProvider> providers;

A dynamic multiple reference must be volatile, because another thread can replace it while your code reads it. This is the standard pattern for a plug-in style extension point.

Service ranking

When several components implement the same interface, the one with the highest service.ranking wins for a single-reference injection. This is how you override an AEM service without touching Adobe's code:

@Component(
    service = SomeAemService.class,
    property = { Constants.SERVICE_RANKING + ":Integer=1000" }
)
public class MyOverridingImpl implements SomeAemService { ... }

Powerful and worth using carefully — you have now taken responsibility for behaviour Adobe may change or rely on elsewhere. Prefer composition where you can.

Getting a ResourceResolver in a service

A service has no request, so it has no user. It needs a service user — covered properly on day 31 — and the resolver must always be closed:

Map<String, Object> params = Collections.singletonMap(
        ResourceResolverFactory.SUBSERVICE, "wknd-content-reader");

try (ResourceResolver resolver =
         resolverFactory.getServiceResourceResolver(params)) {
    Resource r = resolver.getResource("/content/wknd");
    // ...
}   // closed automatically