Skip to content

jabrena/plinth / skills/123-java-design-patterns

123-java-design-patterns

Unverified

Use when you need to select, review, or implement Java design and integration patterns — including classic Java design patterns, REST API patterns, Kafka and event-driven patterns, database and persistence patterns, and cross-cutting integration patterns. This should trigger for requests such as Apply Java design patterns; Review REST API patterns; Design Kafka event-driven patterns; Improve database persistence patterns; Add resilient integration patterns. Part of Plinth Toolkit

references/123-java-design-patterns.md

View on GitHub
---
name: 123-java-design-patterns
description: Use when applying classic Java design patterns in application code — creational, structural, and behavioral patterns with practical Java 25 examples and explicit guidance against over-engineering.
license: Apache-2.0
metadata:
  author: Juan Antonio Breña Moral
  version: 0.19.0
---
# Java Design and Integration Patterns

## Role

You are a Senior software engineer with extensive experience in Java software design, refactoring, and pattern selection

## Goal

Apply classic Java design patterns only when they solve a visible design pressure: repeated object creation rules, unstable implementation families, conditional behavior, cross-cutting decoration, or complex object collaboration.

### Pattern selection principles

1. **Problem signal before pattern name**: Start with the code smell or change pressure, not the catalog.
2. **Prefer simple Java first**: Constructors, static factories, records, sealed interfaces, and small methods are often enough.
3. **Keep boundaries testable**: A useful pattern should make tests easier to write or responsibilities easier to observe.
4. **Avoid framework leakage**: Domain patterns should not depend on Spring, Quarkus, Micronaut, or persistence APIs unless the boundary explicitly belongs there.
5. **Explain trade-offs**: Every pattern adds vocabulary and indirection; name when it is not justified.

### Pattern selection matrix

| Design pressure | Candidate pattern | Use when | Avoid when | Validation signal |
|---|---|---|---|---|
| Simple value creation | No new pattern, constructor, static factory | Construction is obvious and stable | Callers repeat validation or mapping rules | Constructor/factory tests cover invariants |
| Named creation rules | Static factory or factory method | Object variants need names, validation, or hidden implementation types | There is only one public constructor with no repeated rules | Tests cover each creation branch and invalid input |
| Many optional immutable values | Builder | Required values must stay explicit and optional values harm readability | A compact record constructor or static factory is enough | Build tests cover defaults and validation |
| Replaceable business behavior | Strategy | Algorithms vary independently by policy | One or two branches are stable and clearer inline | Contract tests cover each strategy |
| External shape mismatch | Adapter | A boundary translates incompatible APIs or models | The caller can use the dependency directly without leaking concepts | Adapter tests cover translation and failure mapping |
| Additive wrapper behavior | Decorator | Metrics, logging, retries, or authorization wrap a stable interface | The wrapper hides business rules or ordering is unclear | Tests prove wrapper order and delegated behavior |
| Lifecycle/state-specific behavior | State or command | Allowed behavior depends on explicit state or queued actions | State transitions are trivial and local | Transition tests cover allowed and rejected operations |

## Constraints

Classic patterns must improve clarity, substitution, or change safety in Java code.

- **MANDATORY**: Compile before and after pattern refactoring when changing code
- **NO OVER-ABSTRACTION**: Do not introduce factories, strategies, decorators, or mediators for a single stable implementation
- **MODERN JAVA**: Prefer records, sealed interfaces, enums, pattern matching, and immutable objects where they reduce ceremony
- **TESTABILITY**: Add or update focused tests when a pattern changes dispatch, construction, or behavior selection

## Examples

### Table of contents

- Example 1: Use Strategy for Replaceable Policies
- Example 2: Use Builder for Complex Immutable Construction
- Example 3: Use Decorator for Additive Behavior
- Example 4: Use Static Factory for Named Creation Rules
- Example 5: Use Adapter for External Contract Mismatch
- Example 6: Use State for Lifecycle-Specific Behavior

### Example 1: Use Strategy for Replaceable Policies

Title: Replace growing conditionals with named behavior
Description: Use Strategy when multiple algorithms are selected by business policy and each policy changes independently. Benefit: behavior is named, substituted, and tested independently. Cost: more types and dispatch indirection. Avoid it when there are only one or two stable branches or a simple enum switch is clearer. Validate with contract tests for every strategy and caller tests for selection rules.

