Composite

Real-world analogy

A corporate organizational hierarchy consists of individual employees and management departments. An individual software engineer is a leaf with a salary. A product division is a composite containing engineering managers, who in turn manage teams of engineers. When the CEO requests the total payroll of the organization, they do not iterate through different payroll procedures for individuals versus departments; they simply invoke calculatePayroll() at the root department, which recursively sums payroll across all children.

The problem

You are building an in-memory file system. The file system contains two primary entities: binary File objects (which store a byte size directly) and Directory objects (which hold other files and subdirectories).

Without the Composite pattern, client code that calculates disk usage or prints a tree structure must continuously check the type of each item using instanceof or conditional type checks:

1 // Naive implementation: Conditional type checking and disparate interfaces
2 class File {
3   constructor(name, size) {
4     this.name = name;
5     this.size = size;
6   }
7 }
8 
9 class Directory {
10   constructor(name) {
11     this.name = name;
12     this.files = [];
13     this.subdirectories = [];
14   }
15 }
16 
17 function calculateTotalSize(item) {
18   // Client must know concrete types and traverse disparate structures
19   if (item instanceof File) {
20     return item.size;
21   } else if (item instanceof Directory) {
22     let sum = 0;
23     for (const f of item.files) sum += f.size;
24     for (const d of item.subdirectories) sum += calculateTotalSize(d);
25     return sum;
26   }
27   return 0;
28 }

1 public class Example {
2     static class File {
3         String name;
4         long size;
5         public File(String name, long size) { this.name = name; this.size = size; }
6     }
7 
8     static class Directory {
9         String name;

This approach introduces brittle conditional branching across your codebase. Adding symbolic links, archives, or shortcuts forces updates to every traversal and calculation function.

The solution

The Composite pattern organizes objects into tree structures to represent part-whole hierarchies. It defines a common interface for both individual primitives (Leaf) and complex containers (Composite), allowing clients to treat them uniformly.

• Component (FileSystemEntry): Declares common operations (getSize(), display()) for all objects in the hierarchy.
• Leaf (File): Represents primitive terminal elements that have no children.
• Composite (Directory): Stores child components and delegates operations recursively across its children.
• Client: Interacts with all elements exclusively through the Component contract.

Step-by-step implementation

Step 1: Declare the common component contract

Create an abstract component declaring the operations that leaves and composites share.

Step 2: Implement the leaf element

The leaf handles operations directly without holding references to child nodes.

Step 3: Implement the composite container

The composite maintains an array of child FileSystemEntry components and aggregates results recursively.

The complete example

Here is the complete, runnable implementation showing nested directories and files executed uniformly.

1 + Directory: root
2   + Directory: etc
3     - File: hosts (320 bytes)
4     - File: passwd (1250 bytes)
5   + Directory: home
6     + Directory: swarup
7       - File: resume.pdf (45000 bytes)
8       - File: notes.txt (1500 bytes)
9   - File: boot.bin (8192 bytes)
10 Total tree storage: 56262 bytes

Variations

Uniform vs safe child management

A foundational design decision in the Composite pattern is where child management methods (add, remove, getChildren) are declared:

1. Uniformity (Transparency): Child methods are declared directly on the base Component interface. Both File and Directory share the exact same interface. The client never needs to know if a node is a leaf or a composite. However, calling add() on a leaf must throw an UnsupportedOperationException or silently fail, sacrificing compile-time safety.
2. Safety: Child methods are declared only on the concrete Composite class (Directory). Leaves do not have add() or remove() methods, ensuring invalid operations are rejected at compile time. However, clients lose uniformity because they must cast components to Composite to manipulate children.

Parent pointers and aggregate caching

In deep composite trees, repeatedly traversing the tree to calculate metrics (such as directory size or total price) degrades performance.

To optimize this:

• Each component maintains a reference to its parent.
• Each composite caches its aggregate calculation.
• When a leaf changes (size updated, child added or removed), it invalidates the cache upwards through its parent pointer until reaching the root.

Where you've already used it

• Browser DOM: Node is the component; Text and Comment are leaves; Element and DocumentFragment are composites containing child nodes.
• React Component Trees: React elements and native JSX primitives form a composite tree passed via props.children.
• Java Swing / AWT: java.awt.Component is the base; JButton and JLabel are leaves; java.awt.Container (and JPanel) are composites.
• JSON Abstract Syntax Trees: A JSON document consists of scalar primitives (string, number, boolean leaves) and container nodes (object, array composites).

Pros and cons

When not to use it

Do not use Composite if your data is linear or tabular rather than hierarchical. If your entities never contain nested versions of themselves, standard list or map structures are simpler and more performant.

Related patterns

Interview questions

What is the core difference between the Uniformity and Safety approaches in Composite? Uniformity defines child management on the root Component for maximum transparency at the cost of runtime exceptions on leaves. Safety defines child management only on Composites, ensuring compile-time safety but requiring clients to distinguish leaves from composites.

How do you prevent circular references in a Composite tree? A composite must validate that the node being added is not an ancestor of itself. This can be verified by traversing upward through parent pointers before permitting the insertion.

How does Composite relate to the Decorator pattern? Both share a common interface with the objects they wrap. However, Composite manages multiple children representing a part-whole tree, whereas Decorator wraps a single child to layer on additional behavior.

How can you visit nodes in a Composite structure without polluting the Component interface with new methods? Combine Composite with the Visitor pattern. The Component interface defines a single accept(Visitor v) method, allowing new operations (serialization, validation, syntax checks) to be added without modifying the tree classes.