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.
@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;
}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.