Java Design Patterns — Administrator & Developer Guide

1. Architecture Overview

Java Design Patterns is a Maven multi-module educational repository containing 166 self-contained design pattern implementations in Java. The project is structured as a flat collection of independent modules under a single parent POM — there is no runtime application, no deployment target, and no central entry point. Each module is a standalone unit that can be built, tested, and run independently.

The architecture is intentionally simple: a parent POM defines shared dependencies and plugin configuration, and each pattern module inherits from it while adding only pattern-specific code. The project's value is in its breadth, consistency, and educational quality — not in runtime complexity.

java-design-patterns/                    (parent POM, aggregator)
├── abstract-document/                   (pattern module)
│   ├── pom.xml                          (inherits parent)
│   ├── README.md                        (pattern documentation)
│   ├── etc/                             (UML diagrams)
│   └── src/
│       ├── main/java/com/iluwatar/...   (implementation + App.java)
│       └── test/java/com/iluwatar/...   (JUnit 5 tests)
├── abstract-factory/                    (same structure)
├── ...                                  (164 more pattern modules)
├── localization/                        (18+ language translations)
│   ├── ar/                              (Arabic)
│   ├── zh/                              (Chinese)
│   └── ...
└── pom.xml                              (root parent POM)

Component Inventory

Technology Stack

Note

Not every module uses every dependency. Spring Boot, H2, MongoDB, Guice, and HtmlUnit are only present in the modules that specifically demonstrate those technologies. Most pattern modules depend only on SLF4J/Logback, Lombok, and JUnit 5.

2. System Requirements

Development Environment

CI Environment

Important

The project has no runtime deployment requirements. It is a build-and-run-locally educational resource. There are no containers, no cloud deployments, and no production servers to manage.

3. Configuration Reference

The project has minimal configuration. All settings live in the root pom.xml as Maven properties.

Maven Properties (root pom.xml)

SonarCloud Properties

Additional Repositories

Tip

To override any version locally without modifying pom.xml, pass it as a Maven property: mvn install -Djunit.version=5.12.0 -DskipTests

4. Deployment & Scaling

This project is not deployed as a service. It is a source-code repository used for learning. The relevant operational concerns are:

Website

The project website at https://java-design-patterns.com/ is maintained separately. Pattern pages on the website are generated from the module README files using a static site generator.

Repository Hosting

Scaling the Module Count

Adding new pattern modules involves:

1. Create the module directory with the standard structure
2. Add the <module> entry to the root pom.xml <modules> section (alphabetical order)
3. Create a pom.xml inheriting from the parent:

<project>
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>com.iluwatar</groupId>
    <artifactId>java-design-patterns</artifactId>
    <version>1.26.0-SNAPSHOT</version>
  </parent>
  <artifactId>my-new-pattern</artifactId>
  <dependencies>
    <!-- pattern-specific deps only -->
  </dependencies>
</project>

Note

The project currently contains 166 modules. Maven handles this scale well, but full builds take several minutes. Use -pl <module> -am for targeted builds during development.

5. Operations

Build Operations

Full build (skip tests):

mvn clean install -DskipTests

Full build with tests:

mvn clean install

Single module build:

mvn compile -pl observer -am

Run a pattern demo:

cd <module>
mvn exec:java -Dexec.mainClass="com.iluwatar.<package>.App"

Run tests for one module:

mvn test -pl <module>

Tip

Use mvn -T 1C install -DskipTests to enable parallel builds (1 thread per CPU core). This can cut full build time significantly on multi-core machines.

Code Quality Operations

Run SonarCloud analysis:

mvn sonar:sonar \
  -Dsonar.host.url=https://sonarcloud.io \
  -Dsonar.organization=iluwatar \
  -Dsonar.projectKey=iluwatar_java-design-patterns

Generate code coverage report:

mvn test jacoco:report

Coverage reports are generated per module at <module>/target/site/jacoco/index.html.

Verify license headers:

mvn license:check

Note

The license plugin enforces the MIT license header on all source files. The model-view-viewmodel module is an exception — it uses the ZK framework under LGPL.

Dependency Management

Check for dependency updates:

mvn versions:display-dependency-updates

Check for plugin updates:

mvn versions:display-plugin-updates

Resolve all dependencies (useful for CI caching):

mvn dependency:go-offline

Common Maintenance Tasks

6. Performance

Build Performance

Full build characteristics on modern hardware:

Tip

For the fastest iteration during development, combine -pl, -am, and Maven's -o (offline) flag after the first full build: mvn test -pl observer -am -o

Memory Usage

7. Security

License Compliance

The MIT license is permissive — pattern code can be freely copied, modified, and used in commercial projects. The LGPL-licensed MVVM module requires compliance with LGPL terms if distributed as a library.

