Intermediate

import java.util.HashMap;
import java.util.Map;
 
// => PORT: defines what the application NEEDS from storage
// => The core depends on this abstraction, never on a real DB class
interface UserRepository {
    void save(User user);           // => persistence contract
    User findById(String userId);   // => retrieval contract; null if not found
}
 
// => PORT: defines what the application NEEDS from notifications
interface NotifierPort {
    void sendWelcome(String email); // => notification contract
}
 
// => ENTITY: pure domain data, no infrastructure knowledge
class User {
    final String id;     // => domain identity
    final String email;  // => entity attribute, not a DB column
    final String name;   // => owned by the application core
 
    User(String id, String email, String name) {
        // => constructor enforces required fields
        this.id = id;
        this.email = email;
        this.name = name;
    }
}
 
// => APPLICATION SERVICE: orchestrates domain logic using ports only
// => Never imports JDBC, JavaMail, or HTTP — only port interfaces
class UserService {
    private final UserRepository repo;
    // => injected port — could be DB or in-memory
    private final NotifierPort notifier;
    // => injected port — could be email or SMS
 
    UserService(UserRepository repo, NotifierPort notifier) {
        this.repo = repo;
        this.notifier = notifier;
    }
 
    User register(String userId, String email, String name) {
        User user = new User(userId, email, name); // => create domain object
        repo.save(user);                            // => persist via port
        notifier.sendWelcome(email);               // => notify via port
        return user;                               // => return domain object, not DTO
    }
}
 
// => ADAPTER (driven): concrete implementation of UserRepository port
// => Lives in infrastructure layer — swappable without changing UserService
class InMemoryUserRepository implements UserRepository {
    private final Map<String, User> store = new HashMap<>();
    // => in-memory store for tests/demos
 
    @Override
    public void save(User user) {
        store.put(user.id, user); // => stores by ID key
    }
 
    @Override
    public User findById(String userId) {
        return store.get(userId); // => returns null if not found
    }
}
 
// => ADAPTER (driven): concrete implementation of NotifierPort
class ConsoleNotifier implements NotifierPort {
    @Override
    public void sendWelcome(String email) {
        System.out.println("Welcome email sent to " + email);
        // => simulates email send; swap with SmtpNotifier in production
    }
}
 
// => ADAPTER (driving): CLI adapter calls the application core via UserService
// => Real apps may have an HTTP adapter alongside this CLI adapter
static void cliRegister(UserService service, String userId, String email, String name) {
    User user = service.register(userId, email, name); // => delegates to core
    System.out.println("Registered: " + user.name);    // => adapter formats output
}
 
// wire up adapters
InMemoryUserRepository repo = new InMemoryUserRepository();
// => swap to JpaUserRepository in production
ConsoleNotifier notifier = new ConsoleNotifier();
// => swap to SmtpNotifier in production
UserService service = new UserService(repo, notifier);
// => core receives ports via DI
 
cliRegister(service, "u1", "alice@example.com", "Alice");
// => Output: Welcome email sent to alice@example.com
// => Output: Registered: Alice
 
User found = repo.findById("u1");
System.out.println(found.email); // => Output: alice@example.com

import java.util.HashMap;
import java.util.List;
import java.util.Map;
 
// ENTITIES LAYER — enterprise business rules, no imports from outer layers
// => Entity encapsulates core business rules independent of any framework
class OrderItem {
    final String productId; // => value by identity, not by object reference
    final double price;     // => snapshot price at order time
    final int qty;          // => quantity ordered
 
    OrderItem(String productId, double price, int qty) {
        this.productId = productId;
        this.price = price;
        this.qty = qty;
    }
}
 
class Order {
    final String id;           // => entity identity
    final List<OrderItem> items; // => domain data
    final String customerId;   // => relationship by ID, not object reference
 
    Order(String id, List<OrderItem> items, String customerId) {
        this.id = id;
        this.items = items;
        this.customerId = customerId;
    }
 
    // => business rule lives here, not in the use case or controller
    double getTotal() {
        return items.stream()
            .mapToDouble(i -> i.price * i.qty) // => price * qty per item
            .sum(); // => accumulates to final total
    }
}
 
// USE CASES LAYER — application business rules, depends only on entities
// => Repository interface belongs to use cases layer (dependency inversion)
// => Use case defines what it needs; infrastructure provides the implementation
interface OrderRepository {
    void save(Order order); // => persistence abstraction
}
 
// => Use case implementation — pure business orchestration, no HTTP/DB code
class PlaceOrderInteractor {
    private final OrderRepository repo;
    // => repo injected, satisfies dependency inversion
 
    PlaceOrderInteractor(OrderRepository repo) {
        this.repo = repo;
    }
 
    Order execute(String customerId, List<OrderItem> items) {
        String id = "ord-" + System.currentTimeMillis(); // => generate order ID
        Order order = new Order(id, items, customerId);   // => create entity
        repo.save(order); // => persist via repository port
        return order;     // => return entity, not DB row
    }
}
 
// INTERFACE ADAPTERS LAYER — converts data between use cases and frameworks
// => Controller translates HTTP request into use case input
class OrderController {
    private final PlaceOrderInteractor useCase;
    // => depends on use case class (or interface), not infrastructure
 
    OrderController(PlaceOrderInteractor useCase) {
        this.useCase = useCase;
    }
 
    Map<String, Object> handleRequest(String customerId, List<OrderItem> items) {
        Order order = useCase.execute(customerId, items);
        // => invoke use case with domain-shaped input
        return Map.of("orderId", order.id, "total", order.getTotal());
        // => presenter maps entity to HTTP-shaped output
    }
}
 
// FRAMEWORKS LAYER — in-memory adapter (stands in for a real DB adapter)
class InMemoryOrderRepo implements OrderRepository {
    private final Map<String, Order> store = new HashMap<>();
    // => storage detail hidden from use cases
 
    @Override
    public void save(Order order) {
        store.put(order.id, order); // => concrete persistence
    }
}
 
// wire layers together (this wiring itself lives in the frameworks layer)
InMemoryOrderRepo repo = new InMemoryOrderRepo();
// => outer layer provides implementation
PlaceOrderInteractor interactor = new PlaceOrderInteractor(repo);
// => use case receives repo
OrderController controller = new OrderController(interactor);
// => adapter receives use case
 
Map<String, Object> result = controller.handleRequest(
    "c1", List.of(new OrderItem("p1", 10.0, 2))
);
System.out.println(result); // => Output: {orderId=ord-..., total=20.0}

import java.util.HashMap;
import java.util.Map;
import java.util.Objects;
 
// => DOMAIN MODEL (innermost ring) — pure business objects, zero dependencies
final class Money {
    final double amount;  // => value in currency units
    final String currency; // => ISO 4217 code, e.g., "USD"
 
    Money(double amount, String currency) {
        this.amount = amount;
        this.currency = currency;
    }
 
    Money add(Money other) {
        if (!Objects.equals(this.currency, other.currency))
            throw new IllegalArgumentException("Currency mismatch");
            // => domain rule enforced here
        return new Money(this.amount + other.amount, this.currency);
        // => returns new Money (immutable pattern)
    }
}
 
// => ENTITY: product with a domain-typed price
class Product {
    final String id;    // => identity
    final String name;  // => display name
    final Money price;  // => price is a domain concept, not a raw double
 
    Product(String id, String name, Money price) {
        this.id = id;
        this.name = name;
        this.price = price;
    }
}
 
// => DOMAIN SERVICES (second ring) — stateless operations on domain objects
// => Domain services operate on domain entities; they have no infrastructure calls
class PricingService {
    Money applyDiscount(Money price, double discountPct) {
        double discounted = price.amount * (1 - discountPct / 100);
        // => computes discounted amount
        return new Money(Math.round(discounted * 100.0) / 100.0, price.currency);
        // => preserves currency, rounds to cents
    }
}
 
// => APPLICATION SERVICES (third ring) — orchestrates domain + domain services
// => Depends on domain model and domain services; not on infrastructure
class ProductCatalogService {
    private final PricingService pricer;
    // => domain service injected
 
