Java Design Patterns — User Guide

1. Quick Start

Java Design Patterns is the largest open-source collection of design pattern implementations in Java. Each pattern lives in its own Maven module with a self-contained App.java entry point, unit tests, UML class diagrams, and a detailed README explaining intent, real-world analogies, and trade-offs. The repository serves as both a learning resource and a reference library for software engineers at every level.

Key features:

• 166 design pattern implementations spanning Creational, Structural, Behavioral, Concurrency, Architectural, and more
• Every pattern has a runnable App.java demonstrating the concept end-to-end
• UML class diagrams in the etc/ directory for visual learners
• Comprehensive unit tests for every pattern using JUnit 5
• Multi-language README translations (Arabic, Bengali, Chinese, Danish, German, Spanish, French, Greek, Hindi, Indonesian, Italian, Japanese, Marathi, Nepali, Portuguese, Russian, Sinhala, Turkish, Urdu)
• Modern Java idioms — var, switch expressions, streams, lambdas, sealed classes

Prerequisites:

• Java 17 or later (JDK)
• Apache Maven 3.9+

Quick build and run:

git clone https://github.com/iluwatar/java-design-patterns.git
cd java-design-patterns
mvn compile -pl singleton -am

cd singleton
mvn exec:java -Dexec.mainClass="com.iluwatar.singleton.App"

Cthulhu=com.iluwatar.singleton.IvoryTower@...
Cthulhu=com.iluwatar.singleton.IvoryTower@...

Tip

You can run any pattern's demo the same way — replace singleton with the pattern module name (e.g., observer, strategy, builder).

What to explore next: Browse the full pattern catalog in section 3, pick a category that interests you, and run the demos.

2. Installation

System Requirements

Clone the Repository

git clone https://github.com/iluwatar/java-design-patterns.git
cd java-design-patterns

Important

The repository contains 3,500+ files. A shallow clone saves time if you only need the latest version: git clone --depth 1 https://github.com/iluwatar/java-design-patterns.git

Build All Patterns

mvn clean install -DskipTests

[INFO] Reactor Summary for Java Design Patterns 1.26.0-SNAPSHOT:
[INFO] java-design-patterns .......................... SUCCESS
[INFO] abstract-document ............................. SUCCESS
[INFO] abstract-factory .............................. SUCCESS
...
[INFO] BUILD SUCCESS

Build a Single Pattern

mvn compile -pl observer -am

The -pl flag selects the module; -am (also-make) builds its dependencies (the parent POM).

Verify Your Installation

mvn test -pl singleton

[INFO] Tests run: 5, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

Warning

Some pattern modules (e.g., microservices-*, health-check, anti-corruption-layer) use Spring Boot and download additional dependencies on first build. Ensure you have a stable internet connection.

IDE Setup

IntelliJ IDEA

1. File → Open → select the root pom.xml
2. Choose "Open as Project"
3. IntelliJ imports all 166 modules automatically
4. Run any App.java with the green play button

Eclipse

1. File → Import → Maven → Existing Maven Projects
2. Select the root directory
3. Eclipse discovers all submodules
4. Right-click any App.java → Run As → Java Application

VS Code

1. Install the Extension Pack for Java
2. Open the root folder
3. The Java extension detects the Maven structure
4. Click Run above any main method

Install Troubleshooting

Error: Unsupported class file major version 65

Your Maven or IDE is using an older JDK. Set JAVA_HOME to JDK 17+:

export JAVA_HOME=/path/to/jdk-17
mvn clean install -DskipTests

Error: Could not resolve dependencies

