Decorator

Real-world analogy

When dressing for freezing weather, you do not manufacture a single specialized "t-shirt-sweater-raincoat" garment. Instead, you put on a base t-shirt, wrap it with a sweater for warmth, and wrap the sweater with a waterproof jacket for rain protection. Each layer conforms to your body, adds a specific capability, and can be removed or combined in any order depending on conditions.

The problem

You are designing an alerting notification pipeline. Initially, the system only sends basic email notifications. Soon, stakeholders demand SMS alerts, Slack alerts, and PagerDuty escalations. Furthermore, different alert types require different combinations:

• Critical alerts: Email + SMS + PagerDuty
• Warning alerts: Email + Slack
• Info alerts: Email only

If you use class inheritance to support every combination, you quickly suffer a combinatorial class explosion ($2^N$ subclasses):

1 Notifier
2 ├── EmailNotifier
3 ├── SMSNotifier
4 ├── SlackNotifier
5 ├── EmailSMSNotifier
6 ├── EmailSlackNotifier
7 ├── EmailSMSAndSlackNotifier
8 └── EmailSMSAndPagerDutyNotifier

Static inheritance forces you to anticipate every permutation at compile time. It is impossible to add an SMS alert to an existing notifier at runtime based on user preferences.

The solution

The Decorator pattern attaches additional responsibilities to an object dynamically using composition. Decorators wrap the original component, implement the exact same interface, and delegate calls to the wrapped object while executing additional logic before or after delegation.

• Component (Notifier): Common interface implemented by both concrete components and decorators.
• Concrete Component (BasicNotifier): The base object that provides default core functionality.
• Base Decorator (NotifierDecorator): Holds a reference to a wrapped Notifier and delegates all calls to it.
• Concrete Decorators (SMSDecorator, SlackDecorator): Adds specific responsibilities dynamically.

Step-by-step implementation

Step 1: Define the component interface

Both the base notifier and all decorators must conform to this contract.

1 class Notifier {
2   send(message) {
3     throw new Error("send() must be implemented");
4   }
5 }

1 public class Example {
2     interface Notifier {
3         void send(String message);
4     }
5 
6 

Step 2: Implement the concrete component

Provide the basic standalone implementation (e.g. standard email).

1 class Notifier {
2   send(message) { throw new Error("not implemented"); }
3 }
4 
5 class EmailNotifier extends Notifier { 
6+  send(message) { 
7+    console.log(`[Email] ${message}`); 
8+  } 
9 }

Step 3: Implement base and concrete decorators

The base decorator delegates to the wrapped instance. Concrete decorators add behavior.

The complete example

Here is the complete runnable implementation demonstrating stacking decorators dynamically at runtime.

1 --- Pipeline 1: Email + SMS ---
2 Email to ops@example.com: Disk usage exceeded 85%
3 SMS to +1-555-0199: Disk usage exceeded 85%
4 
5 --- Pipeline 2: Timestamped Email + Slack + SMS ---
6 Email to ops@example.com: [2026-10-19T10:00:00.000Z] Database replica lag > 60s
7 SMS to +1-555-0142: [2026-10-19T10:00:00.000Z] Database replica lag > 60s
8 Slack post to #prod-incidents: [2026-10-19T10:00:00.000Z] Database replica lag > 60s

Variations

Stacking and execution ordering

Because decorators form an onion-like wrapping chain, their composition order directly impacts runtime execution:

• Pre-processing: Outer decorators execute their pre-processing code before passing the argument to inner decorators.
• Post-processing: Outer decorators receive the return value and execute their post-processing code after inner decorators finish.

For example, when chaining EncryptionDecorator and CompressionDecorator, compressing first and encrypting second yields high compression efficiency. Encrypting first produces high-entropy pseudo-random ciphertext that cannot be compressed.

Higher-order functions in JavaScript

In modern JavaScript and functional programming, the Decorator pattern is frequently implemented as higher-order functions rather than class hierarchies. A higher-order function takes a function as an argument and returns a new function with added telemetry, rate limiting, or caching.

Where you've already used it

• java.io stream hierarchy:
  JSnippet.java

  Copy

  1 InputStream stream = new GZIPInputStream(
  2     new BufferedInputStream(
  3         new FileInputStream("archive.tar.gz")
  4     )
  5 );

  Java · 5 lines

  UTF-8
  FileInputStream reads bytes; BufferedInputStream adds buffer pooling; GZIPInputStream decompresses the byte stream dynamically.
• Express / Koa middleware: Express handler functions (req, res, next) wrap request processing in sequential decorator layers (authentication, body parsing, CORS).
• Spring AOP & @Transactional: Spring creates dynamic proxies that decorate service methods with transaction begin, commit, and rollback logic.

Pros and cons

When not to use it

Do not use Decorator when the component interface is enormous (e.g. 30+ methods). If Component has 30 methods, the BaseDecorator must maintain forwarding boilerplate for all 30 methods, increasing maintenance burden. In those scenarios, look into Proxy or AOP interceptors.

Related patterns

Interview questions

How does Decorator differ from Proxy when both implement the same interface? Decorator dynamically enhances the target's behavior with new responsibilities (e.g., encryption, compression). Proxy controls access, lifecycle, or execution characteristics (e.g., security check, lazy loading, caching) without adding functional features.

Why does Java I/O rely so heavily on the Decorator pattern? java.io avoids creating classes like BufferedGzipFileInputStream. By making InputStream the common component, any stream source can be combined with any processing filter (buffering, decompression, data parsing).

What is the downside of object identity in the Decorator pattern? A decorator wraps a component, so decorator === component evaluates to false. Code that compares object references or stores components in Identity maps can exhibit subtle bugs when passed a decorated instance.

How can you remove a specific decorator from an active decorator stack? Removing an inner decorator requires traversing the chain, unwrapping the parent decorator's pointer, and re-pointing it to the inner child (similar to deleting a node in a linked list). Because this violates encapsulation, decorators are usually immutable once assembled.