    ProductCatalogService(PricingService pricer) {
        this.pricer = pricer;
    }
 
    Money getDiscountedPrice(Product product, double discountPct) {
        return pricer.applyDiscount(product.price, discountPct);
        // => application logic: which domain service to call and when
    }
}
 
// => REPOSITORY PORT (third ring, owned by application) — infrastructure contract
// => Defined here so infrastructure depends inward on this interface
interface ProductRepository {
    Product find(String productId); // => contract; null if not found
}
 
// => INFRASTRUCTURE (outermost ring) — implements repository port
class InMemoryProductRepository implements ProductRepository {
    private final Map<String, Product> data = new HashMap<>();
    // => in-memory store
 
    @Override
    public Product find(String productId) {
        return data.get(productId); // => concrete retrieval
    }
 
    void add(Product product) {
        data.put(product.id, product); // => concrete persistence
    }
}
 
// demo wiring — infrastructure created last, domain created first
InMemoryProductRepository repo = new InMemoryProductRepository();
repo.add(new Product("p1", "Widget", new Money(100.0, "USD")));
// => seed data
 
PricingService pricer = new PricingService();       // => domain service, no infra
ProductCatalogService catalog = new ProductCatalogService(pricer); // => app service
 
Product product = repo.find("p1");          // => retrieve from outer ring
Money discounted = catalog.getDiscountedPrice(product, 10);
// => applies 10% discount via domain service
System.out.println(discounted.currency + " " + discounted.amount);
// => Output: USD 90.0

import java.util.ArrayList;
import java.util.Date;
import java.util.List;
import java.util.function.Consumer;
 
// => EventBus: subject that holds observers and broadcasts events
// => Observers register themselves; the bus doesn't care what they do
// => Generic type T ensures type-safety per event kind
class EventBus<T> {
    private final List<Consumer<T>> handlers = new ArrayList<>();
    // => list grows as handlers subscribe; shrinks on unsubscribe
 
    void subscribe(Consumer<T> handler) {
        handlers.add(handler); // => add observer to list
    }
 
    void unsubscribe(Consumer<T> handler) {
        handlers.remove(handler);
        // => remove by reference equality; remaining handlers unaffected
    }
 
    void publish(T event) {
        for (Consumer<T> handler : handlers) {
            handler.accept(event); // => notify each observer in registration order
        }
        // => if one handler throws, subsequent handlers are skipped — add try/catch in production
    }
}
 
// => DOMAIN EVENT: named, immutable record of what happened
class UserRegistered {
    final String userId;    // => who registered
    final String email;     // => where to send welcome
    final Date timestamp;   // => when it happened
 
    UserRegistered(String userId, String email, Date timestamp) {
        this.userId = userId;
        this.email = email;
        this.timestamp = timestamp;
    }
}
 
// wire up: create bus and register observers
EventBus<UserRegistered> bus = new EventBus<>();
// => typed bus for UserRegistered events only
 
// => OBSERVER 1: sends welcome email
bus.subscribe(event -> {
    System.out.println("Sending welcome to " + event.email);
    // => in production: call email service API here
});
 
// => OBSERVER 2: writes audit log
bus.subscribe(event -> {
    System.out.println("Audit: user " + event.userId + " registered at " + event.timestamp);
    // => in production: write to append-only audit table
});
 
// => OBSERVER 3: increments stats counter
bus.subscribe(event -> {
    System.out.println("Stats: new user registered");
    // => in production: increment Prometheus counter
});
 
bus.publish(new UserRegistered("u1", "alice@example.com", new Date()));
// => Output: Sending welcome to alice@example.com
// => Output: Audit: user u1 registered at ...
// => Output: Stats: new user registered
// => all three handlers fired without the publisher knowing about any of them

import java.time.Instant;
import java.util.*;
import java.util.function.Consumer;
 
// => DOMAIN EVENT BASE: every event has an occurredAt timestamp
abstract class DomainEvent {
    final Instant occurredAt = Instant.now();
    // => set at creation time so events are immutable records of the past
}
 
// => DOMAIN EVENTS: past-tense names (OrderPlaced, not PlaceOrder)
class OrderPlaced extends DomainEvent {
    final String orderId;     // => which order was placed
    final String customerId;  // => who placed it
    final double total;       // => enough data for handlers without DB lookups
 
    OrderPlaced(String orderId, String customerId, double total) {
        this.orderId = orderId;
        this.customerId = customerId;
        this.total = total;
    }
}
 
class OrderCancelled extends DomainEvent {
    final String orderId; // => which order was cancelled
    final String reason;  // => why — useful for analytics and customer comms
 
    OrderCancelled(String orderId, String reason) {
        this.orderId = orderId;
        this.reason = reason;
    }
}
 
// => AGGREGATE: raises domain events as part of state transitions
class Order {
    final String id;
    final String customerId;
    final double total;
    String status = "PENDING";                   // => initial state
    private final List<DomainEvent> events = new ArrayList<>();
    // => events collected here, NOT yet dispatched
 
    Order(String id, String customerId, double total) {
        this.id = id;
        this.customerId = customerId;
        this.total = total;
    }
 
    void place() {
        this.status = "PLACED";                   // => state change
        events.add(new OrderPlaced(id, customerId, total));
        // => record event for later dispatch
    }
 
    void cancel(String reason) {
        if (!"PLACED".equals(status))
            throw new IllegalStateException("Cannot cancel order in status " + status);
            // => business rule enforced before event is raised
        this.status = "CANCELLED";               // => state change
        events.add(new OrderCancelled(id, reason));
    }
 
    List<DomainEvent> popEvents() {
        List<DomainEvent> drained = new ArrayList<>(events);
        events.clear(); // => caller drains events; aggregate starts fresh
        return drained;
    }
}
 
// => EVENT DISPATCHER: collects events from aggregates and notifies handlers
class EventDispatcher {
    private final Map<Class<?>, List<Consumer<DomainEvent>>> handlers = new HashMap<>();
    // => maps event type to list of handlers
 
    @SuppressWarnings("unchecked")
    <T extends DomainEvent> void register(Class<T> type, Consumer<T> handler) {
        handlers.computeIfAbsent(type, k -> new ArrayList<>())
                .add(e -> handler.accept((T) e));
        // => multiple handlers per event type are supported
    }
 
    void dispatch(List<DomainEvent> events) {
        for (DomainEvent event : events) {
            for (Consumer<DomainEvent> h : handlers.getOrDefault(event.getClass(), List.of())) {
                h.accept(event); // => each handler called with the event
            }
        }
    }
}
 
// demo: place then cancel an order
EventDispatcher dispatcher = new EventDispatcher();
dispatcher.register(OrderPlaced.class,
    e -> System.out.println("Email: order " + e.orderId + " placed, total $" + e.total));
// => handler 1: send confirmation email
dispatcher.register(OrderCancelled.class,
    e -> System.out.println("Refund triggered: " + e.orderId + ", reason: " + e.reason));
// => handler 2: trigger refund workflow
 
Order order = new Order("o1", "c1", 49.99);
order.place();                        // => state: PENDING -> PLACED, event queued
dispatcher.dispatch(order.popEvents());
// => Output: Email: order o1 placed, total $49.99
 
order.cancel("Customer request");     // => state: PLACED -> CANCELLED, event queued
dispatcher.dispatch(order.popEvents());
// => Output: Refund triggered: o1, reason: Customer request

import java.time.Instant;
import java.util.*;
import java.util.function.Consumer;
 
// => MESSAGE BROKER SIMULATION: in-memory topic-based pub/sub
// => In production, replace with Kafka, RabbitMQ, or AWS SQS
class MessageBroker {
    private final Map<String, List<Consumer<Object>>> topics = new HashMap<>();
    // => each topic holds a list of consumer callbacks
 
