---
title: "Core mental model: modules, lifecycle, and services"
chapter: "01"
---

# Core mental model: modules, lifecycle, and services

Three ideas define OSGi: **module boundaries**, **managed lifecycle**, and a
**dynamic service registry**.

## Modules

An OSGi bundle is a JAR with metadata in `META-INF/MANIFEST.MF`. The framework
creates a class space from explicit imports and exports. A bundle sees its own
private classes, selected Java platform packages, and packages wired by the
resolver. It does not receive one flat application classpath.

## Lifecycle

A bundle moves through states:

`INSTALLED → RESOLVED → STARTING → ACTIVE → STOPPING → RESOLVED`

`UNINSTALLED` is terminal for that bundle object. INSTALLED often means a
requirement cannot be resolved. ACTIVE means the bundle's start operation
completed—not that every business dependency is healthy.

## Services

A service is an object registered under one or more interface names with
properties. Consumers query by interface and LDAP-style filter. Services can
arrive, be replaced, or disappear. Good code expresses this dynamics through
Declarative Services instead of caching raw registry objects.

```java
@Component(service = PricingService.class)
public final class DefaultPricingService implements PricingService {
  public Money price(Quote quote) { return quote.basePrice(); }
}
```

The DS runtime creates the component, publishes the service, binds references,
and withdraws it safely.

## Bundle versus component

A bundle is a deployment and class-loading unit. A DS component is a managed
object inside a bundle. One bundle can contain many components; one component
can publish several service contracts.

## Static and dynamic

Package wiring is normally decided at resolve time and stays stable until a
refresh. Service wiring is dynamic at runtime. Confusing those two timelines
causes poor designs.

## Feynman check

A package wire answers “where is this class loaded from?” A service reference
answers “which object currently performs this job?” Explain why those are
different questions.