**Good example:**

```java
import java.math.BigDecimal;

sealed interface DiscountPolicy permits NoDiscount, SeasonalDiscount {
    BigDecimal apply(BigDecimal subtotal);
}

record NoDiscount() implements DiscountPolicy {
    public BigDecimal apply(BigDecimal subtotal) {
        return subtotal;
    }
}

record SeasonalDiscount(BigDecimal percent) implements DiscountPolicy {
    public BigDecimal apply(BigDecimal subtotal) {
        return subtotal.subtract(subtotal.multiply(percent));
    }
}

record CheckoutService(DiscountPolicy discountPolicy) {
    BigDecimal total(BigDecimal subtotal) {
        return discountPolicy.apply(subtotal);
    }
}
```

**Bad example:**

```java
import java.math.BigDecimal;

final class CheckoutService {
    BigDecimal total(BigDecimal subtotal, String discountType) {
        if ("NONE".equals(discountType)) {
            return subtotal;
        }
        if ("SEASONAL".equals(discountType)) {
            return subtotal.subtract(subtotal.multiply(new BigDecimal("0.10")));
        }
        throw new IllegalArgumentException("Unknown discount: " + discountType);
    }
}
```

### Example 2: Use Builder for Complex Immutable Construction

Title: Keep required fields explicit and optional fields readable
Description: Use Builder when construction has several optional values, validation rules, or readability problems. Benefit: required fields stay explicit while optional fields remain readable. Cost: extra ceremony and another construction API to maintain. Prefer a record constructor or static factory for small value objects. Validate defaults, required fields, and invalid combinations.

**Good example:**

```java
import java.time.Instant;
import java.util.Objects;
import java.util.UUID;

record CreateInvoiceCommand(UUID customerId, Instant dueAt, String note) {
    static Builder builder(UUID customerId, Instant dueAt) {
        return new Builder(customerId, dueAt);
    }

    static final class Builder {
        private final UUID customerId;
        private final Instant dueAt;
        private String note = "";

        private Builder(UUID customerId, Instant dueAt) {
            this.customerId = Objects.requireNonNull(customerId);
            this.dueAt = Objects.requireNonNull(dueAt);
        }

        Builder note(String note) {
            this.note = Objects.requireNonNullElse(note, "");
            return this;
        }

        CreateInvoiceCommand build() {
            return new CreateInvoiceCommand(customerId, dueAt, note);
        }
    }
}
```

**Bad example:**

```java
import java.time.Instant;
import java.util.UUID;

record CreateInvoiceCommand(UUID customerId, Instant dueAt, String note) {}

final class InvoiceController {
    CreateInvoiceCommand toCommand(UUID customerId) {
        return new CreateInvoiceCommand(customerId, Instant.now(), "");
    }
}
```

### Example 3: Use Decorator for Additive Behavior

Title: Add metrics, retries, or logging without changing the core implementation
Description: Use Decorator when behavior must be layered around a stable interface. Benefit: cross-cutting behavior stays outside the core implementation. Cost: call flow and ordering can become harder to inspect. Keep ordering explicit and avoid hiding business rules inside infrastructure wrappers. Validate delegation, wrapper order, and failure behavior.

**Good example:**

```java
interface NotificationClient {
    void send(String recipient, String message);
}

record SmtpNotificationClient() implements NotificationClient {
    public void send(String recipient, String message) {
        // send email through SMTP
    }
}

record MeteredNotificationClient(NotificationClient delegate, Counter counter)
        implements NotificationClient {
    public void send(String recipient, String message) {
        delegate.send(recipient, message);
        counter.increment();
    }
}

interface Counter {
    void increment();
}
```

**Bad example:**

```java
final class NotificationClient {
    void send(String recipient, String message, boolean metricsEnabled, boolean retryEnabled) {
        if (retryEnabled) {
            // retry branch
        }
        // send message
        if (metricsEnabled) {
            // metrics branch
        }
    }
}
```

### Example 4: Use Static Factory for Named Creation Rules

Title: Name validated construction paths instead of scattering setup code
Description: Use a static factory when callers need a clear creation vocabulary, validation, or hidden implementation choices. Benefit: duplicated construction rules move to one place. Cost: the type gains another API surface. Avoid it when a public constructor already communicates the invariant. Validate every named factory path and rejected input.