Maven cannot reach a repository. Check your network and proxy settings in ~/.m2/settings.xml. The project uses JitPack (https://jitpack.io) as an additional repository.

Error: OutOfMemoryError during build

Increase Maven's heap:

export MAVEN_OPTS="-Xmx2g"
mvn clean install -DskipTests

Error: Plugin execution not covered by lifecycle configuration (Eclipse)

This is an Eclipse/m2e issue. Go to Window → Preferences → Maven → Errors/Warnings and set "Plugin execution not covered" to "Warning" or "Ignore".

3. Pattern Catalog

The 166 patterns are organized by category. Each pattern module follows the same structure:

pattern-name/
├── README.md          ← Intent, explanation, code examples, class diagram
├── pom.xml            ← Module build config
├── etc/               ← UML diagrams (.png, .urm.png)
└── src/
    ├── main/java/     ← Implementation
    └── test/java/     ← Unit tests

Creational Patterns

Patterns that deal with object creation mechanisms.

Structural Patterns

Patterns that compose classes and objects into larger structures.

Behavioral Patterns

Patterns that manage algorithms and communication between objects.

Concurrency Patterns

Patterns for managing multi-threaded and asynchronous execution.

Architectural Patterns

Large-scale structural and organizational patterns.

Microservices Patterns

Data Access Patterns

Integration Patterns

Functional and Idiom Patterns

Other Patterns

4. Core Usage

Running a Pattern Demo

Every pattern includes an App.java with a main method:

# Build the pattern and its dependencies
mvn compile -pl <pattern-module> -am

# Run the demo
cd <pattern-module>
mvn exec:java -Dexec.mainClass="com.iluwatar.<package>.App"

For example, running the Observer pattern:

mvn compile -pl observer -am
cd observer
mvn exec:java -Dexec.mainClass="com.iluwatar.observer.App"

Weather: rainy, 15°C, 0.0 bar
Orcs: The weather changed, brace for rain!
Hobbits: The weather changed, better stay inside!

Note

The package name within com.iluwatar usually matches the module name with hyphens removed. For example, chain-of-responsibility becomes com.iluwatar.chainofresponsibility. Check the App.java in the pattern's src/main/java/ directory for the exact fully-qualified class name.

Reading a Pattern

Each pattern module README follows a consistent structure:

1. Intent — What problem does it solve?
2. Real-world analogy — A concrete scenario making the concept intuitive
3. In plain words — One-sentence explanation
4. Wikipedia/authoritative definition — Formal description
5. Programmatic example — Annotated Java code showing the pattern in action
6. Class diagram — UML visualization of the participants
7. Applicability — When to use (and when not to)
8. Known uses — Real-world JDK/library examples
9. Consequences — Trade-offs (benefits and drawbacks)
10. Related patterns — Links to complementary patterns
11. Credits — Books, articles, tutorials

Tip

Start with the "Programmatic example" section — it shows the pattern's essence in working code. Then read "Applicability" to understand when the pattern fits your specific problem.

Running Tests for a Pattern

mvn test -pl strategy

[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

Run tests for all patterns:

mvn test

Using Patterns in Your Own Projects

These patterns are educational implementations. To apply them in your codebase:

1. Study the pattern — Read the module README and App.java
2. Identify the participants — Note the interfaces, abstract classes, and concrete classes
3. Adapt to your domain — Rename classes to match your problem space
4. Simplify — Production code may not need all participants shown in the demo

Warning

Do not add java-design-patterns as a Maven dependency. It is a learning repository, not a reusable library. Copy and adapt the patterns you need into your own codebase.

Localized Content

Pattern READMEs are available in 18+ languages under localization/<language-code>/:

Access translations at localization/<code>/<pattern-name>/README.md.

5. Common Tasks

Finding the Right Pattern for a Problem

Goal: Identify which design pattern addresses your specific problem.

1. Identify the problem category:
   • "I need to create objects flexibly" → Creational
   • "I need to compose or adapt objects" → Structural
   • "I need to manage behavior or communication" → Behavioral
   • "I need to handle threads or async work" → Concurrency
   • "I need to organize large-scale structure" → Architectural
2. Scan the category table in section 3 for descriptions matching your need
3. Read the module README's "Applicability" section to confirm the fit
4. Run the demo to see the pattern in action

Comparing Related Patterns

Goal: Understand the difference between similar patterns.

Prerequisites: Two or more pattern modules to compare.

1. Read both READMEs side by side (focus on "Intent" and "Applicability")
2. Run both demos and compare output
3. Look at the class diagrams in etc/ for structural differences
4. Check the "Related Patterns" section in each README for explicit comparisons

Common comparisons:

Building a Subset of Patterns

Goal: Build only the patterns you care about to save time.

# Build three specific patterns
mvn compile -pl singleton,observer,strategy -am

# Run all tests for just those three
mvn test -pl singleton,observer,strategy

Studying Concurrency Patterns Safely

Goal: Understand thread-safe patterns without race condition surprises.

1. Read the pattern README carefully — concurrency patterns often include timing-sensitive behavior
2. Run the demo and observe the interleaved output:

mvn compile -pl active-object -am
cd active-object
mvn exec:java -Dexec.mainClass="com.iluwatar.activeobject.App"

Orc0 is eating!
Orc0 has finished eating!
Orc0 has started to roam the wastelands.
Orc1 is eating!
...

3. Examine the test in src/test/java/ for assertions about concurrent behavior
4. Modify timing parameters in App.java to observe different interleavings

Note

Output ordering for concurrency demos may vary between runs — this is expected behavior, not a bug.

Using the Microservices Patterns

Goal: Run the multi-module microservices examples.

Several microservices patterns use Spring Boot and involve multiple services:

# Build the microservices API Gateway example
mvn compile -pl microservices-api-gateway -am

Important

Microservices patterns require Spring Boot (spring-boot-starter-web) and may start embedded web servers. Check each module's pom.xml for specific dependencies and port configuration.

The microservices modules typically include:

• A parent module with shared configuration
• Individual service modules (e.g., image-microservice, price-microservice)
• A gateway or aggregator module

Contributing a New Pattern

Goal: Add a new design pattern to the collection.

1. Check existing patterns to avoid duplication
2. Check open issues — the community tracks requested patterns (e.g., Thread-Specific Storage #3225)
3. Create a new module directory following the standard structure:

my-pattern/
├── README.md
├── pom.xml
├── etc/
│   └── my-pattern.urm.png
└── src/
    ├── main/java/com/iluwatar/mypattern/
    │   └── App.java
    └── test/java/com/iluwatar/mypattern/
        └── AppTest.java

4. Add the module to the root pom.xml <modules> section
5. Follow the existing README format (Intent, Real-world analogy, Programmatic example, Class diagram, Applicability, Known uses, Consequences, Related patterns, Credits)
6. Write comprehensive JUnit 5 tests

See the Admin Guide for full contributing details and code conventions.

6. Troubleshooting

Error: Unsupported class file major version 65

Cause: Your JDK version is too old. The project requires Java 17+.

Solution:

1. Check your Java version:

   java -version
   

2. Install JDK 17 or later
3. Set JAVA_HOME and ensure mvn -version shows the correct JDK

Prevention: Use a version manager like SDKMAN to install and switch between JDK versions.

Error: Could not resolve dependencies

Cause: Maven cannot reach Maven Central or JitPack.

Solution:

1. Check internet connectivity
2. Check proxy settings in ~/.m2/settings.xml
3. Clear the local cache and rebuild:

   rm -rf ~/.m2/repository/com/iluwatar
   mvn clean install -DskipTests
   

Prevention: Keep ~/.m2/settings.xml configured for your environment and proxy.

Error: OutOfMemoryError during full build

Cause: Building all 166 modules requires significant heap space.

Solution:

export MAVEN_OPTS="-Xmx2g -XX:MaxMetaspaceSize=512m"
mvn clean install -DskipTests

Prevention: Build only the modules you need with -pl.

Tests fail intermittently in concurrency modules

Cause: Timing-dependent tests may behave differently under system load. Known issue: busy-waiting loops in some patterns (#2977).

Solution:

1. Re-run the failing test in isolation:

   mvn test -pl <module-name>
   

2. If the failure persists, check the issue tracker for known timing bugs
3. Increase test timeouts if running on CI with limited resources

Prevention: Run concurrency tests individually rather than in a full build under heavy system load.

Warning

Some patterns use Thread.sleep() for demonstration purposes. These sleeps can cause test flakiness in resource-constrained environments.

Spring Boot patterns fail to start

Cause: Port conflicts or missing Spring dependencies.

Solution:

1. Check if another process is using the default port (usually 8080):

   lsof -i :8080
   

2. Ensure all dependencies are downloaded:

   mvn dependency:resolve -pl <module-name>
   

Prevention: Stop other local servers before running Spring-based pattern demos.

IDE shows errors but Maven build succeeds

Cause: IDE index is out of sync with Maven's dependency resolution.

Solution:

1. IntelliJ: File → Invalidate Caches → Invalidate and Restart
2. Eclipse: Right-click project → Maven → Update Project
3. VS Code: Ctrl+Shift+P → "Java: Clean Java Language Server Workspace"

Prevention: Run mvn install -DskipTests from the command line after pulling changes, then refresh your IDE.

Tip

If only a few modules show errors, build just those with mvn compile -pl <module> -am and re-import.

Lombok annotations not recognized by IDE

Cause: Lombok requires annotation processing support in the IDE.

Solution:

1. IntelliJ: Settings → Build → Compiler → Annotation Processors → Enable
2. Eclipse: Install the Lombok plugin from lombok.jar (run java -jar lombok.jar)
3. VS Code: The Java extension handles Lombok automatically with the correct dependency

Prevention: Install the Lombok IDE plugin before importing the project.

7. FAQ

Q: What Java version do I need?

JDK 17 or later. The project uses modern Java features including var local variable type inference, switch expressions, and streams.

Q: Can I use these patterns as a library dependency?

No. This is an educational repository. Copy and adapt the specific pattern code you need into your own project. The patterns are intentionally self-contained for learning purposes.

Q: How are these patterns different from the Gang of Four (GoF) book?

The repository includes all 23 original GoF patterns plus over 140 additional patterns from other authoritative sources — Martin Fowler's enterprise patterns, game programming patterns, concurrency patterns, microservices patterns, and modern Java idioms. The implementations use modern Java rather than the C++/Smalltalk of the original book.

Q: Why are some READMEs in other languages?

The project has an active community of translators. English READMEs live at <pattern>/README.md; translations are in localization/<language-code>/<pattern>/README.md. Not every pattern has been translated to every language.

Q: Is model-view-viewmodel licensed differently?

Yes. The MVVM module uses the ZK framework, which is licensed under LGPL (see lgpl-3.0.txt in the repository root). All other modules are MIT-licensed.

Q: Why do some modules use Spring Boot?

Patterns like microservices, health check, anti-corruption layer, and CQRS benefit from a real web framework to demonstrate their concepts. These modules use Spring Boot 3.4.4.

Q: How do I know which pattern to study first?

Start with the classic GoF patterns: Singleton, Factory Method, Observer, Strategy, Decorator, and Adapter. These are the most widely used and provide a foundation for understanding more complex patterns.

Q: Where do I find the UML diagrams?

Each pattern has a class diagram in its etc/ directory (usually etc/<pattern-name>.urm.png or etc/<pattern-name>.png).

Q: How can I contribute a pattern translation?

Create a directory at localization/<language-code>/<pattern-name>/, add a README.md following the existing English README structure, and submit a pull request.

Q: Why is the version 1.26.0-SNAPSHOT?

SNAPSHOT is Maven's convention for a development version. This is the canonical version of the repository — there are no published releases to Maven Central because this is a learning resource, not a library.