Sealed Classes in Java 17 — Complete Guide with Real-World Examples

// FILE: ShapeHierarchy.java
// Demonstrates the three legal modifiers a permitted subtype must carry.

// The sealed parent — permits exactly three direct subtypes.
public sealed class Shape permits Circle, Rectangle, WeirdPolygon {

    // A common property all shapes share.
    public abstract double area();

    // ----- Permitted subtype 1: FINAL — closes the branch completely -----
    public static final class Circle extends Shape {
        private final double radius;

        public Circle(double radius) {
            this.radius = radius;
        }

        @Override
        public double area() {
            // πr² — classic formula, no surprises here.
            return Math.PI * radius * radius;
        }

        @Override
        public String toString() {
            return "Circle(radius=" + radius + ")";
        }
    }

    // ----- Permitted subtype 2: SEALED — adds another closed layer -----
    // Rectangle is itself sealed, permitting only Square.
    public static sealed class Rectangle extends Shape permits Rectangle.Square {
        protected final double width;
        protected final double height;

        public Rectangle(double width, double height) {
            this.width = width;
            this.height = height;
        }

        @Override
        public double area() {
            return width * height;
        }

        @Override
        public String toString() {
            return "Rectangle(" + width + "x" + height + ")";
        }

        // Square is a permitted subtype of Rectangle — the chain continues.
        public static final class Square extends Rectangle {
            public Square(double side) {
                // A square IS a rectangle where width == height.
                super(side, side);
            }

            @Override
            public String toString() {
                return "Square(side=" + width + ")";
            }
        }
    }

    // ----- Permitted subtype 3: NON-SEALED — deliberately reopens the hierarchy -----
    // Anyone in any package can now extend WeirdPolygon freely.
    // Use this escape hatch consciously — it weakens exhaustiveness guarantees.
    public static non-sealed class WeirdPolygon extends Shape {
        private final int sides;

        public WeirdPolygon(int sides) {
            this.sides = sides;
        }

        @Override
        public double area() {
            // Placeholder — real implementation would need more geometry.
            return 0.0;
        }

        @Override
        public String toString() {
            return "WeirdPolygon(sides=" + sides + ")";
        }
    }

    // ----- Demo main — run this to see the hierarchy in action -----
    public static void main(String[] args) {
        // Build a mixed list of shapes.
        Shape[] shapes = {
            new Circle(5.0),
            new Rectangle(4.0, 6.0),
            new Rectangle.Square(3.0),
            new WeirdPolygon(7)
        };

        for (Shape shape : shapes) {
            // Java 21 pattern matching in switch — but the compiler knows
            // Shape only has three direct subtypes, so it can verify coverage.
            String description = switch (shape) {
                case Circle c    -> "Circle with area " + String.format("%.2f", c.area());
                case Rectangle r -> "Rectangle with area " + String.format("%.2f", r.area());
                // WeirdPolygon is non-sealed, so we still need a default
                // (or a WeirdPolygon case) to satisfy the compiler.
                default          -> "Unknown shape: " + shape;
            };
            System.out.println(description);
        }
    }
}

// FILE: PaymentResult.java
// Models a payment processing outcome as a sealed interface + records.
// This is the ADT pattern — a fixed set of variants, each with its own data.

public class PaymentResult {

    // The sealed interface acts as the 'type header'.
    // No permits clause needed — all variants are in this file.
    public sealed interface ProcessingResult
            permits ProcessingResult.Success,
                    ProcessingResult.Declined,
                    ProcessingResult.ProcessingError {

        // A convenience method every variant can implement — or we pattern-match outside.
        boolean isTerminal();

        // ----- Variant 1: Payment went through -----
        // Records are implicitly final, so they satisfy the sealed constraint automatically.
        record Success(
                String transactionId,   // e.g. "TXN-8821-ABCD"
                double amountCharged,   // the actual amount billed
                String currency         // ISO 4217 code: "USD", "EUR", etc.
        ) implements ProcessingResult {

            // Compact canonical constructor — validate on construction.
            public Success {
                if (amountCharged <= 0) {
                    throw new IllegalArgumentException(
                        "Charged amount must be positive, got: " + amountCharged);
                }
                if (transactionId == null || transactionId.isBlank()) {
                    throw new IllegalArgumentException("Transaction ID must not be blank");
                }
            }

            @Override
            public boolean isTerminal() {
                // A successful charge is always a terminal state.
                return true;
            }
        }

        // ----- Variant 2: Card declined by issuer -----
        record Declined(
                String declineCode,     // issuer code, e.g. "INSUFFICIENT_FUNDS"
                boolean retryable       // should the caller attempt again later?
        ) implements ProcessingResult {

            @Override
            public boolean isTerminal() {
                // Non-retryable declines are terminal; retryable ones are not.
                return !retryable;
            }
        }

        // ----- Variant 3: Internal processing failure -----
        record ProcessingError(
                String errorMessage,
                Throwable cause         // the underlying exception, for logging
        ) implements ProcessingResult {

            @Override
            public boolean isTerminal() {
                // Errors are always terminal — don't silently retry on errors.
                return true;
            }
        }
    }

