jabrena/plinth / skills/123-java-design-patterns
123-java-design-patterns
UnverifiedUse 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
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.3 KB |
| references/123-cross-cutting-integration-patterns.md | markdown | 9.4 KB |
| references/123-database-persistence-patterns.md | markdown | 9.3 KB |
| references/123-java-design-patterns.md | markdown | 13.3 KB |
| references/123-kafka-event-driven-patterns.md | markdown | 9.0 KB |
| references/123-rest-api-patterns.md | markdown | 8.4 KB |
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 patternRelated skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 117k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 117k | Updated | Claude CodeCodex | Unverified | Install |