    @SuppressWarnings("unchecked")
    <T> void subscribe(String topic, Consumer<T> consumer) {
        topics.computeIfAbsent(topic, k -> new ArrayList<>())
              .add(msg -> consumer.accept((T) msg));
        // => consumer registered for this topic
    }
 
    void publish(String topic, Object message) {
        List<Consumer<Object>> consumers = topics.getOrDefault(topic, List.of());
        // => get all consumers; empty list if topic has no subscribers
        for (Consumer<Object> c : consumers) {
            c.accept(message); // => deliver to each consumer
        }
        // => in production, broker delivers asynchronously via Kafka partition
    }
}
 
// => DOMAIN EVENT: something that happened in the Order service
class OrderShipped {
    final String orderId;      // => which order shipped
    final String trackingCode; // => courier tracking reference
    final String shippedAt;    // => ISO timestamp
 
    OrderShipped(String orderId, String trackingCode, String shippedAt) {
        this.orderId = orderId;
        this.trackingCode = trackingCode;
        this.shippedAt = shippedAt;
    }
}
 
// => PRODUCER SERVICE: publishes events, does not know about consumers
class OrderService {
    private final MessageBroker broker;
    // => broker injected; producer never references consumer classes directly
 
    OrderService(MessageBroker broker) {
        this.broker = broker;
    }
 
    void shipOrder(String orderId, String trackingCode) {
        OrderShipped event = new OrderShipped(orderId, trackingCode, Instant.now().toString());
        // => capture shipping time in event
        broker.publish("order.shipped", event);
        // => publishes to topic — does not call notification or warehouse services directly
        System.out.println("Order " + orderId + " shipped");
    }
}
 
// => CONSUMER 1: notification service — listens independently
class NotificationService {
    void onOrderShipped(OrderShipped event) {
        System.out.println("Notif: send tracking " + event.trackingCode + " to customer for order " + event.orderId);
        // => in production: call email/SMS provider API
    }
}
 
// => CONSUMER 2: warehouse service — listens independently
class WarehouseService {
    void onOrderShipped(OrderShipped event) {
        System.out.println("Warehouse: update inventory for order " + event.orderId);
        // => in production: decrement stock counts in warehouse DB
    }
}
 
// wire up
MessageBroker broker = new MessageBroker();         // => in production: Kafka client
NotificationService notifier = new NotificationService();
WarehouseService warehouse = new WarehouseService();
 
broker.subscribe("order.shipped", (OrderShipped e) -> notifier.onOrderShipped(e));
// => notification service subscribes to topic
broker.subscribe("order.shipped", (OrderShipped e) -> warehouse.onOrderShipped(e));
// => warehouse service subscribes to same topic — independent of notification
 
OrderService orderService = new OrderService(broker);
orderService.shipOrder("o1", "TRK-9876");
// => Output: Order o1 shipped
// => Output: Notif: send tracking TRK-9876 to customer for order o1
// => Output: Warehouse: update inventory for order o1
// => both consumers received the event independently

// => STRATEGY INTERFACE: defines the algorithm contract
interface ShippingStrategy {
    double calculate(double weightKg, double distanceKm);
    // => every strategy must implement this signature
}
 
// => CONCRETE STRATEGY 1: flat rate regardless of weight/distance
class FlatRateStrategy implements ShippingStrategy {
    private final double rate; // => configurable flat fee
 
    FlatRateStrategy(double rate) {
        this.rate = rate;
    }
 
    @Override
    public double calculate(double weightKg, double distanceKm) {
        return rate; // => ignores inputs — always same price
        // => Use when: subscription-based shipping or simple pricing tiers
    }
}
 
// => CONCRETE STRATEGY 2: price based on weight
class WeightBasedStrategy implements ShippingStrategy {
    private final double pricePerKg; // => cost per kilogram
 
    WeightBasedStrategy(double pricePerKg) {
        this.pricePerKg = pricePerKg;
    }
 
    @Override
    public double calculate(double weightKg, double distanceKm) {
        return weightKg * pricePerKg; // => heavier = more expensive
        // => distance ignored — Use when: local delivery with flat zone pricing
    }
}
 
// => CONCRETE STRATEGY 3: free shipping (zero cost always)
class FreeShippingStrategy implements ShippingStrategy {
    @Override
    public double calculate(double weightKg, double distanceKm) {
        return 0.0; // => promotional: customer pays nothing
        // => Use when: orders over threshold or loyalty program members
    }
}
 
// => CONTEXT: uses whatever strategy is injected
class ShippingCalculator {
    private ShippingStrategy strategy;
    // => accepts any ShippingStrategy implementation
 
    ShippingCalculator(ShippingStrategy strategy) {
        this.strategy = strategy;
    }
 
    void setStrategy(ShippingStrategy strategy) {
        this.strategy = strategy; // => swap strategy at runtime
    }
 
    double getCost(double weightKg, double distanceKm) {
        return strategy.calculate(weightKg, distanceKm);
        // => delegates entirely to strategy — no if/else here
    }
}
 
// runtime selection: choose strategy based on business conditions
double orderTotal = 120.0;
ShippingStrategy strategy;
if (orderTotal >= 100) {
    strategy = new FreeShippingStrategy();       // => orders over $100 ship free
} else if (orderTotal >= 50) {
    strategy = new FlatRateStrategy(5.0);        // => medium orders: flat $5
} else {
    strategy = new WeightBasedStrategy(2.5);     // => small orders: by weight
}
 
ShippingCalculator calculator = new ShippingCalculator(strategy);
double cost = calculator.getCost(2.0, 50.0);
System.out.printf("Shipping cost: $%.2f%n", cost);
// => Output: Shipping cost: $0.00 (free shipping applied)
 
// swap strategy at runtime — context code unchanged
calculator.setStrategy(new WeightBasedStrategy(2.5));
double cost2 = calculator.getCost(2.0, 50.0);
System.out.printf("Weight-based cost: $%.2f%n", cost2);
// => Output: Weight-based cost: $5.00

import java.util.HashMap;
import java.util.Map;
import java.util.function.Supplier;
 
// => PRODUCT INTERFACE: what all created objects share
// => Factory returns this type — callers depend only on this interface
interface PaymentProcessor {
    String process(double amount); // => returns transaction ID
    String getName();              // => processor name for logging
}
 
// => CONCRETE PRODUCT 1: Stripe payment implementation
// => Caller never imports this class directly — factory owns instantiation
class StripeProcessor implements PaymentProcessor {
    @Override
    public String getName() { return "Stripe"; }
 
    @Override
    public String process(double amount) {
        String txId = "stripe_" + System.currentTimeMillis();
        // => simulated transaction ID; real impl calls Stripe SDK
        System.out.printf("Stripe: charged $%.2f, tx=%s%n", amount, txId);
        return txId; // => return transaction reference to caller
    }
}
 
// => CONCRETE PRODUCT 2: PayPal payment implementation
class PayPalProcessor implements PaymentProcessor {
    @Override
    public String getName() { return "PayPal"; }
 
    @Override
    public String process(double amount) {
        String txId = "pp_" + System.currentTimeMillis();
        // => simulated PayPal transaction ID
        System.out.printf("PayPal: charged $%.2f, tx=%s%n", amount, txId);
        return txId;
    }
}
 
// => CONCRETE PRODUCT 3: bank transfer implementation
class BankTransferProcessor implements PaymentProcessor {
    @Override
    public String getName() { return "BankTransfer"; }
 
    @Override
    public String process(double amount) {
        String txId = "bt_" + System.currentTimeMillis();
        // => simulated bank reference number
        System.out.printf("BankTransfer: initiated $%.2f, ref=%s%n", amount, txId);
        return txId;
    }
}
 
// => FACTORY: registry maps type keys to factory functions (Suppliers)
// => Caller never calls new StripeProcessor() directly — factory owns creation
class PaymentProcessorFactory {
    private static final Map<String, Supplier<PaymentProcessor>> REGISTRY = new HashMap<>();
    // => static registry populated once at class load
 