Warning

If you extract code from the model-view-viewmodel module for use in a proprietary project, review LGPL requirements carefully. The ZK framework dependency triggers LGPL obligations.

Dependency Security

The project uses well-known, actively maintained dependencies. Key security considerations:

Caution

Some pattern demos (e.g., serialized-entity, serialized-lob) use Java serialization. Do not use Java serialization with untrusted data in production systems — it is a known attack vector. These modules demonstrate the pattern concept only.

No Secrets or Credentials

The repository contains no secrets, API keys, database credentials, or sensitive configuration. All data access patterns use in-memory H2 databases or mock data.

8. Developer Internals

Repository Structure

java-design-patterns/
├── pom.xml                         Root POM (aggregator + dependency management)
├── lgpl-3.0.txt                    LGPL license for ZK framework
├── LICENSE.md                      MIT license
│
├── abstract-document/              Pattern module (×166, all same structure)
│   ├── README.md                   Pattern docs (intent, examples, diagrams)
│   ├── pom.xml                     Module POM (inherits root)
│   ├── etc/                        UML class diagrams
│   │   └── abstract-document.urm.png
│   └── src/
│       ├── main/java/com/iluwatar/abstractdocument/
│       │   ├── App.java            Entry point demo
│       │   ├── AbstractDocument.java
│       │   ├── Document.java       Core interface
│       │   └── domain/             Domain objects (Car, Part, etc.)
│       └── test/java/com/iluwatar/abstractdocument/
│           ├── AbstractDocumentTest.java
│           └── AppTest.java
│
├── localization/                   Translated READMEs
│   ├── ar/                         Arabic (most complete)
│   ├── bn/                         Bengali
│   ├── da/                         Danish
│   ├── de/                         German
│   ├── el/                         Greek
│   ├── es/                         Spanish
│   ├── fa/                         Persian
│   ├── fr/                         French
│   ├── hi/                         Hindi
│   ├── id/                         Indonesian
│   ├── it/                         Italian
│   ├── ja/                         Japanese
│   ├── mr/                         Marathi
│   ├── ne/                         Nepali
│   ├── pt/                         Portuguese
│   ├── ru/                         Russian
│   ├── si/                         Sinhala
│   ├── tr/                         Turkish
│   ├── ur/                         Urdu
│   └── zh/                         Chinese
│
└── (no other top-level directories)

Architecture Deep Dive

Parent POM Pattern

The root pom.xml uses Maven's <packaging>pom</packaging> aggregator pattern. It defines:

1. <modules> — All 166 pattern modules listed alphabetically
2. <dependencyManagement> — Version-locked dependencies available to all modules
3. <properties> — Centralized version strings
4. <build><pluginManagement> — Shared plugin configuration (compiler, surefire, JaCoCo, license)
5. <repositories> — JitPack for GitHub-hosted dependencies

Child modules inherit the parent and only declare the dependencies they actually need, without specifying versions (they inherit from <dependencyManagement>).

Module Independence

Each pattern module is fully self-contained:

• No cross-module dependencies. Pattern A never imports from pattern B
• No shared library module. Common utilities (if any) are duplicated by design
• No shared resources. Each module manages its own test data and config

This strict isolation means:

• Any module can be extracted and used independently
• Build failures in one module do not cascade
• New patterns can be added without touching existing code

Note

The only shared elements are the parent POM's dependency versions and the Lombok/SLF4J transitive dependencies that all modules use.

Entry Point Convention

Every pattern provides App.java at src/main/java/com/iluwatar/<patternpackage>/App.java with a public static void main(String[] args) method. This method:

1. Sets up the pattern participants (creates objects, wires dependencies)
2. Executes the pattern's core behavior
3. Logs output via SLF4J to demonstrate the result

The entry point serves as a living code example — it is both documentation and executable demo.

Test Convention

Every pattern provides test classes alongside the implementation:

• AppTest.java — Verifies App.main() runs without exceptions
• <PatternClass>Test.java — Unit tests for individual pattern participants
• Tests use JUnit 5 (@Test, assertThat, assertThrows)
• Mockito for behavior verification where needed
• system-lambda for capturing System.out output in tests

Module Reference

The following modules have source code analyzed in detail (HIGH-priority modules with source content):

Pipeline Pattern (pipeline/)

Demonstrates ordered processing stages. Key classes:

Usage:

var filters = new Pipeline<>(new RemoveAlphabetsHandler())
    .addHandler(new RemoveDigitsHandler())
    .addHandler(new ConvertToCharArrayHandler());
var output = filters.execute("GoYankees123!");

Reactor Pattern (reactor/)

NIO-based event demultiplexing with Spring-like channel handlers. Key classes:

Observer Pattern (observer/)

Classic publish-subscribe with weather data. Key classes:

Flux Pattern (flux/)

Unidirectional data flow. Key classes:

Event Sourcing (event-sourcing/)

Persists state as an immutable event log. Demonstrates DomainEventProcessor dispatching AccountCreateEvent, MoneyDepositEvent, MoneyTransferEvent to reconstruct state.

Service Layer (service-layer/)

Application boundary pattern with MagicService → SpellDao, SpellbookDao, WizardDao. Uses @Transactional-style patterns with in-memory data.

CQRS (command-query-responsibility-segregation/)

Separate read (QueryService) and write (CommandService) models operating on Author and Book entities.

Layered Architecture (layered-architecture/)

Clean separation into presentation → service → persistence layers using CakeBakingService, CakeDao, CakeToppingDao.

Code Patterns and Conventions

Naming Conventions

Logging

All modules use SLF4J with Logback. Most use Lombok's @Slf4j annotation:

@Slf4j
public class App {
  public static void main(String[] args) {
    LOGGER.info("Starting pattern demo");
  }
}

Some older modules use explicit logger creation:

private static final Logger logger = LoggerFactory.getLogger(App.class.getName());

Lombok Usage

Modern Java Features

The codebase uses modern Java idioms throughout:

• var for local variable type inference
• Switch expressions with arrow syntax
• Streams and lambdas for functional-style processing
• Map.of(), List.of() for immutable collection literals
• Optional for nullable return values
• record types where appropriate

Testing Strategy

Test Framework

• JUnit 5 (Jupiter) for all test classes
• Mockito 5 for mock creation and verification
• system-lambda for capturing System.out and System.exit in tests
• HtmlUnit for web-pattern integration tests

Test Coverage

The project uses JaCoCo for code coverage. Coverage reports are generated per-module and aggregated by SonarCloud.

# Generate coverage for a single module
mvn test jacoco:report -pl observer

# View the report
open observer/target/site/jacoco/index.html

Test Categories

Note

Concurrency pattern tests are inherently timing-sensitive. The project has a known open issue (#2977) regarding busy-waiting loops that can cause intermittent test failures under load.

Potential Improvements

Based on source analysis and community issues:

Contributing Guide

Prerequisites

• JDK 17+
• Maven 3.9+
• Understanding of the design pattern being contributed

Adding a New Pattern

1. Research — Ensure the pattern is documented in authoritative literature and is not already implemented
2. Create module directory with standard structure (see section 4)
3. Write the implementation following existing conventions:
   • App.java as entry point with SLF4J logging
   • Clean separation of pattern participants into individual files
   • Use Lombok where appropriate
4. Write comprehensive tests:
   • AppTest.java — verify main() runs without exception
   • Unit tests for each pattern participant
   • Edge case tests
5. Write the README following the template:
   • Intent (with YAML frontmatter: title, shortTitle, category, language, tag)
   • Real-world analogy
   • In plain words
   • Programmatic example with code blocks
   • Class diagram (generate UML and place in etc/)
   • Applicability
   • Known uses (JDK/real-world examples)
   • Consequences
   • Related patterns
   • Credits
6. Add module to root pom.xml <modules> in alphabetical order
7. Run full test suite to verify no regressions: mvn test
8. Submit pull request with pattern name and category in the title

README Frontmatter Format

---
title: Pattern Name
shortTitle: Pattern Name
category: Creational|Structural|Behavioral|Concurrency|...
language: en
tag:
  - Gang of Four
  - Extensibility
  - Performance
---

Code Style

• Follow existing patterns for consistency
• Use @Slf4j for logging (not manual LoggerFactory.getLogger())
• Use var for local variables where type is obvious
• Keep classes small and focused — one file per pattern participant
• No external code formatters are enforced, but match surrounding code style
• License header (MIT) required on all Java files — enforced by license-maven-plugin

Important

Every Java source file must include the MIT license header. Run mvn license:check to verify compliance before submitting a pull request. The header mentions the LGPL exception for the model-view-viewmodel module.

9. Integration Points

SonarCloud

The project integrates with SonarCloud for continuous code quality analysis:

• Organization: iluwatar
• Project key: iluwatar_java-design-patterns
• Quality gates: Applied per-module via sonar.moduleKey=${project.artifactId}
• Coverage: JaCoCo reports are uploaded automatically during analysis

JitPack

JitPack is configured as an additional Maven repository for dependencies hosted on GitHub that are not available on Maven Central:

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

Website

Pattern READMEs serve as the source content for the project website at https://java-design-patterns.com/. The YAML frontmatter in each README (title, shortTitle, category, language, tag) provides metadata for website navigation, categorization, and search.

Tip

When writing or updating a pattern README, ensure the YAML frontmatter is present and correctly formatted — it directly affects how the pattern appears on the website.