OSGi Services and References: Wiring Your Code Together

In the previous post we saw how a component starts and stops. Real features need components that work together: a servlet that calls a service, a service that uses another service, a workflow step that needs a helper. OSGi handles this wiring through services and references. This post shows how to design a service, consume it safely, and diagnose it when the wiring fails.

Service = Interface + Implementation

The standard pattern is a small public interface and one implementation:

package com.myproject.core.services;

public interface PriceService {
    String formatPrice(double amount, String currencyCode);
}

package com.myproject.core.services.impl;

import com.myproject.core.services.PriceService;
import java.text.NumberFormat;
import java.util.Currency;
import java.util.Locale;
import org.osgi.service.component.annotations.Component;

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

    @Override
    public String formatPrice(double amount, String currencyCode) {
        NumberFormat format = NumberFormat.getCurrencyInstance(Locale.US);
        format.setCurrency(Currency.getInstance(currencyCode));
        return format.format(amount);
    }
}

service = PriceService.class is what registers the component as a service under that interface. Without it, the component exists but nobody can look it up.

Keep the interface in an API package and the implementation in a separate impl package. Other code depends only on the interface, so you can replace or mock the implementation without touching callers.

Consuming a Service with @Reference

Inside another component, ask for the service with @Reference:

@Component(service = Servlet.class)
public class PriceServlet extends SlingSafeMethodsServlet {

    @Reference
    private PriceService priceService;

    @Override
    protected void doGet(SlingHttpServletRequest request, SlingHttpServletResponse response)
            throws IOException {
        response.setContentType("text/plain");
        response.getWriter().write(priceService.formatPrice(19.99, "USD"));
    }
}

OSGi finds an active PriceService, injects it, and only then activates the servlet. If no matching service exists, the servlet stays unsatisfied.

In a Sling Model, don't use @Reference. Use @OSGiService:

@Model(adaptables = SlingHttpServletRequest.class,
       defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL)
public class PriceModel {
    @OSGiService
    private PriceService priceService;
}

Reference Options That Matter

@Reference has defaults that suit most cases: mandatory, static. These attributes change the behavior:

Example of an optional, dynamic reference. The field must be volatile:

@Reference(cardinality = ReferenceCardinality.OPTIONAL, policy = ReferencePolicy.DYNAMIC)
private volatile AuditLogger auditLogger;

private void audit(String message) {
    AuditLogger logger = auditLogger;   // read once into a local variable
    if (logger != null) {
        logger.log(message);
    }
}

Copying the field into a local variable before the null check avoids a race, because a dynamic reference can disappear between two reads.

Choosing Between Implementations

If two components implement the same interface, OSGi needs a way to pick one. You have two options:

Service ranking. The highest service.ranking wins:

@Component(service = PriceService.class, property = {"service.ranking:Integer=100"})

A target filter. Select by a service property:

@Component(service = PriceService.class, property = {"channel=web"})
public class WebPriceService implements PriceService { ... }

@Reference(target = "(channel=web)")
private PriceService priceService;

The Advanced series covers multiple implementations and factory configurations in more depth.

Designing Good Services

• Make services stateless where possible. They are shared by many requests at once
• Keep each service focused. One responsibility is easier to test and replace
• Don't use new on a service. A hand-created object isn't wired, so its @Reference fields are null
• Don't expose AEM internals in your interface. Return plain types and your own classes
• Don't implement interfaces that AEM provides for you to call. Many product interfaces are meant to be consumed, not implemented. The Cloud build checks API usage against the SDK, so a misuse shows up as a build failure rather than a runtime surprise

Diagnosing Wiring Problems

When something isn't injected, the cause is almost always one of these:

On the local SDK, use the Felix console's Components and Services pages. On Cloud Service, the Developer Console shows the same information read-only.

AEM as a Cloud Service vs 6.5

The annotations and the lifecycle are the same on both. A few practical differences:

• Deploy time: on Cloud Service a wiring mistake only shows after the pipeline deploys, so test on a Dev environment, not just locally
• Annotations: older 6.5 code often uses the Felix SCR annotations (org.apache.felix.scr.annotations). Newer code, and everything for Cloud Service, should use the OSGi DS annotations shown here. If you're migrating, the SCR annotations are among the first things to replace
• Constructor injection: newer DS versions support injecting references through the constructor, but field injection works everywhere. Check what your runtime supports before using the newer style

What's Next

Services often need settings: an endpoint, a toggle, a timeout. The next post covers OSGi configuration: where the files live, how run modes work, and how to supply secrets safely on Cloud Service.

Next in this series: [OSGi Configuration: Files, Run Modes and Environment Variables]