    static {
        REGISTRY.put("stripe",        StripeProcessor::new);
        // => factory function per type — add new types here without if/else
        REGISTRY.put("paypal",        PayPalProcessor::new);
        REGISTRY.put("bank_transfer", BankTransferProcessor::new);
    }
 
    static PaymentProcessor create(String type) {
        Supplier<PaymentProcessor> factory = REGISTRY.get(type);
        // => look up factory function for the requested type
        if (factory == null) {
            throw new IllegalArgumentException("Unknown payment processor: " + type);
            // => fail early with useful error rather than returning null
        }
        return factory.get(); // => invoke factory function, return new instance
    }
}
 
// caller uses the factory — decoupled from concrete classes
String processorType = "stripe"; // => in practice: from config or HTTP request param
PaymentProcessor processor = PaymentProcessorFactory.create(processorType);
// => caller never imported StripeProcessor — depends only on PaymentProcessor
 
String txId = processor.process(99.99);
// => Output: Stripe: charged $99.99, tx=stripe_...
// => txId is "stripe_..." (type: String)
 
// adding a new processor: add one entry to REGISTRY + one new class
// => zero changes to checkout flow or any other caller

import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
 
// => PRODUCT: complex, immutable object with many optional fields
// => All fields set via builder — no public setters
final class HttpRequest {
    final String url;           // => required: endpoint URL
    final String method;        // => HTTP method (GET, POST, etc.)
    final Map<String, String> headers; // => request headers
    final String body;          // => optional request body; null if absent
    final double timeoutSeconds; // => request timeout
    final int retries;          // => retry count on transient failure
    final String authToken;     // => optional Bearer token; null if absent
 
    // => private constructor: only HttpRequestBuilder calls this
    private HttpRequest(Builder b) {
        this.url     = b.url;
        this.method  = b.method;
        this.headers = Collections.unmodifiableMap(new HashMap<>(b.headers));
        // => defensive copy + unmodifiable view
        this.body    = b.body;
        this.timeoutSeconds = b.timeoutSeconds;
        this.retries = b.retries;
        this.authToken = b.authToken;
    }
 
    // => BUILDER: inner static class accumulates configuration
    static class Builder {
        private final String url;              // => mandatory at construction time
        private String method = "GET";         // => defaults mirrored from product
        private final Map<String, String> headers = new HashMap<>();
        private String body = null;
        private double timeoutSeconds = 30.0;
        private int retries = 0;
        private String authToken = null;
 
        Builder(String url) {
            this.url = url; // => URL required — fail fast if null
        }
 
        Builder method(String method) {
            this.method = method.toUpperCase(); // => normalize to uppercase
            return this;                        // => return this enables chaining
        }
 
        Builder header(String key, String value) {
            this.headers.put(key, value); // => add individual header
            return this;                  // => fluent interface
        }
 
        Builder jsonBody(String body) {
            this.body = body;
            this.headers.put("Content-Type", "application/json");
            // => auto-set content-type when body is JSON
            return this;
        }
 
        Builder timeout(double seconds) {
            if (seconds <= 0) throw new IllegalArgumentException("Timeout must be positive");
            // => validate immediately; don't wait until execution
            this.timeoutSeconds = seconds;
            return this;
        }
 
        Builder withRetries(int count) {
            this.retries = count; // => retry count for transient failures
            return this;
        }
 
        Builder bearerToken(String token) {
            this.authToken = token;
            this.headers.put("Authorization", "Bearer " + token);
            // => set auth header alongside storing token
            return this;
        }
 
        HttpRequest build() {
            return new HttpRequest(this);
            // => build() is the only place HttpRequest is constructed
        }
    }
}
 
// GOOD: builder reads like a sentence — far clearer than positional args
HttpRequest request = new HttpRequest.Builder("https://api.example.com/users")
    .method("POST")                      // => self-documenting
    .jsonBody("{\"name\":\"Alice\"}")    // => auto-sets Content-Type
    .timeout(10.0)                       // => named step, clear intent
    .withRetries(3)                      // => retry on transient failure
    .bearerToken("tok123")               // => auth token
    .build();                            // => produce immutable HttpRequest
 
System.out.println(request.method);          // => Output: POST
System.out.println(request.headers);         // => Output: {Content-Type=application/json, Authorization=Bearer tok123}
System.out.println(request.timeoutSeconds);  // => Output: 10.0
System.out.println(request.retries);         // => Output: 3

import java.util.Map;
 
// => EXISTING EXTERNAL LIBRARY: third-party analytics SDK with its own interface
// => We cannot change this class — it comes from an external package
class LegacyAnalyticsSDK {
    void trackPageView(String pageName, int userId, String platform) {
        System.out.printf("Legacy: page=%s, user=%d, platform=%s%n", pageName, userId, platform);
        // => legacy SDK uses integer userIds and positional args
    }
 
    void trackEvent(String eventName, String eventData) {
        System.out.printf("Legacy: event=%s, data=%s%n", eventName, eventData);
        // => eventData as raw JSON string — legacy string format
    }
}
 
// => OUR APPLICATION'S ANALYTICS PORT: the interface our code expects
// => Clean, typed interface aligned with our domain language
interface AnalyticsPort {
    void recordPageView(String page, String userId, String userName);
    // => our interface uses String IDs and named parameters
    void recordEvent(String eventName, Map<String, Object> properties);
    // => our interface accepts a typed map, not raw JSON string
}
 
// => ADAPTER: wraps the legacy SDK and exposes our AnalyticsPort interface
// => Adapter is the only place that knows both interfaces
class LegacyAnalyticsAdapter implements AnalyticsPort {
    private final LegacyAnalyticsSDK sdk;
    // => adapter holds reference to the adaptee (legacy SDK instance)
 
    LegacyAnalyticsAdapter(LegacyAnalyticsSDK sdk) {
        this.sdk = sdk;
    }
 
    @Override
    public void recordPageView(String page, String userId, String userName) {
        int numericUserId = Integer.parseInt(userId);
        // => TRANSLATE: our String ID → legacy integer userId
        sdk.trackPageView(page, numericUserId, "web");
        // => DELEGATE: call legacy SDK with translated args
        // => callers never know about the legacy integer ID format
    }
 
    @Override
    public void recordEvent(String eventName, Map<String, Object> properties) {
        String legacyData = properties.toString().replace("=", ":").replace(" ", "");
        // => TRANSLATE: our typed Map → legacy flat string representation
        sdk.trackEvent(eventName, legacyData);
        // => DELEGATE: call legacy SDK with translated format
    }
}
 
// => CLIENT: depends only on AnalyticsPort — zero knowledge of legacy SDK
static void trackCheckout(AnalyticsPort analytics, String userId, double total) {
    analytics.recordPageView("/checkout", userId, "Alice");
    // => calls our clean interface
    analytics.recordEvent("checkout_completed", Map.of("total", total, "currency", "USD"));
    // => calls our clean interface with typed Map
}
 
// wire up: inject adapter into client — adapter bridges the gap
LegacyAnalyticsSDK legacySDK = new LegacyAnalyticsSDK();
// => the incompatible adaptee
LegacyAnalyticsAdapter adapter = new LegacyAnalyticsAdapter(legacySDK);
// => adapter translates between our interface and legacy SDK
 
trackCheckout(adapter, "42", 99.99);
// => Output: Legacy: page=/checkout, user=42, platform=web
// => Output: Legacy: event=checkout_completed, data={total:99.99,currency:USD}
// => client code used clean interface; adapter handled translation silently

import java.util.HashMap;
import java.util.Map;
 
// => COMPONENT INTERFACE: what all decorators and the core implement
// => Decorators and core all share this type — callers see only this
interface UserRepository {
    Map<String, String> findById(String userId);
    // => returns user map (id, name) or null if not found
}
 
// => CONCRETE COMPONENT: the real implementation being decorated
// => This is what decorators ultimately wrap and delegate to
class DatabaseUserRepository implements UserRepository {
    @Override
    public Map<String, String> findById(String userId) {
        // => simulate DB query — real impl queries JDBC/JPA here
        if ("u1".equals(userId)) {
            return Map.of("id", "u1", "name", "Alice"); // => found
        }
        return null; // => not found
    }
}
 
// => DECORATOR BASE: holds a wrapped component, delegates by default
// => Concrete decorators extend this and override to add behavior
abstract class UserRepositoryDecorator implements UserRepository {
    protected final UserRepository wrapped;
    // => the next layer in the chain — may be another decorator or core
 
    UserRepositoryDecorator(UserRepository wrapped) {
        this.wrapped = wrapped;
    }
 
    @Override
    public Map<String, String> findById(String userId) {
        return wrapped.findById(userId);
        // => default: pass through unchanged — subclasses override
    }
}
 
// => DECORATOR 1: adds structured logging around every call
class LoggingDecorator extends UserRepositoryDecorator {
    LoggingDecorator(UserRepository wrapped) { super(wrapped); }
 
    @Override
    public Map<String, String> findById(String userId) {
        System.out.println("[LOG] findById called with userId=" + userId);
        // => log before delegating
        Map<String, String> result = wrapped.findById(userId);
        // => delegate to next layer in chain
        System.out.println("[LOG] findById returned: " + result);
        // => log after delegation completes
        return result; // => return result unchanged
    }
}
 
// => DECORATOR 2: adds in-memory caching (cache-aside pattern)
class CachingDecorator extends UserRepositoryDecorator {
    private final Map<String, Map<String, String>> cache = new HashMap<>();
    // => in-memory cache; TTL/eviction omitted for clarity
 
    CachingDecorator(UserRepository wrapped) { super(wrapped); }
 
    @Override
    public Map<String, String> findById(String userId) {
        if (cache.containsKey(userId)) {
            System.out.println("[CACHE] hit for " + userId);
            return cache.get(userId); // => serve from cache, skip DB call
        }
        Map<String, String> result = wrapped.findById(userId);
        // => cache miss: delegate to next layer
        cache.put(userId, result); // => store in cache for future calls
        return result;
    }
}
 
// => DECORATOR 3: adds retry on exception (simplified for demo)
class RetryDecorator extends UserRepositoryDecorator {
    private final int maxRetries;
    // => configurable retry count; default 3
 
    RetryDecorator(UserRepository wrapped, int maxRetries) {
        super(wrapped);
        this.maxRetries = maxRetries;
    }
 
    @Override
    public Map<String, String> findById(String userId) {
        for (int attempt = 0; attempt < maxRetries; attempt++) {
            try {
                return wrapped.findById(userId); // => try the operation
            } catch (RuntimeException e) {
                if (attempt == maxRetries - 1) throw e;
                // => last attempt: re-throw
                System.out.println("[RETRY] attempt " + (attempt + 1) + " failed: " + e.getMessage());
            }
        }
        return null; // => unreachable — satisfies compiler
    }
}
 
// compose decorators: Logging → Caching → Retry → DB
DatabaseUserRepository dbRepo = new DatabaseUserRepository();
// => innermost: real DB implementation
UserRepository retryRepo   = new RetryDecorator(dbRepo, 3);
// => wrap DB with retry logic
UserRepository cachingRepo = new CachingDecorator(retryRepo);
// => wrap retry with caching
UserRepository loggingRepo = new LoggingDecorator(cachingRepo);
// => outermost: logging wraps entire chain
 
loggingRepo.findById("u1");
// => Output: [LOG] findById called with userId=u1
// => Output: [LOG] findById returned: {id=u1, name=Alice}
 
loggingRepo.findById("u1"); // => second call — cache hit
// => Output: [LOG] findById called with userId=u1
// => Output: [CACHE] hit for u1
// => Output: [LOG] findById returned: {id=u1, name=Alice}
// => DB was NOT called on second request (cache served it)

// => SUBSYSTEM CLASS 1: manages inventory reservations
// => Has its own complex API; callers should not call this directly
class InventoryService {
    boolean reserve(String productId, int qty) {
        System.out.println("Inventory: reserved " + qty + "x " + productId);
        return true; // => simulated: always succeeds for demo
        // => in production: checks stock levels, applies reservations
    }
 
    void release(String productId, int qty) {
        System.out.println("Inventory: released " + qty + "x " + productId);
        // => in production: undoes reservation on order failure
    }
}
 
// => SUBSYSTEM CLASS 2: charges payment and issues refunds
class PaymentGateway {
    String charge(String customerId, double amount) {
        String authCode = "AUTH-" + System.currentTimeMillis();
        // => simulated authorization code; real impl calls payment provider
        System.out.printf("Payment: charged customer %s $%.2f, auth=%s%n", customerId, amount, authCode);
        return authCode; // => authorization code for records
    }
 
    void refund(String authCode) {
        System.out.println("Payment: refunded auth " + authCode);
        // => in production: reverse the charge via payment provider API
    }
}
 
// => SUBSYSTEM CLASS 3: schedules physical delivery
class ShippingService {
    String scheduleDelivery(String orderId, String address) {
        String trackingId = "TRK-" + orderId;
        // => simulated tracking ID; real impl calls courier API
        System.out.printf("Shipping: scheduled delivery for order %s to %s, tracking=%s%n", orderId, address, trackingId);
        return trackingId; // => tracking reference for customer
    }
}
 
// => SUBSYSTEM CLASS 4: sends customer notifications
class NotificationService {
    void sendConfirmation(String email, String orderId, String trackingId) {
        System.out.printf("Notification: sent order confirmation to %s, order=%s, tracking=%s%n", email, orderId, trackingId);
        // => in production: sends transactional email via SendGrid/SES
    }
}
 
// => RESULT: simple return type for facade callers
class OrderResult {
    final boolean success;
    final String trackingId; // => null if success is false
    OrderResult(boolean success, String trackingId) {
        this.success = success;
        this.trackingId = trackingId;
    }
}
 
// => FACADE: single entry point that orchestrates the four subsystem services
// => Callers invoke one method; facade owns the coordination sequence
class OrderFacade {
    private final InventoryService inventory;  // => subsystem dependency
    private final PaymentGateway payment;      // => subsystem dependency
    private final ShippingService shipping;    // => subsystem dependency
    private final NotificationService notification; // => subsystem dependency
 
    OrderFacade(InventoryService inventory, PaymentGateway payment,
                ShippingService shipping, NotificationService notification) {
        this.inventory    = inventory;
        this.payment      = payment;
        this.shipping     = shipping;
        this.notification = notification;
    }
 
    OrderResult placeOrder(String orderId, String customerId, String customerEmail,
                           String productId, int qty, double amount, String shippingAddress) {
        // => step 1: reserve inventory first — fail fast if out of stock
        boolean reserved = inventory.reserve(productId, qty);
        if (!reserved) {
            return new OrderResult(false, null);
            // => early return — no payment charged if inventory unavailable
        }
 
        // => step 2: charge payment
        String authCode = payment.charge(customerId, amount);
        // => authCode stored internally; facade hides this detail from caller
 
        // => step 3: schedule delivery
        String trackingId = shipping.scheduleDelivery(orderId, shippingAddress);
 
        // => step 4: notify customer
        notification.sendConfirmation(customerEmail, orderId, trackingId);
 
        return new OrderResult(true, trackingId);
        // => caller receives simple result; all subsystem coordination hidden
    }
}
 
// CALLER: uses only the facade — never touches subsystem classes directly
OrderFacade facade = new OrderFacade(
    new InventoryService(),
    new PaymentGateway(),
    new ShippingService(),
    new NotificationService()
);
 
OrderResult result = facade.placeOrder(
    "o1", "c1", "alice@example.com", "p1", 2, 49.99, "123 Main St"
);
// => Output: Inventory: reserved 2x p1
// => Output: Payment: charged customer c1 $49.99, auth=AUTH-...
// => Output: Shipping: scheduled delivery for order o1 to 123 Main St, tracking=TRK-o1
// => Output: Notification: sent order confirmation to alice@example.com, order=o1, tracking=TRK-o1
System.out.println("success=" + result.success + ", tracking=" + result.trackingId);
// => Output: success=true, tracking=TRK-o1

