All posts
OSGi · 10 min read · Jun 14, 2026

Managing service dependencies in large OSGi ecosystems

Managing service dependencies in large OSGi ecosystems

OSGi makes services dynamic: components come and go at runtime, and the framework wires them together as they become available. That dynamism is powerful, but in a system with hundreds of components it is also where the most confusing bugs live. A feature that simply does not appear, with no error in the log, is almost always a dependency that was never satisfied. Managing these dependencies deliberately keeps a large module graph predictable.

Mandatory versus optional references

The first decision for every dependency is whether the component can function without it. A mandatory reference means the component will not activate until the dependency is present; an optional one lets it run and adapt when the dependency appears or disappears. Choosing wrong is a common source of stuck components.

java
@Component(service = ReportGenerator.class)
public class ReportGeneratorImpl implements ReportGenerator {

    // Mandatory: component won't start without it
    @Reference
    private DataSourceProvider dataSource;

    // Optional: component runs even if absent
    @Reference(cardinality = ReferenceCardinality.OPTIONAL,
               policy = ReferencePolicy.DYNAMIC)
    private volatile AuditService auditService;
}
Cardinality and policy decide whether a missing service blocks activation or is tolerated.

Diagnosing a component that won't start

When a feature goes missing, the Gogo shell is the fastest path to the cause. A handful of commands tell you exactly which reference is unsatisfied:

  • scr:list shows every component and its current state.
  • scr:info <name> lists a component's references and which are satisfied.
  • A component stuck in 'unsatisfied' points directly at the missing dependency.
  • lb confirms whether the bundle providing that service is even active.

Design to keep the graph shallow

The healthiest large systems keep their dependency graphs shallow and explicit. Depend on interfaces rather than implementations, avoid circular references between components, and prefer a few well-defined services over many fine-grained ones. A flat, intentional graph is far easier to reason about than a deep web of optional references.

Make the runtime observable

In a large OSGi ecosystem the goal is to make wiring visible. When any developer can run two shell commands and explain why a feature is or is not active, dependency problems stop being mysterious. That observability, more than any single design rule, is what keeps hundreds of components manageable.

Contact

Let’s connect

Have a Liferay or Backend project you’d like to talk through? Fill in the form and I’ll get back to you.

Book Calendar