    // Simulates a payment gateway response based on card number suffix.
    public static ProcessingResult charge(String cardNumberSuffix, double amount) {
        return switch (cardNumberSuffix) {
            case "4242" -> new ProcessingResult.Success("TXN-" + System.nanoTime(), amount, "USD");
            case "0002" -> new ProcessingResult.Declined("INSUFFICIENT_FUNDS", true);
            case "9999" -> new ProcessingResult.Declined("STOLEN_CARD", false);
            default     -> new ProcessingResult.ProcessingError(
                                "Gateway timeout",
                                new RuntimeException("Connection refused"));
        };
    }

    public static void main(String[] args) {
        String[] testCards = {"4242", "0002", "9999", "1234"};

        for (String card : testCards) {
            ProcessingResult result = charge(card, 99.95);

            // Pattern matching switch — NO default needed because all permitted
            // types are records (implicitly final). The compiler verifies exhaustiveness.
            String summary = switch (result) {
                case ProcessingResult.Success s ->
                    String.format("✅ Charged $%.2f — TXN: %s", s.amountCharged(), s.transactionId());

                case ProcessingResult.Declined d ->
                    String.format("❌ Declined (%s) — Retryable: %s", d.declineCode(), d.retryable());

                case ProcessingResult.ProcessingError e ->
                    String.format("💥 Error: %s", e.errorMessage());
                // No default needed! The compiler KNOWS these three are all there are.
            };

            System.out.printf("Card ...%s → %s (terminal=%s)%n",
                    card, summary, result.isTerminal());
        }
    }
}

// FILE: SealedReflectionInspector.java
// Shows how to read sealed metadata at runtime via the Reflection API.
// Useful for building framework integrations or diagnostic tooling.

import java.lang.constant.ClassDesc;
import java.util.Arrays;
import java.util.List;

public class SealedReflectionInspector {

    // A minimal sealed hierarchy to inspect.
    sealed interface Notification
            permits Notification.EmailNotification,
                    Notification.SmsNotification,
                    Notification.PushNotification {
        String recipient();
    }

    record EmailNotification(String recipient, String subject)
            implements Notification {}

    record SmsNotification(String recipient, String messageBody)
            implements Notification {}

    record PushNotification(String recipient, String deviceToken, String payload)
            implements Notification {}

    public static void main(String[] args) {
        Class<Notification> notificationClass = Notification.class;

        // ----- 1. Check if the type is sealed -----
        System.out.println("Is Notification sealed? " + notificationClass.isSealed());
        System.out.println("Is String sealed?        " + String.class.isSealed());
        System.out.println();

        // ----- 2. Retrieve permitted subtypes -----
        // Returns ClassDesc[] — lightweight descriptors that don't trigger class loading.
        ClassDesc[] permitted = notificationClass.permittedSubclasses();

        System.out.println("Permitted subtypes of Notification:");
        for (ClassDesc descriptor : permitted) {
            // descriptor.displayName() gives a human-readable class name.
            System.out.println("  → " + descriptor.displayName());
        }
        System.out.println();

        // ----- 3. Use reflection to build a dispatcher — no hardcoded instanceof -----
        // This simulates what a serialization framework might do at startup.
        List<Notification> events = List.of(
            new EmailNotification("alice@example.com", "Your order shipped"),
            new SmsNotification("+1-555-0100", "OTP: 847291"),
            new PushNotification("bob@example.com", "device-token-xyz", "{\"alert\":\"New message\"}")
        );

        System.out.println("Dispatching " + events.size() + " notifications:");
        for (Notification event : events) {
            // getClass().getSimpleName() here — in a real framework you'd
            // use the ClassDesc array to build a lookup map at initialization.
            System.out.printf("  [%s] → recipient: %s%n",
                    event.getClass().getSimpleName(),
                    event.recipient());
        }
        System.out.println();

        // ----- 4. Show that the JVM enforces sealing at load time -----
        // Demonstrating isSealed() on a record subtype.
        System.out.println("Is EmailNotification sealed? " +
                EmailNotification.class.isSealed());
        System.out.println("Is EmailNotification final? " +
                java.lang.reflect.Modifier.isFinal(
                        EmailNotification.class.getModifiers()));
        // Records are implicitly final, so isSealed() is false and isFinal() is true.
    }
}