import java.util.ArrayDeque;
import java.util.Deque;
import java.util.HashMap;
import java.util.Map;
 
// => RECEIVER: the object that actually performs the work
// => Commands delegate to UserStore; store never knows about commands
class UserStore {
    private final Map<String, String> users = new HashMap<>();
    // => key: userId, value: email
 
    void create(String userId, String email) {
        users.put(userId, email); // => add user to store
        System.out.printf("Created user %s with email %s%n", userId, email);
    }
 
    String delete(String userId) {
        String email = users.remove(userId);
        // => remove and return email for undo support
        if (email != null) System.out.println("Deleted user " + userId);
        return email; // => null if user did not exist
    }
 
    String updateEmail(String userId, String newEmail) {
        if (!users.containsKey(userId)) return null;
        // => user not found
        String oldEmail = users.get(userId); // => save current email for undo
        users.put(userId, newEmail);          // => perform the update
        System.out.printf("Updated %s email to %s%n", userId, newEmail);
        return oldEmail; // => caller uses this to support undo
    }
 
    Map<String, String> all() {
        return Map.copyOf(users); // => immutable snapshot of current state
    }
}
 
// => COMMAND INTERFACE: every command must implement execute and undo
interface Command {
    void execute(); // => perform the action
    void undo();    // => reverse the action exactly
}
 
// => CONCRETE COMMAND 1: create a user — captures all params at construction
class CreateUserCommand implements Command {
    private final UserStore store; // => receiver
    private final String userId;   // => command param captured at construction
    private final String email;    // => not passed at execute() time
 
    CreateUserCommand(UserStore store, String userId, String email) {
        this.store  = store;
        this.userId = userId;
        this.email  = email;
    }
 
    @Override
    public void execute() {
        store.create(userId, email); // => delegate to receiver
    }
 
    @Override
    public void undo() {
        store.delete(userId);        // => reverse: remove the created user
        System.out.println("Undo: removed user " + userId);
    }
}
 
// => CONCRETE COMMAND 2: update user email with undo support
class UpdateEmailCommand implements Command {
    private final UserStore store;
    private final String userId;
    private final String newEmail;
    private String oldEmail; // => captured during execute() for undo
 
    UpdateEmailCommand(UserStore store, String userId, String newEmail) {
        this.store    = store;
        this.userId   = userId;
        this.newEmail = newEmail;
    }
 
    @Override
    public void execute() {
        oldEmail = store.updateEmail(userId, newEmail);
        // => save old email so undo can restore it exactly
    }
 
    @Override
    public void undo() {
        if (oldEmail != null) {
            store.updateEmail(userId, oldEmail);
            // => restore previous email
            System.out.println("Undo: restored email to " + oldEmail);
        }
    }
}
 
// => INVOKER: queues commands and maintains undo history
class CommandQueue {
    private final Deque<Command> history = new ArrayDeque<>();
    // => stack of executed commands; pop() gives most recent
 
    void execute(Command command) {
        command.execute();    // => execute the command on the receiver
        history.push(command); // => push onto history stack for potential undo
    }
 
    void undoLast() {
        if (!history.isEmpty()) {
            Command command = history.pop(); // => take most recent command
            command.undo();                  // => reverse it
        }
    }
}
 
UserStore store = new UserStore();
CommandQueue queue = new CommandQueue();
 
queue.execute(new CreateUserCommand(store, "u1", "alice@example.com"));
// => Output: Created user u1 with email alice@example.com
queue.execute(new UpdateEmailCommand(store, "u1", "newalice@example.com"));
// => Output: Updated u1 email to newalice@example.com
System.out.println(store.all()); // => Output: {u1=newalice@example.com}
 
queue.undoLast(); // => undo UpdateEmail command
// => Output: Updated u1 email to alice@example.com
// => Output: Undo: restored email to alice@example.com
System.out.println(store.all()); // => Output: {u1=alice@example.com}

import java.util.List;
 
// => MEDIATOR INTERFACE: defines how components talk to the mediator
// => Components call notify() instead of calling each other directly
interface Mediator {
    void notify(Component sender, String event, Object data);
    // => sender identifies which component fired; event names what happened
}
 
// => BASE COMPONENT: holds a reference to its mediator, uses it to emit events
// => Components never import each other — they only import Mediator
class Component {
    protected final String name; // => component identifier for logging
    protected Mediator mediator; // => set by mediator after construction
 
    Component(String name) {
        this.name = name;
    }
 
    void setMediator(Mediator mediator) {
        this.mediator = mediator; // => wired by the mediator at creation time
    }
 
    void emit(String event, Object data) {
        if (mediator != null) {
            mediator.notify(this, event, data);
            // => send event to mediator; mediator decides who else hears it
        }
    }
}
 
// => CONCRETE COMPONENTS: they emit events; never reference each other
class SearchBox extends Component {
    SearchBox() { super("search_box"); }
 
    void search(String query) {
        System.out.println("SearchBox: searching for '" + query + "'");
        emit("search_submitted", query);
        // => notifies mediator; does NOT call ResultsList directly
    }
}
 
class ResultsList extends Component {
    ResultsList() { super("results"); }
 
    void display(List<String> results) {
        System.out.println("ResultsList: displaying " + results.size() + " results: " + results);
        emit("results_displayed", results);
        // => notifies mediator; does NOT call StatusBar directly
    }
}
 
class StatusBar extends Component {
    StatusBar() { super("status"); }
 
    void update(String message) {
        System.out.println("StatusBar: " + message);
        // => StatusBar is a leaf — no events emitted
    }
}
 
class LoadingSpinner extends Component {
    LoadingSpinner() { super("spinner"); }
 
    void show() {
        System.out.println("Spinner: showing");
        emit("spinner_shown", null);
    }
 
    void hide() {
        System.out.println("Spinner: hidden");
        // => hide emits no event in this example
    }
}
 
// => CONCRETE MEDIATOR: knows all components and orchestrates their interactions
// => All coordination logic lives here — components stay simple
class SearchPageMediator implements Mediator {
    final SearchBox searchBox = new SearchBox();    // => create and own all components
    final ResultsList results  = new ResultsList();
    final StatusBar status     = new StatusBar();
    final LoadingSpinner spinner = new LoadingSpinner();
 
    SearchPageMediator() {
        // => wire self as mediator into every component
        for (Component c : List.of(searchBox, results, status, spinner)) {
            c.setMediator(this);
        }
        // => after wiring, all components know only this mediator
    }
 
    @Override
    public void notify(Component sender, String event, Object data) {
        // => ALL coordination logic is centralized here in the mediator
        if ("search_submitted".equals(event)) {
            spinner.show();                             // => start loading indicator
            status.update("Searching for '" + data + "'..."); // => update status text
            List<String> fakeResults = List.of(
                "Result for " + data + " #0",
                "Result for " + data + " #1",
                "Result for " + data + " #2"
            );
            // => simulate search results; real impl calls search service
            results.display(fakeResults);              // => populate results list
            spinner.hide();                            // => stop loading indicator
            status.update("Found " + fakeResults.size() + " results for '" + data + "'");
            // => update status with result count
        }
    }
}
 
// demo: triggering one component cascades through the mediator
SearchPageMediator mediator = new SearchPageMediator();
// => all components created and wired inside constructor
mediator.searchBox.search("architecture patterns");
// => Output: SearchBox: searching for 'architecture patterns'
// => Output: Spinner: showing
// => Output: StatusBar: Searching for 'architecture patterns'...
// => Output: ResultsList: displaying 3 results: [Result for architecture patterns #0, ...]
// => Output: Spinner: hidden
// => Output: StatusBar: Found 3 results for 'architecture patterns'
// => SearchBox never called ResultsList or Spinner directly

// => STATE INTERFACE: defines behavior for every possible order state
interface OrderState {
    void pay();          // => attempt to pay
    void ship();         // => attempt to ship
    void cancel();       // => attempt to cancel
    String getStatus();  // => current status name
}
 