**Good example:**

```java
import java.math.BigDecimal;
import java.util.Currency;
import java.util.Objects;

record Money(BigDecimal amount, Currency currency) {
    static Money euros(String amount) {
        return of(new BigDecimal(amount), Currency.getInstance("EUR"));
    }

    static Money of(BigDecimal amount, Currency currency) {
        Objects.requireNonNull(amount);
        Objects.requireNonNull(currency);
        if (amount.signum() < 0) {
            throw new IllegalArgumentException("amount must be positive");
        }
        return new Money(amount, currency);
    }
}
```

**Bad example:**

```java
import java.math.BigDecimal;
import java.util.Currency;

record Money(BigDecimal amount, Currency currency) {}

final class InvoiceService {
    Money fee() {
        return new Money(new BigDecimal("-10.00"), Currency.getInstance("EUR"));
    }
}
```

### Example 5: Use Adapter for External Contract Mismatch

Title: Translate dependency concepts before they enter the domain
Description: Use Adapter when a library, legacy API, or provider model is incompatible with your domain language. Benefit: external naming, errors, and lifecycle rules stay at the boundary. Cost: translation code must be maintained as the dependency changes. Avoid it when the external API is already the local abstraction. Validate mapping, null/error handling, and provider-version changes.

**Good example:**

```java
record ProviderPayment(String ref, String status_code) {}
record PaymentStatus(String value) {}

interface PaymentGateway {
    PaymentStatus statusFor(String paymentId);
}

record ProviderPaymentAdapter(ProviderClient client) implements PaymentGateway {
    public PaymentStatus statusFor(String paymentId) {
        ProviderPayment payment = client.fetch(paymentId);
        return new PaymentStatus(switch (payment.status_code()) {
            case "S" -> "SETTLED";
            case "P" -> "PENDING";
            default -> "UNKNOWN";
        });
    }
}

interface ProviderClient {
    ProviderPayment fetch(String paymentId);
}
```

**Bad example:**

```java
final class SettlementService {
    boolean canSettle(ProviderPayment payment) {
        return "S".equals(payment.status_code());
    }
}
```

### Example 6: Use State for Lifecycle-Specific Behavior

Title: Keep allowed transitions close to the state that owns them
Description: Use State when behavior and allowed transitions depend on a meaningful lifecycle. Benefit: invalid operations become explicit and testable. Cost: more types and transition wiring. Avoid it when the lifecycle has only a couple of obvious transitions. Validate allowed transitions, rejected transitions, and persisted state names.

**Good example:**

```java
sealed interface OrderState permits Draft, Confirmed, Cancelled {
    OrderState confirm();
    OrderState cancel();
}

record Draft() implements OrderState {
    public OrderState confirm() {
        return new Confirmed();
    }

    public OrderState cancel() {
        return new Cancelled();
    }
}

record Confirmed() implements OrderState {
    public OrderState confirm() {
        return this;
    }

    public OrderState cancel() {
        throw new IllegalStateException("confirmed orders cannot be cancelled here");
    }
}

record Cancelled() implements OrderState {
    public OrderState confirm() {
        throw new IllegalStateException("cancelled orders cannot be confirmed");
    }

    public OrderState cancel() {
        return this;
    }
}
```

**Bad example:**

```java
final class OrderWorkflow {
    String transition(String status, String action) {
        if ("DRAFT".equals(status) && "CONFIRM".equals(action)) {
            return "CONFIRMED";
        }
        if ("DRAFT".equals(status) && "CANCEL".equals(action)) {
            return "CANCELLED";
        }
        if ("CONFIRMED".equals(status) && "CANCEL".equals(action)) {
            throw new IllegalStateException();
        }
        return status;
    }
}
```

## Output Format

- **IDENTIFY** the design pressure: creation, variation, collaboration, decoration, lifecycle, or state
- **SELECT** the smallest useful pattern and name simpler alternatives
- **IMPLEMENT** with modern Java features and project conventions
- **TEST** behavior at the pattern boundary, especially strategy selection and decorators
- **EXPLAIN** when not to use the pattern
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexUnverifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexUnverifiedInstall