4.3 Composite Entity

The Composite Entity pattern uses a coarse-grained entity object to manage a set of interdependent fine-grained objects (an "object graph"). It was born in the EJB era, when each fine-grained object might be a separate entity bean and accessing them one by one remotely was extremely costly. A composite entity bundles them so the client operates the whole graph through one coarse-grained call.

In the lab below, the Customer composite entity manages an Address and a set of Orders; after editing fields, one persist() saves the entire object graph as a unit.

Coarse-grained vs fine-grained

The core tradeoff is the number of remote calls:

• Fine-grained: each dependent object is accessed/persisted independently; loading one customer can take several remote round-trips.

• Coarse-grained (composite entity): customer, address, and orders form one unit, handled in a single call.

The comparator below lets you switch between the two granularities and see the difference in remote calls needed to load the whole object graph.

Role breakdown

A classic composite entity often includes several roles:

• Composite Entity: the coarse-grained main object, the single entry point.

• Dependent Objects: the fine-grained objects it manages, not exposed individually.

• Strategies: optional, used to customize how the entity persists/loads.

The client sees only the composite entity, whose lifecycle governs the dependent objects — reducing remote calls and hiding the internal structure.

Real-world echoes

Pure EJB entity beans are history, but "wrap a set of tightly related objects in a coarse-grained boundary" is still everywhere today:

• DDD's Aggregate Root: the aggregate root is the single entry that governs the consistency boundary of objects inside the aggregate — just like a composite entity.

• A single GraphQL query fetching an object graph: avoids N frontend requests for related data.

Understanding the composite entity helps you see the shared motive — "reduce round-trips, unify the boundary" — behind these modern designs.