// => CONTEXT: the Order that delegates all behavior to its current state
class OrderContext {
    private OrderState state; // => current state — changes over lifecycle
 
    OrderContext() {
        this.state = new PendingState(this); // => always starts as Pending
        System.out.println("Order created in state: " + state.getStatus());
    }
 
    // => state transition: called by state objects, never by external callers
    void transitionTo(OrderState next) {
        System.out.println("  State: " + state.getStatus() + " -> " + next.getStatus());
        this.state = next; // => replace current state with new state object
    }
 
    // => delegate all behavior to the current state object
    void pay()    { state.pay(); }    // => behavior differs per state
    void ship()   { state.ship(); }   // => behavior differs per state
    void cancel() { state.cancel(); } // => behavior differs per state
    String status() { return state.getStatus(); }
}
 
// => CONCRETE STATE: Pending — awaiting payment
class PendingState implements OrderState {
    private final OrderContext order; // => back-reference to trigger transitions
    PendingState(OrderContext order) { this.order = order; }
 
    @Override public void pay() {
        System.out.println("Payment received");
        order.transitionTo(new PaidState(order));
        // => valid transition: Pending -> Paid
    }
 
    @Override public void ship() {
        System.out.println("Cannot ship: order not paid yet");
        // => invalid in this state — no transition occurs
    }
 
    @Override public void cancel() {
        System.out.println("Order cancelled before payment");
        order.transitionTo(new CancelledState(order));
        // => valid transition: Pending -> Cancelled
    }
 
    @Override public String getStatus() { return "PENDING"; }
}
 
// => CONCRETE STATE: Paid — payment received, awaiting shipment
class PaidState implements OrderState {
    private final OrderContext order;
    PaidState(OrderContext order) { this.order = order; }
 
    @Override public void pay() {
        System.out.println("Already paid");
        // => invalid: cannot pay twice — no transition
    }
 
    @Override public void ship() {
        System.out.println("Order shipped");
        order.transitionTo(new ShippedState(order));
        // => valid transition: Paid -> Shipped
    }
 
    @Override public void cancel() {
        System.out.println("Order cancelled, refund issued");
        order.transitionTo(new CancelledState(order));
        // => valid: refund required when cancelling after payment
    }
 
    @Override public String getStatus() { return "PAID"; }
}
 
// => CONCRETE STATE: Shipped — in transit, no backwards transitions
class ShippedState implements OrderState {
    private final OrderContext order;
    ShippedState(OrderContext order) { this.order = order; }
 
    @Override public void pay()    { System.out.println("Already paid"); }
    @Override public void ship()   { System.out.println("Already shipped"); }
    @Override public void cancel() { System.out.println("Cannot cancel: already shipped"); }
    // => all operations are no-ops or informational — shipped is near-terminal
 
    @Override public String getStatus() { return "SHIPPED"; }
}
 
// => CONCRETE STATE: Cancelled — terminal state, all operations rejected
class CancelledState implements OrderState {
    private final OrderContext order;
    CancelledState(OrderContext order) { this.order = order; }
 
    @Override public void pay()    { System.out.println("Cannot pay: order cancelled"); }
    @Override public void ship()   { System.out.println("Cannot ship: order cancelled"); }
    @Override public void cancel() { System.out.println("Already cancelled"); }
    // => no transitions from terminal state
 
    @Override public String getStatus() { return "CANCELLED"; }
}
 
// demo: valid order lifecycle
OrderContext order = new OrderContext();    // => Output: Order created in state: PENDING
order.ship();   // => Output: Cannot ship: order not paid yet
order.pay();    // => Output: Payment received
                // => Output:   State: PENDING -> PAID
order.ship();   // => Output: Order shipped
                // => Output:   State: PAID -> SHIPPED
order.cancel(); // => Output: Cannot cancel: already shipped
System.out.println(order.status()); // => Output: SHIPPED

import java.util.*;
 
// => ABSTRACT CLASS: defines the algorithm skeleton via a template method
// => Template method calls abstract hooks in a fixed sequence
abstract class DataExporter {
 
    // => TEMPLATE METHOD: invariant algorithm — validate -> transform -> serialize -> checksum
    // => Final prevents subclasses from reordering or skipping steps
    final String export(List<Map<String, Object>> data) {
        List<Map<String, Object>> validated   = validate(data);   // => step 1: filter invalid rows
        List<Map<String, Object>> transformed = transform(validated); // => step 2: shape the data
        String serialized = serialize(transformed);               // => step 3: produce string output
        String checksum   = computeChecksum(serialized);          // => step 4: invariant, not overridable
        return serialized + "\nChecksum:" + checksum;             // => step 5: invariant wrapper
    }
 
    // => ABSTRACT HOOKS: subclasses must fill in these steps
    protected abstract List<Map<String, Object>> validate(List<Map<String, Object>> data);
    protected abstract List<Map<String, Object>> transform(List<Map<String, Object>> data);
    protected abstract String serialize(List<Map<String, Object>> data);
 
    // => CONCRETE STEP: checksum is always the same — subclasses cannot override
    private String computeChecksum(String content) {
        return Integer.toHexString(content.hashCode()).substring(0, 8);
        // => simplified hash for demo; use SHA-256 in production
    }
}
 
// => CONCRETE SUBCLASS 1: CSV exporter
class CsvExporter extends DataExporter {
    @Override
    protected List<Map<String, Object>> validate(List<Map<String, Object>> data) {
        List<Map<String, Object>> result = new ArrayList<>();
        for (Map<String, Object> row : data) {
            if (!row.isEmpty()) result.add(row); // => filter empty rows
        }
        return result;
    }
 
    @Override
    protected List<Map<String, Object>> transform(List<Map<String, Object>> data) {
        List<Map<String, Object>> result = new ArrayList<>();
        for (Map<String, Object> row : data) {
            Map<String, Object> stringRow = new LinkedHashMap<>();
            for (Map.Entry<String, Object> e : row.entrySet()) {
                stringRow.put(e.getKey(), String.valueOf(e.getValue()));
                // => convert all values to strings for CSV compatibility
            }
            result.add(stringRow);
        }
        return result;
    }
 
    @Override
    protected String serialize(List<Map<String, Object>> data) {
        if (data.isEmpty()) return "";
        List<String> lines = new ArrayList<>();
        lines.add(String.join(",", data.get(0).keySet())); // => header row
        for (Map<String, Object> row : data) {
            lines.add(String.join(",", row.values().stream()
                .map(Object::toString).toArray(String[]::new)));
            // => data row: join all values with comma
        }
        return String.join("\n", lines); // => all lines joined
    }
}
 
// => CONCRETE SUBCLASS 2: JSON exporter
class JsonExporter extends DataExporter {
    @Override
    protected List<Map<String, Object>> validate(List<Map<String, Object>> data) {
        return new ArrayList<>(data); // => JSON handles any map structure natively
    }
 
    @Override
    protected List<Map<String, Object>> transform(List<Map<String, Object>> data) {
        return data; // => JSON handles types natively, no transformation needed
    }
 
    @Override
    protected String serialize(List<Map<String, Object>> data) {
        StringBuilder sb = new StringBuilder("[");
        for (int i = 0; i < data.size(); i++) {
            sb.append("{");
            data.get(i).forEach((k, v) -> sb.append("\"").append(k).append("\":\"").append(v).append("\","));
            if (sb.charAt(sb.length() - 1) == ',') sb.setLength(sb.length() - 1);
            sb.append("}");
            if (i < data.size() - 1) sb.append(","); // => separator between objects
        }
        return sb.append("]").toString(); // => close JSON array
    }
}
 
// demo: same export() call, different output format
List<Map<String, Object>> sampleData = List.of(
    new LinkedHashMap<>(Map.of("name", "Alice", "age", 30)),
    new LinkedHashMap<>(Map.of("name", "Bob",   "age", 25))
);
 