// FILE: ShippingCalculator.java
// Demonstrates exhaustive pattern matching switch over a sealed hierarchy,
// including guarded patterns and null safety.

public class ShippingCalculator {

    // Sealed interface modelling a shipping method — four variants, all final.
    public sealed interface ShippingMethod
            permits ShippingMethod.StandardGround,
                    ShippingMethod.ExpressAir,
                    ShippingMethod.OvernightPriority,
                    ShippingMethod.DigitalDelivery {

        // A contract all variants must satisfy.
        boolean requiresPhysicalAddress();

        record StandardGround(int estimatedDays) implements ShippingMethod {
            @Override public boolean requiresPhysicalAddress() { return true; }
        }

        record ExpressAir(int estimatedDays, boolean insured) implements ShippingMethod {
            @Override public boolean requiresPhysicalAddress() { return true; }
        }

        record OvernightPriority(String cutoffTime) implements ShippingMethod {
            @Override public boolean requiresPhysicalAddress() { return true; }
        }

        // Digital delivery — no physical address needed.
        record DigitalDelivery(String downloadUrl) implements ShippingMethod {
            @Override public boolean requiresPhysicalAddress() { return false; }
        }
    }

    /**
     * Calculates shipping cost for a package.
     *
     * @param method     the chosen shipping method (must not be null — see null guard below)
     * @param weightKg   package weight in kilograms
     * @return           calculated shipping cost in USD
     */
    public static double calculateCost(ShippingMethod method, double weightKg) {
        // Explicit null case — without this, a null method throws NullPointerException
        // BEFORE reaching any type pattern. This is the most common sealed-switch gotcha.
        return switch (method) {
            case null ->
                throw new IllegalArgumentException("Shipping method must not be null");

            // Guarded pattern: StandardGround is cheap only if weight is under 5kg.
            case ShippingMethod.StandardGround sg when weightKg <= 5.0 ->
                5.99 + (weightKg * 0.50);

            // Same type, different guard — handles heavier packages.
            case ShippingMethod.StandardGround sg ->
                5.99 + (weightKg * 0.80); // penalty rate for heavy ground shipments

            // Destructure the record's components directly in the case.
            case ShippingMethod.ExpressAir(int days, boolean insured) ea
                    when insured ->
                // Insurance adds a flat 15% surcharge.
                (12.99 + (weightKg * 1.50)) * 1.15;

            case ShippingMethod.ExpressAir ea ->
                12.99 + (weightKg * 1.50);

            case ShippingMethod.OvernightPriority op ->
                // Overnight is a flat rate regardless of weight.
                39.99;

            case ShippingMethod.DigitalDelivery dd ->
                // Digital goods ship free — no weight cost.
                0.00;

            // NO default needed — the compiler verified all 4 permitted types are covered.
            // If we add a 5th variant to the sealed interface, THIS switch will fail to compile
            // until we add a matching case. That's the safety guarantee.
        };
    }

    public static void main(String[] args) {
        var orders = new Object[][] {
            { new ShippingMethod.StandardGround(5),            3.0  },
            { new ShippingMethod.StandardGround(5),            8.0  },
            { new ShippingMethod.ExpressAir(2, true),          2.5  },
            { new ShippingMethod.ExpressAir(2, false),         2.5  },
            { new ShippingMethod.OvernightPriority("5:00 PM"), 1.0  },
            { new ShippingMethod.DigitalDelivery("https://dl.example.com/v2.zip"), 0.0 }
        };

        System.out.printf("%-40s %8s%n", "Shipping Method", "Cost");
        System.out.println("-".repeat(50));

        for (Object[] order : orders) {
            ShippingMethod method = (ShippingMethod) order[0];
            double weight = (double) order[1];
            double cost = calculateCost(method, weight);

            System.out.printf("%-40s $%7.2f%n",
                    method.getClass().getSimpleName() + " (" + weight + "kg)", cost);
        }

        // Show null guard in action.
        try {
            calculateCost(null, 1.0);
        } catch (IllegalArgumentException e) {
            System.out.println("\nNull guard caught: " + e.getMessage());
        }
    }
}