Understanding Liferay's OSGi Runtime Beyond Bundles
Ask a typical Liferay developer what OSGi is and you will usually hear 'it is how modules are packaged and deployed.' That is true but shallow. OSGi is a dynamic module system with a live service registry, class-level isolation, and a component lifecycle that runs while the portal is up. The behaviors that confuse people - a service that is suddenly unavailable, a component that never activates, a reference that fails to bind - all come from this runtime, not from the JAR itself.
Bundles are the packaging, not the point
A bundle is a JAR with extra metadata describing what packages it exports, what packages it imports, and how it should be wired to the rest of the system. The important word is wired. At runtime OSGi resolves each bundle's imports against the exports of other bundles, forming a dependency graph. If an import cannot be satisfied, the bundle stays unresolved and none of its code runs. This is why 'my module deployed but does nothing' is nearly always a missing or mismatched import.
The service registry is the real engine
Beyond wiring packages, OSGi provides a service registry: a runtime dictionary where components publish services and other components look them up. Services can appear and disappear at any moment while the portal runs. This dynamism is powerful but demands a different mental model than plain Java, where an object either exists or does not for the life of the process.
- A component publishes a service under one or more interfaces.
- Consumers declare a reference to that interface, not to a concrete class.
- The runtime binds consumers to whatever implementation is currently registered - and rebinds if it changes.
Declarative Services and the component lifecycle
Liferay leans heavily on Declarative Services (DS). Instead of manually registering services in code, you annotate a class as a @Component and declare @Reference dependencies. The DS runtime then manages activation: a component only becomes active once all its mandatory references are satisfied. When a dependency goes away, the component can be deactivated automatically.
@Component(immediate = true, service = GreetingService.class)
public class GreetingServiceImpl implements GreetingService {
@Reference
private UserLocalService _userLocalService;
@Activate
protected void activate() {
// Runs only after every mandatory @Reference is bound.
}
public String greet(long userId) {
return "Hello " + _userLocalService.fetchUser(userId).getFullName();
}
}This explains one of the most common 'ghost' problems in Liferay: a component that silently never activates. If a mandatory @Reference is never satisfied - because the target service failed to register - DS keeps the component in an unsatisfied state. There is no exception, just absence. The Gogo shell commands that inspect component state are the fastest way to see this.
Static vs dynamic references
References have policies that decide how the runtime reacts when a dependency changes. A static reference means the component is deactivated and reactivated when the dependency changes - safe but disruptive. A dynamic reference lets the component swap the dependency in place without restarting. Choosing the wrong policy can cause components to churn or to hold a stale reference longer than intended.
| Aspect | Static policy | Dynamic policy |
|---|---|---|
| On change | Deactivate + reactivate component | Swap reference in place |
| Field type | Usually a single field | Often used with volatile fields or collections |
| Best for | Stable, mandatory dependencies | Optional or frequently changing services |
Why isolation matters
Each bundle gets its own class space, wired precisely to the packages it imports. This is a stricter form of the class loading problems that plague plain Java applications. It prevents version clashes but means two bundles can load different versions of the same library side by side. When you hit a class cast exception between two seemingly identical classes, this isolation is usually the cause.
Practical takeaways
- When a module 'does nothing', check whether the bundle resolved and whether its components activated - these are two separate checks.
- Depend on interfaces via @Reference, never on concrete implementations, so the runtime can wire and rewire freely.
- Prefer static references for mandatory dependencies and reserve dynamic policies for genuinely optional or changing services.
- Use the Gogo shell to inspect bundle and component state before assuming your code is wrong.
Conclusion
OSGi in Liferay is not just a packaging format; it is a living runtime that resolves dependencies, publishes services, and manages component lifecycles as the portal runs. The developers who treat it that way stop being surprised by deployments. They know that a bundle can resolve without its components activating, that services come and go, and that isolation is a feature rather than a bug. That mental model is what separates fighting the platform from working with it.