CsvExporter csv = new CsvExporter();
System.out.println("=== CSV ===");
System.out.println(csv.export(sampleData));
// => Output: name,age\nAlice,30\nBob,25\nChecksum:xxxxxxxx
 
JsonExporter json = new JsonExporter();
System.out.println("=== JSON ===");
System.out.println(json.export(sampleData));
// => Output: [{"name":"Alice","age":"30"},{"name":"Bob","age":"25"}]\nChecksum:yyyyyyyy
// => Both use identical validate->transform->serialize->checksum sequence
// => Only the format-specific steps differ between subclasses

import java.util.Objects;
 
// => VALUE OBJECT: Money — defined by amount + currency together
// => No setters: once constructed, values never change (immutable)
final class Money {
    private final double amount;   // => monetary amount
    private final String currency; // => ISO 4217 currency code, normalized to uppercase
 
    Money(double amount, String currency) {
        // => validation at construction — invalid Money cannot exist
        if (amount < 0)
            throw new IllegalArgumentException("Money amount cannot be negative: " + amount);
        if (currency == null || currency.length() != 3)
            throw new IllegalArgumentException("Currency must be a 3-letter ISO code: " + currency);
        this.amount   = amount;
        this.currency = currency.toUpperCase(); // => normalize to uppercase at construction
    }
 
    Money add(Money other) {
        if (!this.currency.equals(other.currency))
            throw new IllegalArgumentException("Cannot add " + currency + " and " + other.currency);
        return new Money(this.amount + other.amount, this.currency);
        // => returns NEW Money — does not mutate self (immutable value semantics)
    }
 
    Money multiply(double factor) {
        return new Money(Math.round(this.amount * factor * 100.0) / 100.0, this.currency);
        // => rounds to 2 decimal places (cents precision)
    }
 
    // => EQUALITY BY VALUE: two Money objects with same amount+currency are equal
    @Override public boolean equals(Object o) {
        if (!(o instanceof Money)) return false;
        Money m = (Money) o;
        return Double.compare(amount, m.amount) == 0 && currency.equals(m.currency);
        // => reference identity irrelevant — only values matter
    }
 
    @Override public int hashCode() { return Objects.hash(amount, currency); }
 
    @Override public String toString() {
        return String.format("%s %.2f", currency, amount); // => "USD 10.00"
    }
 
    double getAmount()   { return amount; }
    String getCurrency() { return currency; }
}
 
// => VALUE OBJECT: Email — self-validating, immutable
final class Email {
    private final String address; // => always lowercase after construction
 
    Email(String raw) {
        // => validation at construction — invalid Email cannot exist
        if (raw == null || !raw.contains("@") || !raw.contains("."))
            throw new IllegalArgumentException("Invalid email address: " + raw);
        this.address = raw.toLowerCase(); // => normalize to lowercase
    }
 
    String domain() {
        return address.split("@")[1]; // => extract domain part
    }
 
    @Override public boolean equals(Object o) {
        return o instanceof Email && address.equals(((Email) o).address);
        // => equality by normalized address value
    }
 
    @Override public int hashCode() { return address.hashCode(); }
    @Override public String toString() { return address; }
}
 
// demo: value object equality and immutability
Money price1 = new Money(10.0, "USD"); // => USD 10.00
Money price2 = new Money(10.0, "USD"); // => USD 10.00 — same attributes
Money price3 = new Money(20.0, "USD"); // => USD 20.00 — different amount
 
System.out.println(price1.equals(price2)); // => Output: true  (same values = equal)
System.out.println(price1.equals(price3)); // => Output: false (different amount)
System.out.println(price1 == price2);      // => Output: false (different object references)
// => reference identity differs; equality is determined by values, not identity
 
Money total = price1.add(price3);
System.out.println(total); // => Output: USD 30.00
 
try {
    new Money(-5.0, "USD"); // => attempt negative amount
} catch (IllegalArgumentException e) {
    System.out.println(e.getMessage()); // => Output: Money amount cannot be negative: -5.0
}
 
Email email1 = new Email("Alice@Example.COM"); // => mixed case input
Email email2 = new Email("alice@example.com"); // => lowercase input
System.out.println(email1.equals(email2)); // => Output: true (both normalized to lowercase)
System.out.println(email1.domain());       // => Output: example.com

import java.util.*;
 
// => VALUE OBJECT: line item inside the aggregate
// => Immutable snapshot — values fixed at creation time
final class LineItem {
    final String productId;   // => identifies the product
    final String productName; // => snapshot name at order time (not live)
    final double unitPrice;   // => snapshot price at order time (not live)
    final int    quantity;    // => how many units
 
    LineItem(String productId, String productName, double unitPrice, int quantity) {
        this.productId   = productId;
        this.productName = productName;
        this.unitPrice   = unitPrice;
        this.quantity    = quantity;
    }
 
    double subtotal() { return unitPrice * quantity; } // => line total
}
 
// => AGGREGATE ROOT: Order — the consistency boundary
// => All modifications to order contents MUST go through Order methods
class Order {
    final String id;          // => aggregate identity
    final String customerId;  // => relationship by ID, not by object reference
    private String status = "DRAFT";
    // => status only changes through root methods
    private final List<LineItem> items = new ArrayList<>();
    // => internal — external code accesses via items() accessor only
 
    private static final double MAX_ORDER_VALUE = 10_000.0;
    // => BUSINESS INVARIANT enforced by the aggregate root
 
    Order(String id, String customerId) {
        this.id         = id;
        this.customerId = customerId;
    }
 
    void addItem(String productId, String name, double price, int qty) {
        // => GUARD: can only add items to DRAFT orders
        if (!"DRAFT".equals(status))
            throw new IllegalStateException("Cannot add items to order in status " + status);
 
        LineItem item = new LineItem(productId, name, price, qty);
        // => INVARIANT CHECK: compute candidate total before committing
        double candidateTotal = items.stream().mapToDouble(LineItem::subtotal).sum() + item.subtotal();
        if (candidateTotal > MAX_ORDER_VALUE)
            throw new IllegalStateException("Order total would exceed maximum $" + MAX_ORDER_VALUE);
 
        items.add(item); // => commit: invariant satisfied
    }
 
    void removeItem(String productId) {
        if (!"DRAFT".equals(status))
            throw new IllegalStateException("Cannot remove items from non-draft order");
        boolean removed = items.removeIf(i -> i.productId.equals(productId));
        // => removeIf returns true if any element was removed
        if (!removed)
            throw new NoSuchElementException("Product " + productId + " not in order");
    }
 
    void confirm() {
        // => INVARIANT: cannot confirm an empty order
        if (items.isEmpty())
            throw new IllegalStateException("Cannot confirm empty order");
        status = "CONFIRMED"; // => state transition through root — never set directly
    }
 
    double total() {
        return items.stream().mapToDouble(LineItem::subtotal).sum();
        // => aggregate total computed from child line items
    }
 
    List<LineItem> items() {
        return Collections.unmodifiableList(items);
        // => return unmodifiable view — external code cannot mutate the internal list
    }
 
    String status() { return status; }
}
 
// demo: all modifications go through the aggregate root
Order order = new Order("o1", "c1"); // => starts as DRAFT
 
order.addItem("p1", "Widget", 50.0, 2); // => subtotal $100
order.addItem("p2", "Gadget", 30.0, 1); // => subtotal $30
System.out.println("Total: $" + order.total()); // => Output: Total: $130.0
 
try {
    order.addItem("p3", "BigItem", 9_900.0, 1); // => would exceed $10,000
} catch (IllegalStateException e) {
    System.out.println(e.getMessage()); // => Output: Order total would exceed maximum $10000.0
}
 
order.confirm();                         // => transition: DRAFT -> CONFIRMED
System.out.println(order.status());      // => Output: CONFIRMED
 
try {
    order.addItem("p4", "Extra", 10.0, 1); // => cannot add to CONFIRMED
} catch (IllegalStateException e) {
    System.out.println(e.getMessage()); // => Output: Cannot add items to order in status CONFIRMED
}