This is Part 6 (final) of "Java 17 Features Every Senior Developer Should Know" - a comprehensive reference covering syntax, usage patterns, feature interactions, and migration strategies for all 6 features covered in Parts 1-5. Perfect for printing and keeping at your desk as you work with modern Java code.

How to Use This Series

First time learning Java 17 features?

• Read Part 1: var Keyword → Part 2: Records → Part 3: Sealed Classes → Part 4: Pattern Matching → Part 5: Text Blocks

• Each part includes practical examples and best practices

• Estimated reading time: 1-2 hours total

Need a quick reference?

• Use the Quick Reference Cards below (this page)

• Each section provides syntax, examples, and use cases at a glance

• Links to full parts for detailed explanations

Looking for specific feature?

• Use the Table of Contents below to jump to any feature

• Each Quick Reference Card links back to its full part

Want to understand feature interactions?

• See full articles for detailed explanations and real-world patterns

Planning a migration?

• See full articles for phased migration strategy and compatibility notes

Series Overview & Timeline

This series covers 6 major Java features spanning Java 10-17, representing over 20 years of language evolution:

Why These Features Matter:

• Part 1-2: Reduce boilerplate (less code to write)

• Part 3-4: Increase safety (compiler catches more errors)

• Part 5-6: Improve readability (code matches intent)

Feature Comparison Matrix

Decision At-a-Glance

Feature Dependencies

var (Java 10)
    ↓ (enables clean declaration of)
Records (Java 16)
    ↓ (work well with)
Sealed Classes (Java 17)
    ↓ (enables exhaustive checking with)
Pattern Matching (Java 16)
    ↓ (used in)
Switch Expressions (Java 14)
    ↓ (format data with)
Text Blocks (Java 15)

Quick Reference Cards

var Keyword (Java 10)

JEP 286 | Local variable type inference

📖 See also: Part 1: Introduction & var Keyword - Full feature deep dive with examples and pitfalls

Syntax

var name = expression;

✅ Use When

• Type is obvious from right side: var user = new User()

• Long generic types: var map = new HashMap<String, List<Employee>>()

• Stream chains: var filtered = list.stream().filter(...)

• For-loops: for (var item : items)

❌ Don't Use When

• Type isn't clear: var data = fetchData() (what type?)

• Need supertype: List<String> list = new ArrayList<>() (flexibility)

• Fields, parameters, return types (not allowed)

• Lambda/method reference alone: var c = String::length (error)

Examples

// ✅ Good
var message = "Hello";
var count = 42;
var users = List.of("Alice", "Bob");
var map = new HashMap<String, Integer>();

// ❌ Bad
var x = getData();           // unclear type
var y = null;                // error: cannot infer
var list = new ArrayList<>(); // error: need type args

Quick Rules

• Compile-time type inference (NOT dynamic typing)

• Local variables only

• Must have initializer

• Type never changes

Records (Java 16)

JEP 395 | Immutable data carriers

📖 See also: Part 2: Records - Full feature deep dive with examples and best practices

Syntax

record Name(Type1 field1, Type2 field2) {
    // optional: custom methods, validation
}

✅ Use When

• Data Transfer Objects (DTOs)

• Value objects (Point, Money, Range)

• Configuration objects

• API request/response models

• Return values from methods (multiple values)

❌ Don't Use When

• Need mutability

• Need inheritance (records are final)

• Want to hide internal structure

• Need JavaBeans getters (use field() not getField())

• Complex lazy initialization

Examples

// Basic record
record Point(int x, int y) {}

// With validation (compact constructor)
record Range(int start, int end) {
    public Range {
        if (start > end) throw new IllegalArgumentException();
    }
}

// With custom methods
record Person(String name, int age) {
    public boolean isAdult() { return age >= 18; }
    public Person withAge(int newAge) { return new Person(name, newAge); }
}

// Generic record
record Pair<T, U>(T first, U second) {}

// Implementing interface
record Circle(double radius) implements Shape {
    @Override
    public double area() { return Math.PI * radius * radius; }
}

What You Get Automatically

• Constructor: public Point(int x, int y)

• Accessors: p.x(), p.y() (NOT getX(), getY())

• equals(), hashCode(), toString()

• Fields are private final

• Class is final

Quick Rules

• Immutable by default

• All fields final

• Cannot extend other classes

• Can implement interfaces

• Defensive copying needed for mutable components

Sealed Classes (Java 17)

JEP 409 | Controlled inheritance

📖 See also: Part 3: Sealed Classes - Design patterns and hierarchy control explained

Syntax

sealed interface/class Name permits SubType1, SubType2 {
}

// Subtypes must be: final, sealed, or non-sealed

✅ Use When

• Closed type hierarchies (known subtypes only)

• Domain modeling with fixed alternatives

• Exhaustive pattern matching

• API design where you control all implementations

❌ Don't Use When

• Open for extension (third-party implementations)

• Plugin architectures

• Need unlimited subclassing

Examples

// Sealed interface with records
sealed interface Shape permits Circle, Rectangle, Triangle {}

record Circle(double radius) implements Shape {}
record Rectangle(double width, double height) implements Shape {}
record Triangle(double base, double height) implements Shape {}

// Sealed class hierarchy
sealed class Result<T> permits Success, Failure {}

final class Success<T> extends Result<T> {
    private final T value;
    // ...
}

final class Failure<T> extends Result<T> {
    private final String error;
    // ...
}

// With non-sealed for extension point
sealed interface Payment permits CreditCard, DebitCard, ExtensiblePayment {}
final class CreditCard implements Payment {}
final class DebitCard implements Payment {}
non-sealed interface ExtensiblePayment extends Payment {} // Open for extension

Permitted Subtypes Must

• Be in same module (or same package if unnamed module)

• Directly extend/implement the sealed type

• Be declared as: final, sealed, or non-sealed

Quick Rules

• Compiler knows all subtypes

• Enables exhaustive pattern matching

• Subtypes must be declared in permits clause

• Better than marker interfaces for closed sets

Pattern Matching (Java 16)

JEP 394 | Pattern matching for instanceof

📖 See also: Part 4: Pattern Matching & Switch Expressions - Type patterns and exhaustiveness checking

Syntax

if (obj instanceof Type variableName) {
    // use variableName here
}

✅ Use When

• Type checking with immediate use

• Implementing equals() methods

• Polymorphic dispatch

• Guard conditions: obj instanceof String s && s.length() > 5

❌ Don't Use When

• Polymorphism would be better (add methods to types)

• Type checking indicates design smell

• Performance is absolutely critical

Examples

// Basic pattern matching
if (obj instanceof String s) {
    System.out.println(s.toUpperCase());
}

// With guards
if (obj instanceof String s && s.length() > 0) {
    return s.toUpperCase();
}

// Simplified equals()
@Override
public boolean equals(Object obj) {
    return obj instanceof Point p && this.x == p.x && this.y == p.y;
}

// Type hierarchy
if (shape instanceof Circle c) {
    return Math.PI * c.radius() * c.radius();
} else if (shape instanceof Rectangle r) {
    return r.width() * r.height();
}

Scope Rules

if (obj instanceof String s && s.length() > 5) {
    // 's' in scope here
}

if (!(obj instanceof String s)) {
    // 's' NOT in scope
} else {
    // 's' IS in scope here
}

Quick Rules

• Pattern variable scoped by flow analysis

• instanceof returns false for null (safe)

• No manual cast needed

• Combines type check + cast + assignment

Switch Expressions (Java 14)

JEP 361 | Switch as expression with arrow syntax

📖 See also: Part 4: Pattern Matching & Switch Expressions - Clean conditional logic with yield

Syntax

// Arrow syntax (no fall-through)
var result = switch (value) {
    case LABEL1 -> expression1;
    case LABEL2, LABEL3 -> expression2;
    default -> expressionN;
};

// Multi-statement with yield
var result = switch (value) {
    case LABEL1 -> {
        // statements
        yield value1;
    }
};

✅ Use When

• Mapping enum values

• Returning values from branches

• Exhaustive enum matching (no default needed)

• Multi-way conditional logic

❌ Don't Use When

• Simple if-else would suffice

• Need fall-through (use colon syntax)

• Cases are complex and unrelated

Examples

// Basic switch expression
String dayType = switch (day) {
    case MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY -> "Weekday";
    case SATURDAY, SUNDAY -> "Weekend";
};

// With yield
int result = switch (op) {
    case ADD -> {
        System.out.println("Adding");
        yield a + b;
    }
    case SUBTRACT -> {
        System.out.println("Subtracting");
        yield a - b;
    }
    default -> throw new IllegalArgumentException();
};

// Exhaustive enum (no default needed)
int days = switch (season) {
    case SPRING, SUMMER, FALL, WINTER -> 3;
};

Quick Rules

• Arrow -> prevents fall-through

• Must be exhaustive (all cases or default)

• Use yield for multi-statement branches

• No break needed with arrows

• Can mix with pattern matching (future Java)

Text Blocks (Java 15)

JEP 378 | Multi-line string literals

📖 See also: Part 5: Text Blocks - Multi-line strings with security considerations

Syntax

String text = """
    content here
    more content
    """;

✅ Use When

• Multi-line strings (JSON, SQL, HTML, XML)

• Embedded code snippets

• Long error messages

• Test fixtures

❌ Don't Use When

• Single-line strings

• Dynamically built strings

• Need platform-specific line endings

Examples

// JSON
String json = """
    {
      "name": "Alice",
      "age": 30,
      "email": "alice@example.com"
    }""";

// SQL
String sql = """
    SELECT u.name, u.email, o.total
    FROM users u
    JOIN orders o ON u.id = o.user_id
    WHERE o.status = 'COMPLETED'
    ORDER BY o.created_at DESC""";

// With formatted()
String json = """
    {
      "name": "%s",
      "age": %d
    }""".formatted(name, age);

// Indentation control
String text = """
    Line 1
        Indented line 2
    Line 3
    """;  // Closing delimiter determines indent stripping

// Line continuation
String long = """
    This is a long line that \
    continues on the next line \
    in source code.
    """;

// Essential space
String trailing = """
    Line with space:\s
    """;

Special Escapes

• \s - Essential space (survives whitespace stripping)

• \ - Line continuation (no newline inserted)

• Standard escapes work: \n, \t, \", \\

Quick Rules

• Opening """ must be followed by newline

• Closing """ position determines indent

• All line endings normalized to \n

• Trailing whitespace auto-removed

• Common indent automatically stripped

End of Series

This concludes "Java 17 Features Every Senior Developer Should Know"

• Part 1: var Keyword

• Part 2: Records

• Part 3: Sealed Classes

• Part 4: Pattern Matching & Switch Expressions

• Part 5: Text Blocks

• Part 6: Syntax Cheat Sheet (this document)

Series Navigation

• ← Part 5: Text Blocks - Multi-line string literals

• ← Series Overview - Overview and series guide

Traditionally, embedding multi-line strings required extensive use of escape sequences and concatenation operators. Each newline needed an explicit \n, quotes required escaping with \", and each line demanded a + operator. This approach made code difficult to read and maintain, particularly for structured data formats.

Text blocks provide a cleaner solution. You can directly embed multi-line strings with proper formatting preserved. The compiler automatically handles line termination normalization, indentation stripping, and whitespace management. When combined with formatted(), text blocks offer a practical lightweight alternative for generating emails, invoices, configurations, and other templated content.

The Problem: Multi-line Strings Before Java 15

Before Java 15, creating multi-line string literals required verbose and error-prone approaches. Consider these common scenarios:

JSON embedded in tests:

String json = "{\n" +
              "  \"name\": \"Alice\",\n" +
              "  \"age\": 30,\n" +
              "  \"email\": \"alice@example.com\"\n" +
              "}";

SQL queries as strings:

String query = "SELECT u.name, u.email, o.total\n" +
               "FROM users u\n" +
               "JOIN orders o ON u.id = o.user_id\n" +
               "WHERE o.status = 'COMPLETED'\n" +
               "ORDER BY o.created_at DESC";

HTML templates in code:

String html = "<html>\n" +
              "  <head>\n" +
              "    <title>Welcome</title>\n" +
              "  </head>\n" +
              "  <body>\n" +
              "    <h1>Hello, World!</h1>\n" +
              "  </body>\n" +
              "</html>";

Common issues with this approach:

• Every line requires a + concatenation operator

• Newlines must be explicitly written as \n

• All quotes require escaping with \"

• Easy to introduce bugs: missing +, forgotten quotes, misplaced escapes

• Source code indentation doesn't match the actual data structure

• Copy-pasting content from external tools (Postman, database clients, design tools) requires extensive reformatting

• Structure and readability of JSON, SQL, or HTML is obscured by Java syntax noise

• Maintenance burden: any update to the content requires modifying multiple lines

What Are Text Blocks?

A text block is a multi-line string literal that avoids most escape sequences. It was introduced in Java 15 (JEP 378) after two preview versions in Java 13 and 14.

Text blocks use triple-double-quote delimiters (""") and automatically:

• Normalize line terminators to \n

• Strip common leading whitespace (indentation)

• Remove incidental trailing whitespace

• Preserve essential formatting

Before and After

// Before: Traditional string
String json = "{\n" +
              "  \"name\": \"Alice\",\n" +
              "  \"age\": 30\n" +
              "}";

// After: Text block
String json = """
    {
      "name": "Alice",
      "age": 30
    }
    """;

The text block version is:

• ✅ More readable

• ✅ No escape sequences needed

• ✅ Natural indentation

• ✅ Easier to maintain

Syntax and Basic Usage

Delimiter Rules

Text blocks are delimited by three double-quote marks ("""):

String textBlock = """
    Line 1
    Line 2
    Line 3
    """;

Important rules:

1. Opening """ must be followed by a line terminator (newline)

2. Content starts on the line after the opening delimiter

3. Closing """ can be on its own line or after content

// ✅ Valid: Opening delimiter on separate line
String valid1 = """
    Hello, World!
    """;

// ✅ Valid: Closing delimiter on same line as content
String valid2 = """
    Hello, World!""";

// ❌ Invalid: Content on same line as opening delimiter
String invalid = """Hello, World!
    """;

Line Terminator Normalization

All line terminators (Windows \r\n, Unix \n, Mac \r) are normalized to \n:

String block = """
    Line 1
    Line 2
    """;

// Equivalent to:
String traditional = "Line 1\nLine 2\n";

Indentation Rules

Text blocks have sophisticated indentation handling through automatic indent stripping. This is the most complex but powerful feature.

Rule 1: Common Indent Stripping

The compiler finds the minimum indentation across all non-blank lines and removes it:

String example = """
        Hello
        World
        """;

// Actual content: "Hello\nWorld\n"
// The 8 leading spaces were stripped because
// all lines shared that minimum indentation

Rule 2: Closing Delimiter Position Matters

The position of the closing """ determines the indent level:

// Closing delimiter aligned left - no stripping
String left = """
Hello
World
""";
// Content: "Hello\nWorld\n"

// Closing delimiter indented - strips that amount
String indented = """
    Hello
    World
    """;
// Content: "Hello\nWorld\n" (4 spaces stripped from each line)

Rule 3: Essential Whitespace with \s

Use \s to preserve spaces that would otherwise be stripped:

String preserved = """
    Hello\s\s\sWorld
    """;
// Content: "Hello   World\n" (3 spaces preserved)

Rule 4: Trailing Whitespace Removal

Spaces at the end of lines are automatically removed (unless escaped with \s):

String trailing = """
    Hello
    World
    """;
// Content: "Hello\nWorld\n" (trailing spaces removed)

Escape Sequences

Text blocks support standard Java escape sequences plus two new ones.

Standard Escapes

All traditional escapes still work:

String escapes = """
    Newline: \n
    Tab: \t
    Backslash: \\
    Quote: \"
    """;

New Escape 1: Essential Space (\s)

Marks a space that survives trailing whitespace removal:

String essential = """
    End with space:\s
    """;
// Content: "End with space: \n" (space preserved)

New Escape 2: Line Continuation (\)

Ends a line without adding \n:

String continued = """
    This is a very long sentence that we want to \
    break across multiple lines in source code \
    but appear as one line in the string.
    """;
// Content: "This is a very long sentence that we want to break across multiple lines in source code but appear as one line in the string.\n"

Escaping Triple Quotes

To include """ in a text block, escape at least one quote:

String quotes = """
    He said: \"""Hello!\"""
    """;
// Content: "He said: \"\"\"Hello!\"\"\"\n"

Practical Examples

Let's explore text blocks through eight comprehensive examples, including critical security considerations for SQL queries.

Example 1: Basic Text Blocks

Text blocks eliminate concatenation and escape sequences for multi-line text.

public class BasicTextBlocksExample {

    public static String getMultilineText() {
        return """
            Line 1
            Line 2
            Line 3
            """;
    }

    public static String getPoem() {
        return """
            Roses are "red",
            Violets are "blue",
            Java 15 is awesome,
            And so are you!""";
    }

    public static String getIndentedBlock() {
        return """
                This line has 4 spaces of indent
                    This line has 8 spaces
                Back to 4 spaces
                """;
    }

    public static void main(String[] args) {
        System.out.println("=== Multi-line Text ===");
        System.out.println(getMultilineText());

        System.out.println("=== Poem with Quotes ===");
        System.out.println(getPoem());

        System.out.println("=== Indented Block ===");
        System.out.println(getIndentedBlock());
    }
}

Output:

=== Multi-line Text ===
Line 1
Line 2
Line 3

=== Poem with Quotes ===
Roses are "red",
Violets are "blue",
Java 15 is awesome,
And so are you!

=== Indented Block ===
This line has 4 spaces of indent
    This line has 8 spaces
Back to 4 spaces

Key Insight: Text blocks eliminate the need for \n and \" escape sequences, making multi-line strings dramatically more readable while producing identical runtime results.

Example 2: JSON with Text Blocks

Text blocks are perfect for embedded JSON - no more escape sequence hell.

public class JSONTextBlocksExample {

    public static String getUserJSON() {
        return """
            {
              "name": "Alice Smith",
              "age": 30,
              "email": "alice@example.com"
            }""";
    }

    public static String getUserJSONFormatted(String name, int age, String email) {
        return """
            {
              "name": "%s",
              "age": %d,
              "email": "%s"
            }""".formatted(name, age, email);
    }

    public static void main(String[] args) {
        System.out.println("=== User JSON ===");
        System.out.println(getUserJSON());

        System.out.println("\n=== Formatted User JSON ===");
        System.out.println(getUserJSONFormatted("Charlie", 25, "charlie@example.com"));
    }
}

Output:

=== User JSON ===
{
  "name": "Alice Smith",
  "age": 30,
  "email": "alice@example.com"
}

=== Formatted User JSON ===
{
  "name": "Charlie",
  "age": 25,
  "email": "charlie@example.com"
}

Key Insight: Text blocks combined with formatted() provide a clean alternative to JSON libraries for simple cases, making test fixtures and configuration templates dramatically more maintainable.

Example 3: SQL with Text Blocks

Text blocks excel at SQL queries, preserving structure and formatting without concatenation hell.

public class SQLTextBlocksExample {

    public static String getActiveOrdersQuery() {
        return """
            SELECT u.id, u.name, o.order_id, o.total
            FROM users u
            JOIN orders o ON u.id = o.user_id
            WHERE o.status = 'COMPLETED'
            ORDER BY o.created_at DESC""";
    }

    // EDUCATIONAL EXAMPLE: Shows how formatted() works with SQL
    // ⚠️ WARNING: This approach is UNSAFE for production code!
    // See "SQL Queries with Text Blocks - Security First" section for secure approach
    public static String getOrdersByStatusQuery(String status, double minAmount) {
        return """
            SELECT * FROM orders
            WHERE status = '%s'
              AND total > %s
            ORDER BY created_at DESC""".formatted(status, minAmount);
    }

    public static void main(String[] args) {
        System.out.println("=== Active Orders ===" );
        System.out.println(getActiveOrdersQuery());

        System.out.println("\n=== Orders by Status ===");
        System.out.println(getOrdersByStatusQuery("COMPLETED", 100.0));
    }
}

Output:

=== Active Orders ===
SELECT u.id, u.name, o.order_id, o.total
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE o.status = 'COMPLETED'
ORDER BY o.created_at DESC

=== Orders by Status ===
SELECT * FROM orders
WHERE status = 'COMPLETED'
  AND total > 100.0
ORDER BY created_at DESC

Key Insight: Text blocks make SQL queries readable and maintainable by preserving their natural structure, but beware of SQL injection when using formatted() with user input—always use PreparedStatement for production code.

Example 4: HTML and SVG with Text Blocks

Text blocks simplify working with HTML and XML-like markup languages by eliminating quote escaping and concatenation noise.

public class HTMLTextBlocksExample {

    public static String getDashboardHTML() {
        return """
            <html>
              <head>
                <title>User Dashboard</title>
              </head>
              <body>
                <h1>Welcome, User!</h1>
                <p>This is your dashboard.</p>
              </body>
            </html>""";
    }

    public static String getSVGCircle() {
        return """
            <svg width="100" height="100">
              <circle cx="50" cy="50" r="40" fill="blue" />
              <text x="50" y="55" text-anchor="middle" fill="white">SVG</text>
            </svg>""";
    }

    public static void main(String[] args) {
        System.out.println("=== Dashboard HTML ===");
        System.out.println(getDashboardHTML());

        System.out.println("\n=== SVG Circle ===");
        System.out.println(getSVGCircle());
    }
}

Output:

=== Dashboard HTML ===
<html>
  <head>
    <title>User Dashboard</title>
  </head>
  <body>
    <h1>Welcome, User!</h1>
    <p>This is your dashboard.</p>
  </body>
</html>

=== SVG Circle ===
<svg width="100" height="100">
  <circle cx="50" cy="50" r="40" fill="blue" />
  <text x="50" y="55" text-anchor="middle" fill="white">SVG</text>
</svg>

Key Insight: Text blocks eliminate the impedance mismatch between HTML/XML structure in design tools and Java code, making templates maintainable without escaping gymnastics.

Example 5: Indentation Rules and Edge Cases

Text blocks handle indentation intelligently, stripping common leading whitespace while preserving relative indentation for formatting.

public class IndentationExample {

    // Common indent stripping - closing delimiter determines indent level
    public static String getStripExample() {
        return """
            Line 1
            Line 2
            Line 3
            """;
    }

    // Closing delimiter aligned left - minimal stripping
    public static String getLeftAlignedClosing() {
        return """
    Indented line 1
    Indented line 2
""";
    }

    // Essential whitespace with \s
    public static String getEssentialSpace() {
        return """
            Line with trailing space:\s
            Another line
            """;
    }

    // Relative indentation preserved
    public static String getRelativeIndent() {
        return """
            Level 1
                Level 2
                    Level 3
                Level 2
            Level 1
            """;
    }

    // Empty lines handling
    public static String getEmptyLines() {
        return """
            First paragraph.

            Second paragraph after blank line.

            Third paragraph.
            """;
    }

    // Line continuation with backslash
    public static String getLineContinuation() {
        return """
            This is a very long line that we want to \
            split in source code but keep as \
            one line in the string.
            """;
    }

    // Mixed example with all features
    public static String getMixedExample() {
        return """
            Regular line
                Indented line
            Line with essential space:\s
            Split across \
            multiple source lines
            """;
    }

    public static void main(String[] args) {
        System.out.println("=== Strip Example ===");
        System.out.println("[" + getStripExample() + "]");

        System.out.println("\n=== Left Aligned Closing ===");
        System.out.println("[" + getLeftAlignedClosing() + "]");

        System.out.println("\n=== Essential Space ===");
        System.out.println("[" + getEssentialSpace() + "]");

        System.out.println("\n=== Line Continuation ===");
        System.out.println("[" + getLineContinuation() + "]");

        System.out.println("\n=== Relative Indent ===");
        System.out.println(getRelativeIndent());

        System.out.println("\n=== Empty Lines ===");
        System.out.println(getEmptyLines());

        System.out.println("\n=== Mixed Example ===");
        System.out.println("[" + getMixedExample() + "]");
    }
}

Output:

=== Strip Example ===
[Line 1
Line 2
Line 3
]

=== Left Aligned Closing ===
[Indented line 1
Indented line 2
]

=== Essential Space ===
[Line with trailing space:
Another line
]

=== Line Continuation ===
[This is a very long line that we want to split in source code but keep as one line in the string.
]

=== Relative Indent ===
Level 1
    Level 2
        Level 3
    Level 2
Level 1

=== Empty Lines ===
First paragraph.

Second paragraph after blank line.

Third paragraph.

=== Mixed Example ===
[Regular line
    Indented line
Line with essential space:
Split across multiple source lines
]

Key Insight: Text block indentation rules are designed to balance source code readability with content integrity—the closing delimiter position determines stripping level, preserving intentional formatting.

Example 6: Escape Sequences and Special Cases

Text blocks support all standard Java escape sequences plus two new ones for advanced use cases: \s for essential spaces and \ for line continuation without newlines.

public class EscapeSequencesExample {

    // Standard escapes - all traditional escapes work in text blocks
    public static String getStandardEscapes() {
        return """
            Newline escape: \\n works here
            Tab escape: \\t indents like this
            Backslash: \\\\ is a single backslash
            Quote: \\" doesn't need escaping in text blocks
            """;
    }

    // Essential space (\s) - preserves trailing whitespace
    public static String getEssentialSpace() {
        return """
            Line ending with essential space:\\s
            Line without space
            Another line with space:\\s
            """;
    }

    // Line continuation (\) - joins lines without newline
    public static String getLineContinuation() {
        return """
            This is a long sentence that spans \
            multiple lines in source code but \
            appears as a single line in the string.""";
    }

    // Escaping triple quotes
    public static String getTripleQuoteEscape() {
        return """
            He said: \\"\\"\\"Hello!\\"\\"\\"
            And I replied: \\"\\"\\"Hi there!\\"\\"\\"
            """;
    }

    // Practical: SQL with special characters
    public static String getSQLWithSpecialChars() {
        return """
            SELECT * FROM table
            WHERE name = 'John\\'s Data'
            AND description LIKE '%\\\\%'
            """;
    }

    // Unicode and emoji handling - text blocks preserve all Unicode characters
    public static String getUnicodeExample() {
        return """
            Polish characters: ąćęłńóśźż ĄĆĘŁŃÓŚŹŻ
            Czech characters: čřšžď ČŘŠŽĎ
            Greek letters: α β γ δ ε ζ η θ
            Math symbols: ∑ ∫ √ ∞ ≈ ≠ ≥ ≤
            Currency: € £ ¥ ₿ ₹ ₽
            Emoji: 🚀 ✅ ❌ 🎯 🔥 💡 ⚠️ 🔒
            Arrows: → ← ↑ ↓ ⇒ ⇐ ⇑ ⇓
            """;
    }

    public static void main(String[] args) {
        System.out.println("=== Standard Escapes ===");
        System.out.println(getStandardEscapes());

        System.out.println("\n=== Essential Space ===");
        System.out.println("[" + getEssentialSpace() + "]");

        System.out.println("\n=== Line Continuation ===");
        System.out.println("[" + getLineContinuation() + "]");

        System.out.println("\n=== Triple Quote Escape ===");
        System.out.println(getTripleQuoteEscape());

        System.out.println("\n=== SQL with Special Chars ===");
        System.out.println(getSQLWithSpecialChars());

        System.out.println("\n=== Unicode and Emoji ===");
        System.out.println(getUnicodeExample());
    }
}

Output:

=== Standard Escapes ===
Newline escape: \n works here
Tab escape: \t indents like this
Backslash: \ is a single backslash
Quote: " doesn't need escaping in text blocks

=== Essential Space ===
[Line ending with essential space:
Line without space
Another line with space:
]

=== Line Continuation ===
[This is a long sentence that spans multiple lines in source code but appears as a single line in the string.
]

=== Triple Quote Escape ===
He said: """Hello!"""
And I replied: """Hi there!"""

=== SQL with Special Chars ===
SELECT * FROM table
WHERE name = 'John\'s Data'
AND description LIKE '%\%'

=== Unicode and Emoji ===
Polish characters: ąćęłńóśźż ĄĆĘŁŃÓŚŹŻ
Czech characters: čřšžď ČŘŠŽĎ
Greek letters: α β γ δ ε ζ η θ
Math symbols: ∑ ∫ √ ∞ ≈ ≠ ≥ ≤
Currency: € £ ¥ ₿ ₹ ₽
Emoji: 🚀 ✅ ❌ 🎯 🔥 💡 ⚠️ 🔒
Arrows: → ← ↑ ↓ ⇒ ⇐ ⇑ ⇓

Key Insight: Text blocks support both standard escape sequences (for compatibility) and new special escapes (\s, \) that provide fine-grained control over whitespace and line handling—enabling both readability and precision.

Example 7: Safe Templates - Emails, Invoices, and Configuration

Text blocks combined with formatted() create a powerful lightweight template system without external libraries—ideal for emails, invoices, configuration files, and API responses. These use cases are safe because they don't involve SQL queries.

public class SimpleTemplateSystemExample {

    // Email template with variable interpolation
    public static String renderEmailTemplate(String recipientName, String activationUrl, String expirationHours) {
        return """
            <html>
              <body style="font-family: Arial, sans-serif;">
                <h2>Welcome, %s!</h2>
                <p>Thank you for signing up. Please activate your account within %s hours.</p>
                <p><a href="%s" style="background-color: #007bff; color: white; padding: 10px 20px; text-decoration: none; border-radius: 5px;">Activate Account</a></p>
                <p>If you didn't sign up, please ignore this email.</p>
                <p>Best regards,<br>The Team</p>
              </body>
            </html>""".formatted(recipientName, expirationHours, activationUrl);
    }

    // Invoice template with multiple variables
    public static String renderInvoiceTemplate(String invoiceNumber, String customerName, String amount, String dueDate) {
        return """
            ╔════════════════════════════════════════╗
            ║           INVOICE                      ║
            ╚════════════════════════════════════════╝

            Invoice #: %s
            Customer:  %s

            Amount Due: $%s
            Due Date:   %s

            ────────────────────────────────────────
            Thank you for your business!
            """.formatted(invoiceNumber, customerName, amount, dueDate);
    }

    // API response template
    public static String renderAPIResponseTemplate(String status, String requestId, String message) {
        return """
            {
              "status": "%s",
              "requestId": "%s",
              "message": "%s",
              "timestamp": "%s"
            }""".formatted(status, requestId, message, java.time.Instant.now().toString());
    }

    // Config file template
    public static String renderConfigTemplate(String appName, String environment, String port) {
        return """
            # Configuration for %s
            # Environment: %s

            app.name=%s
            app.environment=%s
            server.port=%s
            logging.level=INFO
            """.formatted(appName, environment, appName, environment, port);
    }

    public static void main(String[] args) {
        System.out.println("=== Email Template ===");
        System.out.println(renderEmailTemplate("John Smith", "https://app.example.com/activate?token=xyz123", "24"));

        System.out.println("\n=== Invoice Template ===");
        System.out.println(renderInvoiceTemplate("INV-2024-001", "Acme Corp", "1,500.00", "2024-12-31"));

        System.out.println("\n=== API Response Template ===");
        System.out.println(renderAPIResponseTemplate("success", "req-12345", "User created successfully"));

        System.out.println("\n=== Config Template ===");
        System.out.println(renderConfigTemplate("MyApp", "production", "8080"));
    }
}

Output:

=== Email Template ===
<html>
  <body style="font-family: Arial, sans-serif;">
    <h2>Welcome, John Smith!</h2>
    <p>Thank you for signing up. Please activate your account within 24 hours.</p>
    <p><a href="https://app.example.com/activate?token=xyz123" style="background-color: #007bff; color: white; padding: 10px 20px; text-decoration: none; border-radius: 5px;">Activate Account</a></p>
    <p>If you didn't sign up, please ignore this email.</p>
    <p>Best regards,<br>The Team</p>
  </body>
</html>

=== Invoice Template ===
╔════════════════════════════════════════╗
║           INVOICE                      ║
╚════════════════════════════════════════╝

Invoice #: INV-2024-001
Customer:  Acme Corp

Amount Due: $1,500.00
Due Date:   2024-12-31

────────────────────────────────────────
Thank you for your business!

=== API Response Template ===
{
  "status": "success",
  "requestId": "req-12345",
  "message": "User created successfully",
  "timestamp": "2024-11-17T..."
}

=== Config Template ===
# Configuration for MyApp
# Environment: production

app.name=MyApp
app.environment=production
server.port=8080
logging.level=INFO

Key Insight: Text blocks combined with formatted() eliminate the need for template engines in simple scenarios—turning Java into a practical choice for generating emails, configurations, and structured text documents with clean, readable code.

Example 8: Secure SQL with PreparedStatement

Text blocks work perfectly with PreparedStatement for secure, readable SQL queries. This is the SAFE way to combine text blocks with SQL—using parameterized queries instead of string formatting.

public class SecureSQLExample {

    // Safe SQL: Text block with PreparedStatement placeholders (?)
    // Text blocks improve readability while PreparedStatement prevents SQL injection
    public static String getOrdersByStatusQuerySafe() {
        return """
            SELECT o.order_id, o.total, u.name, u.email
            FROM orders o
            JOIN users u ON o.user_id = u.id
            WHERE o.status = ?
              AND o.total >= ?
            ORDER BY o.created_at DESC
            LIMIT ?""";
    }

    // Complex CTE query demonstrating text block power with security
    // Common Table Expressions (CTEs) are highly readable with text blocks
    public static String getTopCustomersQuerySafe() {
        return """
            WITH customer_totals AS (
                SELECT u.id, u.name, u.email,
                       SUM(o.total) as total_spent,
                       COUNT(o.order_id) as order_count
                FROM users u
                JOIN orders o ON u.id = o.user_id
                WHERE o.status = ?
                  AND o.created_at >= ?
                GROUP BY u.id, u.name, u.email
            )
            SELECT id, name, email, total_spent, order_count
            FROM customer_totals
            WHERE total_spent >= ?
            ORDER BY total_spent DESC
            LIMIT ?""";
    }

    // Example execution method showing PreparedStatement usage
    // In production, this would execute against a real database
    public static List<String> executeOrderQuery(Connection conn, String status, double minAmount, int limit)
            throws SQLException {
        List<String> results = new ArrayList<>();
        String query = getOrdersByStatusQuerySafe();

        // PreparedStatement automatically escapes parameters - SAFE from SQL injection
        try (PreparedStatement ps = conn.prepareStatement(query)) {
            ps.setString(1, status);      // Parameter 1: status
            ps.setDouble(2, minAmount);   // Parameter 2: minAmount
            ps.setInt(3, limit);          // Parameter 3: limit

            try (ResultSet rs = ps.executeQuery()) {
                while (rs.next()) {
                    results.add(String.format("Order %s: $%.2f - %s (%s)",
                        rs.getString("order_id"),
                        rs.getDouble("total"),
                        rs.getString("name"),
                        rs.getString("email")));
                }
            }
        }
        return results;
    }

    public static void main(String[] args) {
        System.out.println("=== Safe SQL with PreparedStatement ===");
        System.out.println(getOrdersByStatusQuerySafe());

        System.out.println("\n=== Complex CTE Query ===");
        System.out.println(getTopCustomersQuerySafe());

        System.out.println("\n=== Key Points ===");
        System.out.println("1. Use ? placeholders instead of %s formatting");
        System.out.println("2. PreparedStatement.setString/setDouble/setInt for parameters");
        System.out.println("3. Text blocks still improve readability");
        System.out.println("4. Completely safe from SQL injection attacks");
    }
}

Output:

=== Safe SQL with PreparedStatement ===
SELECT o.order_id, o.total, u.name, u.email
FROM orders o
JOIN users u ON o.user_id = u.id
WHERE o.status = ?
  AND o.total >= ?
ORDER BY o.created_at DESC
LIMIT ?

=== Complex CTE Query ===
WITH customer_totals AS (
    SELECT u.id, u.name, u.email,
           SUM(o.total) as total_spent,
           COUNT(o.order_id) as order_count
    FROM users u
    JOIN orders o ON u.id = o.user_id
    WHERE o.status = ?
      AND o.created_at >= ?
    GROUP BY u.id, u.name, u.email
)
SELECT id, name, email, total_spent, order_count
FROM customer_totals
WHERE total_spent >= ?
ORDER BY total_spent DESC
LIMIT ?

=== Key Points ===
1. Use ? placeholders instead of %s formatting
2. PreparedStatement.setString/setDouble/setInt for parameters
3. Text blocks still improve readability
4. Completely safe from SQL injection attacks

Key Insight: Text blocks and PreparedStatement are the perfect combination—text blocks provide readability for complex SQL while PreparedStatement ensures security through parameterized queries.

Template Systems with Variable Interpolation

Text blocks combined with formatted() create lightweight template systems without external dependencies. Example 7 demonstrates practical use cases:

Common Use Cases for formatted() with Text Blocks:

1. Email Templates - Dynamic email content with user data

2. Invoice/Receipt Generation - Formatted business documents

3. Configuration Files - Properties and values with variables

4. API Response Templates - JSON/XML data structures

5. Log Messages - Contextual information with parameters

For security considerations when using formatted() with SQL or HTML, see the Security Considerations section in Best Practices.

Best Practices

Security Considerations

Text blocks with formatted() introduce critical security risks when used improperly with SQL queries or HTML content. Understanding these risks is essential for production code.

SQL Injection Risks

CRITICAL: Using formatted() with SQL queries creates SQL injection vulnerabilities—one of the most dangerous security mistakes in application development.

The Danger

When you embed user input directly into SQL strings using formatted(), attackers can manipulate the query:

// ❌ DANGEROUS - DO NOT USE IN PRODUCTION
String status = userInput;  // User enters: "COMPLETED' OR '1'='1"
String sql = """
    SELECT * FROM orders
    WHERE status = '%s'
    """.formatted(status);
// Resulting SQL: SELECT * FROM orders WHERE status = 'COMPLETED' OR '1'='1'
// This returns ALL orders, bypassing the status filter!

More severe attacks can delete data, access sensitive information, or compromise your entire database:

// ❌ If user enters: "'; DROP TABLE orders; --"
String sql = """
    SELECT * FROM orders WHERE status = '%s'
    """.formatted(maliciousInput);
// Resulting SQL executes: SELECT * FROM orders WHERE status = ''; DROP TABLE orders; --'
// Your entire orders table is DELETED!

The Safe SQL Pattern

Always use PreparedStatement for SQL with dynamic values:

// ✅ SAFE - Use PreparedStatement with text blocks
String query = """
    SELECT * FROM orders
    WHERE status = ?
      AND total >= ?
    """;

try (PreparedStatement ps = connection.prepareStatement(query)) {
    ps.setString(1, userInput);  // Automatically escaped - safe!
    ps.setDouble(2, minAmount);
    try (ResultSet rs = ps.executeQuery()) {
        // Process results
    }
}

Key Points:

• Text blocks improve SQL readability

• PreparedStatement prevents SQL injection

• Use ? placeholders, NOT %s formatting

• Set parameters via setString(), setInt(), setDouble(), etc.

See Example 8 (SecureSQLExample) for complete, production-ready code demonstrating safe SQL with text blocks and PreparedStatement.

When Text Blocks ARE Safe with SQL

Text blocks are perfectly safe for SQL when:

1. Static queries (no variables): String query = """SELECT * FROM users""";

2. PreparedStatement placeholders: String query = """WHERE id = ?"""; (parameters set via setString/setInt/etc)

3. Non-executable purposes: Logging, documentation, display-only queries

When Text Blocks Are UNSAFE with SQL

Never use formatted() with SQL when:

1. Any user input is involved (form fields, URL parameters, API requests)

2. External data sources (file uploads, API responses, message queues)

3. Any untrusted data that could be manipulated

HTML/XSS Injection Risks

WARNING: Using formatted() with HTML and user input creates Cross-Site Scripting (XSS) vulnerabilities.

The Danger

When you embed user input directly into HTML using formatted(), attackers can inject malicious scripts:

// ❌ DANGEROUS - XSS Vulnerability
String username = userInput;  // User enters: "<script>alert('XSS')</script>"
String html = """
    <html>
      <body>
        <h1>Welcome, %s!</h1>
      </body>
    </html>""".formatted(username);
// Resulting HTML: <h1>Welcome, <script>alert('XSS')</script>!</h1>
// The script executes in the browser, potentially stealing cookies or performing unauthorized actions!

The Safe HTML Pattern

Always escape HTML entities when inserting user input into HTML:

// ✅ SAFE - Escape HTML entities before formatting
public static String escapeHtml(String input) {
    return input
        .replace("&", "&")
        .replace("<", "&lt;")
        .replace(">", "&gt;")
        .replace("\"", "&quot;")
        .replace("'", "&#x27;");
}

String username = escapeHtml(userInput);  // Converts <script> to &lt;script&gt;
String html = """
    <html>
      <body>
        <h1>Welcome, %s!</h1>
      </body>
    </html>""".formatted(username);
// Resulting HTML: <h1>Welcome, &lt;script&gt;alert('XSS')&lt;/script&gt;!</h1>
// The script is displayed as text, not executed!

Alternative: Use dedicated HTML templating libraries (Thymeleaf, Freemarker) that automatically escape variables and provide built-in XSS protection.

See Example 7 (SimpleTemplateSystemExample) for safe template patterns with non-executable content like emails and invoices.

Safe Use Cases for formatted()

formatted() with text blocks is completely safe for:

1. Email Templates - User input is content, not executable code

2. Invoice/Receipt Generation - Display-only data

3. Configuration Files - Properties and values, no SQL/HTML

4. API Response Templates - JSON/XML data structures (ensure proper JSON escaping if needed)

5. Log Messages - Contextual information for debugging

Summary

Remember:

• For SQL with dynamic values → Always use PreparedStatement

• For HTML with user input → Always escape HTML entities

• For safe contexts (emails, configs, logs) → formatted() is fine

• Text blocks are for readability, not security

When to Use Text Blocks

✅ Text blocks are ideal for:

1. Embedded Languages and Markup

• JSON, XML, HTML structures

• SQL queries (especially complex ones with CTEs)

• GraphQL, YAML configurations

• SVG and other vector formats

• Any literal multi-line code in other languages

2. Test Fixtures and Test Data

• Mock JSON responses for API testing

• Structured test data (CSV, XML, HTML)

• Expected output validation in tests

• Configuration templates

3. Documentation and Error Messages

• Multi-line log messages with structure

• Formatted error messages for users

• Documentation templates

• Code examples embedded as strings

4. Dynamic Content with formatted()

• Parameterized SQL queries

• Email templates with variables

• API request bodies with dynamic fields

• Configuration files with placeholders

When NOT to Use Text Blocks

❌ Avoid text blocks when:

1. Single-Line Strings

// Don't do this
String message = """
    Hello World
    """;

// Do this instead
String message = "Hello World";

2. Strings Requiring Platform-Specific Line Endings

// Don't rely on text blocks for Windows-specific line endings
// Text blocks always normalize line terminators to \n (Unix style)
// If you need Windows-style \r\n (CRLF), convert explicitly:
String textBlock = """
    Line 1
    Line 2
    """;
String crlf = textBlock.replace("\n", "\r\n");  // Converts LF to CRLF

3. Complex String Processing

If the string needs heavy regex or manipulation after creation, use regular strings for clarity:

// Awkward: Text block with immediate complex processing
String processed = """
    user@example.com
    admin@example.com
    """.replaceAll("[\\r\\n]+", ",").trim();
// Result: "user@example.com,admin@example.com"

// Better: Regular string is clearer for processed data
String[] emails = {"user@example.com", "admin@example.com"};
String processed = String.join(",", emails);

Performance Considerations

Text blocks have zero runtime overhead compared to traditional strings:

• Compiled to identical bytecode

• No performance penalty vs. concatenation

• String pooling works normally

• Use freely without performance concerns

Compilation Performance

Text block processing happens entirely at compile time, not runtime:

Compile-Time Operations:

• Indentation stripping is calculated when javac compiles the code

• Line terminator normalization (converting \r\n to \n) happens during compilation

• Escape sequence processing occurs at compile time

• The resulting bytecode contains a plain String constant

Bytecode Equivalence:

// Text block source code
String block = """
    Hello
    World
    """;

// Compiles to identical bytecode as:
String traditional = "Hello\nWorld\n";

The JVM sees no difference between text blocks and traditional strings—they produce the exact same bytecode. This means:

• No runtime CPU overhead for indentation calculations

• No memory overhead for storing indentation metadata

• No performance difference in String creation, comparison, or manipulation

• JIT compiler optimizations apply identically to both forms

Practical Impact: You can use text blocks in performance-critical code (hot loops, high-throughput services) without any concerns. The readability benefit comes at zero runtime cost.

Text Blocks vs Template Engines

Understanding when to use text blocks versus full template engines (Thymeleaf, Freemarker, Velocity) is crucial for architecture decisions.

When to Use Text Blocks

Ideal for:

• Simple interpolation: Few variables, straightforward logic

• Build-time templates: Configuration files, code generation

• Test fixtures: Mock responses, expected output validation

• Small scope: Single-purpose, non-reusable templates

• No external files: Template lives alongside code

Example use cases:

// Email notifications with 3-5 variables
String email = """
    Welcome, %s!
    Your order #%s has shipped.
    """.formatted(name, orderId);

// API response templates
String response = """
    {"status": "%s", "data": %s}
    """.formatted(status, jsonData);

// Test expected output
String expected = """
    User: Alice
    Balance: $100.00
    """;

When to Use Template Engines

Required for:

• Complex logic: Conditionals, loops, nested structures

• External templates: Designers/non-developers maintain templates

• Reusability: Same template used in multiple places

• Internationalization: Multi-language support with resource bundles

• Security features: Built-in HTML escaping, auto-sanitization

• Rich functionality: Includes, partials, macros, filters

Example use cases:

// Thymeleaf for complex HTML with logic
<div th:if="${user.premium}">
    <h2>Welcome, Premium Member!</h2>
    <ul>
        <li th:each="feature : ${premiumFeatures}" th:text="${feature}"></li>
    </ul>
</div>

// Freemarker for dynamic content generation
<#list products as product>
    <#if product.stock > 0>
        ${product.name}: $${product.price}
    </#if>
</#list>

Resources

Official Documentation

• JEP 378 - Text Blocks: openjdk.org/jeps/378 The official Java Enhancement Proposal introducing text blocks in Java 15. Includes design rationale, indentation rules, and escape sequence specifications.

• JEP 359 - Record Classes (Preview): openjdk.org/jeps/359 First preview in Java 14 showing the evolution of text blocks across preview stages.

• Java Language Specification - Text Blocks: docs.oracle.com/javase/specs/jls/se17/html/jls-3.html#jls-3.3 Formal specification of text block syntax and semantics in the Java Language Specification.

• Java Platform String Documentation: docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/String.html Complete API documentation including the formatted() method for string interpolation.

Interactive References

• Java Almanac - Text Blocks: javaalmanac.io/features/text-blocks/ Interactive examples with runnable code demonstrating text block syntax and patterns.

• Java Tutorials - Text Blocks: docs.oracle.com/javase/tutorial/java/data/textblocks.html Official Oracle tutorial covering text block basics and common use cases.

Code Repository

• GitHub Repository - blog-9mac-dev-code: github.com/dawid-swist/blog-9mac-dev-code All examples from this article with complete JUnit test suite:

    git clone https://github.com/dawid-swist/blog-9mac-dev-code.git
    cd blog-post-examples/java/2025-10-25-java17-features-every-senior-developer-should-know
    ../../gradlew test --tests *part5*
  

Additional Reading

• Brian Goetz - State of the Specification: Java language architect's updates on evolution

• Inside Java Podcast - Text Blocks Episodes: Design decisions and implementation details

• Effective Java (3rd Edition): Consider using text blocks for clarity when maintaining embedded language strings

Summary.

Implementation Checklist for Your Code

When migrating to text blocks:

• ✅ Identify multi-line string literals (JSON, SQL, HTML, XML)

• ✅ Replace concatenation with triple-quote delimiters

• ✅ Verify indentation is correct (closing """ determines strip level)

• ✅ Remove unnecessary escape sequences (\" becomes ")

• ✅ Use formatted() for parameterized strings instead of multiple calls

• ✅ Test edge cases (empty lines, trailing whitespace, special characters)

• ✅ Update test fixtures to use text blocks for readability

Common Mistakes to Avoid

1. Forgetting newline after opening """

    // Wrong - content on same line as opening delimiter
    String block = """Hello""";
   
    // Correct - newline after opening delimiter
    String block = """
        Hello""";
   

2. Misunderstanding indent stripping

    // This strips 4 spaces (closing """ is indented at 4 spaces)
    String block = """
        Content""";  // Result: "Content\n"
   
    // This strips 0 spaces (closing """ at left margin, content not indented)
    String block = """
    Content""";  // Result: "Content\n"
   
    // This doesn't strip anything (closing """ at left margin, content indented)
    String block = """
        Content
    """;  // Result: "    Content\n"
   

3. Forgetting that trailing whitespace is removed

    // Trailing spaces after "text" are removed
    String block = """
        text   \
        more
        """;  // Use \s if you need trailing space
   

4. Using formatted() with SQL (SQL Injection Risk)

    // DANGEROUS: This is vulnerable to SQL injection!
    String sql = """
        SELECT * FROM table WHERE name = '%s'
        """.formatted(name);
   
    // SAFE: Always use PreparedStatement with parameterized queries
    String query = """
        SELECT * FROM table WHERE name = ?
        """;
    PreparedStatement ps = connection.prepareStatement(query);
    ps.setString(1, name);
   

Written for blog.9mac.devPart of the "Java 17 Features Every Senior Developer Should Know" series

Previous: Part 4 - Pattern Matching & Switch Expressions Next: Part 6 - Summary with Syntax Cheat Sheet

These features represent Java's first serious steps toward pattern matching—a programming paradigm that functional languages have enjoyed for decades. For developers upgrading from Java 8, this is where modern Java starts to feel truly different.

What is Pattern Matching?

Pattern matching is a general programming concept—not specific to Java—for checking a value against a pattern and, if it matches, deconstructing that value into its constituent parts. Java introduces pattern matching incrementally across multiple language features.

In academic terms, pattern matching is a form of structural decomposition combined with conditional dispatch. You're simultaneously asking "what shape is this data?" and "if it matches, bind the components to names I can use."

Pattern Matching in Java: Multiple Forms

Java's approach to pattern matching is incremental—different patterns are added in different versions:

1. Type patterns (Java 16+): instanceof Circle c - match and cast types

2. Guarded patterns (Java 16+): Add conditions with when clause: instanceof String s when s.length() > 0

3. Record patterns (Java 17+): Destructure records - case Point(int x, int y) ->

4. Array patterns (Preview, future): Match array contents - coming in future versions

Each form can appear in different contexts:

• instanceof expressions (Java 16+): Type checking with automatic casting

• switch statements/expressions (Java 14+ with patterns in Java 17+)

The Problem Pattern Matching Solves

Traditional imperative programming requires multiple steps to work with polymorphic data:

1. Check the type using instanceof

2. Cast to that type manually

3. Extract components (for records)

4. Repeat for each possible type

Pattern matching collapses these steps into declarative syntax that's both safer and more concise. Instead of procedural "how to check," you write declarative "what to match." This represents a paradigm shift that:

• Reduces boilerplate: Eliminates manual type casting and null checks

• Improves safety: Compiler enforces exhaustiveness and correct variable scopes

• Reduces errors: Prevents entire classes of type-casting and null-pointer bugs

• Clarifies intent: Makes code more readable by expressing "what we're matching for" rather than "how to check"

Historical Context: Java 1-8

To appreciate pattern matching, we need to understand the pain points it solves. Let's examine how Java developers handled type checking and conditional logic before Java 14-16.

The instanceof-cast Ceremony

Before pattern matching, checking types required explicit casting—a source of verbosity and potential ClassCastException errors:

// Pre-Java 16: The instanceof-cast pattern
public String describe(Object obj) {
    if (obj instanceof String) {
        String s = (String) obj;  // Manual cast required
        return "String of length " + s.length();
    } else if (obj instanceof Integer) {
        Integer i = (Integer) obj;  // Repeated pattern
        return "Integer: " + i;
    } else {
        return "Unknown type";
    }
}

Problems with this approach:

• Redundancy: We write String three times in a single branch

• Error-prone: Nothing prevents casting to the wrong type

• Verbose: The pattern obscures the business logic

• Refactoring friction: Changing types means updating multiple lines

This "test-and-cast" idiom was so common that IDEs created templates for it, but the fundamental problem remained: the language didn't support what we were trying to express.

The Classic Switch Statement

Traditional switch statements had their own set of issues:

// Pre-Java 14: Classic switch with fall-through
public int getDaysInMonth(String month) {
    int days;
    switch (month) {
        case "January":
        case "March":
        case "May":
        case "July":
        case "August":
        case "October":
        case "December":
            days = 31;
            break;
        case "February":
            days = 28;
            break;
        case "April":
        case "June":
        case "September":
        case "November":
            days = 30;
            break;
        default:
            throw new IllegalArgumentException("Invalid month");
    }
    return days;
}

Problems:

• Fall-through behavior: Forgetting break causes bugs (the infamous "fall-through" error)

• Not an expression: Can't assign switch results directly to variables

• Verbose grouping: Multiple cases cascade without clear grouping syntax

• Mutation required: Need to declare variable before switch, assign inside

• No exhaustiveness checking: Compiler won't warn about missing cases (except for enums with -Xlint)

The -Xlint:fallthrough warning existed, but it was a band-aid on a fundamental design flaw.

Equals Method Boilerplate

The equals() method implementation was particularly painful:

// Pre-Java 16: Traditional equals() implementation
public class Point {
    private final int x, y;

    @Override
    public boolean equals(Object obj) {
        if (this == obj) return true;
        if (obj == null) return false;
        if (getClass() != obj.getClass()) return false;

        Point other = (Point) obj;  // Manual cast after type check
        return this.x == other.x && this.y == other.y;
    }
}

The pattern is mechanical, but it requires four lines just to get to the actual comparison logic.

Java 16+ introduced pattern matching to eliminate the test-and-cast ceremony, while Java 14+ made switch expressions return values and prevent fall-through bugs. Java 17 brings these together: pattern matching in switch statements creates powerful, concise conditional logic.

Changes to instanceof (Java 16+)

Java 16 introduced major changes to the instanceof operator via Pattern Matching for instanceof (JEP 394). In the Java Language Specification, this feature is referred to as "pattern variables" or "type patterns in instanceof".

These changes finally bring to Java a feature that other languages have had for decades. Swift, Scala, and functional languages like Haskell pioneered pattern matching as a way to combine type checking, casting, and value extraction into a single expression.

Java's conservative approach meant pattern matching arrived later, but it's now transforming how we write conditional logic, eliminating the test-and-cast ceremony that plagued Java for decades.

Basic Syntax

The new syntax combines type checking and casting in one operation:

// Java 16+: Pattern matching for instanceof
if (obj instanceof String s) {
    // 's' is in scope here, already cast to String
    System.out.println("Length: " + s.length());
}

// Before Java 16 - required manual cast
if (obj instanceof String) {
    String s = (String) obj;
    System.out.println("Length: " + s.length());
}

The pattern variable s is automatically cast and scoped to where the type check succeeds.

Scope Rules

The pattern variable is only in scope where the compiler can prove it was assigned.

How Pattern Variables Are Scoped

Rule 1: After instanceof in same if-block

if (obj instanceof String s) {
    // ✓ 's' is a String here
    System.out.println(s.length());
}

Rule 2: With && (AND) on the right side

if (obj instanceof String s && s.length() > 5) {
    // ✓ 's' is a String AND length > 5 here
    System.out.println(s.toUpperCase());
}

Rule 3: NOT with || (OR) on the right side

if (obj instanceof String s || isTrusted(obj)) {
    // ✗ DOES NOT COMPILE
    // 's' might not exist if isTrusted() was true instead
    System.out.println(s.length());
}

// ✓ CORRECT: Use separate if statements
if (obj instanceof String s) {
    System.out.println(s.length());
}
if (isTrusted(obj)) {
    System.out.println("Trusted");
}

Rule 4: In else block with negation

if (!(obj instanceof String s)) {
    // 's' is NOT in scope here (obj is not a String)
} else {
    // ✓ 's' IS in scope here (obj is definitely a String)
    System.out.println(s.length());
}

Null Handling

Pattern matching handles null naturally—instanceof already returns false for null:

Object obj = null;
if (obj instanceof String s) {
    // This block never executes for null
}

This is safer than manual casting, which required explicit null checks.

Real-World Benefits

Pattern matching shines in polymorphic code:

// Before: Verbose hierarchy traversal
public void processShape(Shape shape) {
    if (shape instanceof Circle) {
        Circle c = (Circle) shape;
        System.out.println("Circle radius: " + c.radius());
    } else if (shape instanceof Rectangle) {
        Rectangle r = (Rectangle) shape;
        System.out.println("Rectangle: " + r.width() + "x" + r.height());
    }
}

// After: Concise and clear
public void processShape(Shape shape) {
    if (shape instanceof Circle c) {
        System.out.println("Circle radius: " + c.radius());
    } else if (shape instanceof Rectangle r) {
        System.out.println("Rectangle: " + r.width() + "x" + r.height());
    }
}

Switch Expressions (Java 14+)

Java 14 introduced switch expressions (JEP 361), transforming switch from a statement to an expression that returns values.

Arrow Syntax (->)

The new arrow syntax eliminates fall-through:

// Java 14+: Switch expression with arrows
String dayType = switch (day) {
    case MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY -> "Weekday";
    case SATURDAY, SUNDAY -> "Weekend";
};

// Before Java 14: Switch statement
String dayType;
switch (day) {
    case MONDAY:
    case TUESDAY:
    case WEDNESDAY:
    case THURSDAY:
    case FRIDAY:
        dayType = "Weekday";
        break;
    case SATURDAY:
    case SUNDAY:
        dayType = "Weekend";
        break;
    default:
        throw new IllegalArgumentException();
}

Key differences:

• No fall-through: Each case executes exactly its branch

• Expression: Returns a value directly

• Concise: Multiple labels separated by commas

• No break needed: Implicit at end of each branch

The yield Keyword

For multi-statement branches, use yield to return a value:

int result = switch (operator) {
    case "+" -> {
        System.out.println("Adding");
        yield a + b;
    }
    case "-" -> {
        System.out.println("Subtracting");
        yield a - b;
    }
    default -> throw new IllegalArgumentException();
};

yield is like return for switch expressions.

Exhaustiveness

Switch expressions must be exhaustive—they must handle all possible values:

// Enum switch: Must cover all values OR include default
enum Color { RED, GREEN, BLUE }

String name = switch (color) {
    case RED -> "Red";
    case GREEN -> "Green";
    case BLUE -> "Blue";
    // No default needed - all enum values covered
};

// Primitives and strings: Must include default
String describe = switch (num) {
    case 0 -> "Zero";
    case 1 -> "One";
    default -> "Other";  // Required for non-enum types
};

The compiler enforces exhaustiveness, preventing bugs from missing cases.

Four Forms of Switch

Java now has four switch variants:

Best practice: Prefer arrow syntax for new code. Use colon syntax only when you need fall-through (rare).

Pattern Matching in Switch (Java 17+)

Java 17 brought pattern matching in switch expressions (JEP 406), combining everything you've learned so far into one powerful feature. Instead of using instanceof checks for pattern matching, you can now directly match patterns inside switch expressions.

Type Patterns in Switch

Match different types directly without instanceof:

String result = switch (obj) {
    case String s -> "String: " + s;
    case Integer i -> "Integer: " + i;
    case Double d -> "Double: " + d;
    case null -> "Null value";
    default -> "Unknown type";
};

Guarded Patterns

Add conditions to patterns using the when clause:

String classify = switch (obj) {
    case String s when s.isEmpty() -> "Empty string";
    case String s when s.length() < 5 -> "Short string: " + s;
    case String s -> "Long string: " + s;
    default -> "Not a string";
};

Sealed Types with Pattern Matching

Sealed types + pattern matching = exhaustiveness guaranteed by the compiler:

sealed interface Shape permits Circle, Rectangle, Triangle {}
record Circle(double radius) implements Shape {}
record Rectangle(int width, int height) implements Shape {}
record Triangle(int base, int height) implements Shape {}

int area = switch (shape) {
    case Circle c -> (int) (Math.PI * c.radius() * c.radius());
    case Rectangle r -> r.width() * r.height();
    case Triangle t -> (t.base() * t.height()) / 2;
    // No default needed - compiler enforces all cases
};

Record Patterns

Destructure records directly in switch patterns:

record Point(int x, int y) {}

String location = switch (obj) {
    case Point(int x, int y) when x > 0 && y > 0 -> "Quadrant 1";
    case Point(int x, int y) when x < 0 && y > 0 -> "Quadrant 2";
    case Point(int x, int y) when x == 0 && y == 0 -> "Origin";
    default -> "Other";
};

Practical Examples

Let's explore pattern matching and switch expressions through seven comprehensive examples.

Example 1: Basic Pattern Matching with instanceof

Pattern matching for instanceof eliminates redundant casting and makes type checks more concise.

Before (Java 8-15):

if (obj instanceof String) {
    String s = (String) obj;
    return "String of length " + s.length();
} else if (obj instanceof Integer) {
    Integer i = (Integer) obj;
    return "Integer: " + i;
}

After (Java 16+):

if (obj instanceof String s) {
    return "String of length " + s.length();
} else if (obj instanceof Integer i) {
    return "Integer: " + i;
}

Full Example:

public class BasicPatternMatchingExample {

    // Java 16+ pattern matching
    public static String describeModern(Object obj) {
        if (obj instanceof String s) {
            return "String of length " + s.length();
        } else if (obj instanceof Integer i) {
            return "Integer: " + i;
        } else if (obj instanceof Double d) {
            return "Double: " + d;
        }
        return "Unknown type";
    }

    // Demonstrating scope rules with && (AND) and negation
    public static String demonstrateScope(Object obj) {
        if (obj instanceof String s && s.length() > 5) {
            return "Long string: " + s.toUpperCase();
        }
        if (!(obj instanceof String s)) {
            return "Not a string";
        }
        return "String in else: " + s;
    }
}

Test:

@Test
void shouldUsePatternMatching() {
    assertEquals("String of length 5",
        BasicPatternMatchingExample.describeModern("Hello"));
}

Key Insight: Pattern matching combines type checking, casting, and variable binding in a single operation. The scope rules ensure pattern variables only exist where the type check succeeds—in the if-block, with && operators on the right side, or in negation blocks.

Example 2: Switch Expressions with Enums

Switch expressions with enums demonstrate exhaustiveness checking—the compiler ensures all enum values are handled.

Before (Java 8-13):

String result;
switch (day) {
    case MONDAY:
    case TUESDAY:
        result = "Weekday";
        break;
    case SATURDAY:
    case SUNDAY:
        result = "Weekend";
        break;
    default:
        throw new IllegalArgumentException();
}

After (Java 14+):

String result = switch (day) {
    case MONDAY, TUESDAY -> "Weekday";
    case SATURDAY, SUNDAY -> "Weekend";
};

Full Example:

public class SwitchEnumExample {
    public enum Day { MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY }

    // Modern switch expression with grouped cases
    public static String getDayType(Day day) {
        return switch (day) {
            case MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY -> "Weekday";
            case SATURDAY, SUNDAY -> "Weekend";
        };
    }

    // No default needed - all enum values covered by compiler
    public static int getSeasonMonths(String season) {
        return switch (season) {
            case "SPRING" -> 3;
            case "SUMMER" -> 3;
            case "FALL" -> 3;
            case "WINTER" -> 3;
        };
    }
}

Test:

@Test
void shouldClassifyDaysWithSwitch() {
    assertEquals("Weekday", SwitchEnumExample.getDayType(Day.MONDAY));
    assertEquals("Weekend", SwitchEnumExample.getDayType(Day.SATURDAY));
}

Key Insight: Switch expressions with enums benefit from exhaustiveness checking. When all enum values are covered, no default case is needed. The compiler will error if a new enum value is added without updating the switch.

Example 3: Switch Expressions with yield

The yield keyword allows multi-statement branches in switch expressions, enabling complex logic while still returning a value.

public class SwitchYieldExample {

    public enum Operation { ADD, SUBTRACT, MULTIPLY, DIVIDE }

    // Simple yield: single statement in braces
    public static double calculate(Operation op, double a, double b) {
        return switch (op) {
            case ADD -> {
                System.out.println("Adding...");
                yield a + b;
            }
            case SUBTRACT -> {
                System.out.println("Subtracting...");
                yield a - b;
            }
            case MULTIPLY -> a * b;
            case DIVIDE -> (b == 0) ? Double.NaN : a / b;
        };
    }

    // Complex logic: validation with yield
    public static String getGrade(int score) {
        return switch (score / 10) {
            case 10, 9 -> "A";
            case 8 -> "B";
            case 7 -> "C";
            default -> {
                if (score < 0 || score > 100) {
                    throw new IllegalArgumentException("Invalid: " + score);
                }
                yield "F";
            }
        };
    }
}

Test:

@Test
void shouldUseYieldForMultiStatementBranches() {
    assertEquals(15.0, calculate(Operation.ADD, 10, 5), 0.001);
    assertEquals("A", getGrade(95));
    assertEquals("F", getGrade(45));
}

Key Insight: The yield keyword enables multi-statement logic within switch branches. Unlike the arrow syntax (->), which executes a single expression, yield allows statements with side effects (like logging) before returning a value. This combines conciseness with flexibility.

Example 4: Pattern Matching in Switch (Java 17+)

Pattern matching in switch expressions (JEP 406) combines type matching, guards, and record destructuring into a single powerful feature.

public class PatternSwitchExample {

    // Type patterns - match and extract different types
    public static String processObject(Object obj) {
        return switch (obj) {
            case String s -> "String: " + s;
            case Integer i -> "Integer: " + i;
            case Double d -> "Double: " + d;
            case null -> "Null value";
            default -> "Unknown";
        };
    }

    // Record patterns with guarded patterns
    public record Point(int x, int y) {}

    public static String describePoint(Object obj) {
        return switch (obj) {
            case Point(int x, int y) when x > 0 && y > 0 ->
                "Quadrant 1: (" + x + ", " + y + ")";
            case Point(int x, int y) when x < 0 && y > 0 ->
                "Quadrant 2: (" + x + ", " + y + ")";
            case Point(int x, int y) when x == 0 && y == 0 ->
                "Origin";
            case Point(int x, int y) ->
                "Other: (" + x + ", " + y + ")";
            default -> "Not a point";
        };
    }
}

Test:

@Test
void shouldUsePatternMatchingInSwitch() {
    assertEquals("String: Hello",
        PatternSwitchExample.processObject("Hello"));
    assertEquals("Null value",
        PatternSwitchExample.processObject(null));
    assertEquals("Quadrant 1: (3, 4)",
        PatternSwitchExample.describePoint(new Point(3, 4)));
}

Key Insight: Pattern matching in switch combines type patterns (like case String s), guarded patterns (like when x > 0), and record destructuring (like case Point(int x, int y)). This eliminates the need for instanceof checks and manual casting, resulting in cleaner, more type-safe code.

Example 5: Pattern Matching with Type Hierarchies

When handling polymorphic types, pattern matching eliminates the redundancy of explicit casting. Instead of writing type names three times (instanceof, cast declaration, cast operation), do it once with pattern matching.

Before Java 16 - Explicit casting required:

if (shape instanceof Circle) {
    Circle c = (Circle) shape;  // ← Type name appears 3 times!
    return "Radius: " + c.radius();
} else if (shape instanceof Rectangle) {
    Rectangle r = (Rectangle) shape;  // ← Redundant
    return "Width: " + r.width();
}

Java 16+ - Pattern matching eliminates redundancy:

if (shape instanceof Circle c) {  // ← All three operations: check, cast, bind
    return "Radius: " + c.radius();
} else if (shape instanceof Rectangle r) {
    return "Width: " + r.width();
}

Full Example:

public class TypeHierarchyExample {

    sealed interface Shape permits Circle, Rectangle, Triangle {}
    record Circle(double radius) implements Shape {}
    record Rectangle(double width, double height) implements Shape {}
    record Triangle(double base, double height) implements Shape {}

    // Modern approach with pattern matching
    public static String describe(Shape shape) {
        return switch (shape) {
            case Circle c -> "Circle: radius=" + c.radius();
            case Rectangle r -> "Rectangle: " + r.width() + "x" + r.height();
            case Triangle t -> "Triangle: base=" + t.base();
        };
    }
}

Test:

@Test
void shouldEliminateTypeCastingWithPatternMatching() {
    Shape circle = new Circle(5.0);
    Shape rect = new Rectangle(10.0, 20.0);

    assertEquals("Circle: radius=5.0", describe(circle));
    assertTrue(describe(rect).contains("Rectangle"));
}

Key Insight: Sealed types + pattern matching guarantee exhaustiveness. The compiler knows all Shape subtypes. When you use sealed types with switch pattern matching, no default case is needed—the compiler will error if you forget to handle a subtype. This prevents entire classes of runtime type errors.

Example 6: Implementing equals() with Pattern Matching

Pattern matching eliminates boilerplate from equals() methods. Instead of explicit null checks, type checks, and casting, pattern matching does it all in one line.

Before Java 16 - 6 lines of ceremony:

@Override
public boolean equals(Object obj) {
    if (this == obj) return true;
    if (obj == null) return false;
    if (getClass() != obj.getClass()) return false;
    Point other = (Point) obj;              // ← Manual cast after type check
    return this.x == other.x && this.y == other.y;
}

Java 16+ - Pattern matching eliminates all boilerplate:

@Override
public boolean equals(Object obj) {
    return obj instanceof Point p &&        // ← Type check + cast + bind in ONE
           this.x == p.x && this.y == p.y;
}

Full Example:

public class EqualsPatternMatchingExample {

    public record Point(int x, int y) {
        @Override
        public boolean equals(Object obj) {
            return obj instanceof Point p &&
                   this.x == p.x && this.y == p.y;
        }
    }

    public record Person(String name, int age) {
        @Override
        public boolean equals(Object obj) {
            return obj instanceof Person p &&
                   Objects.equals(this.name, p.name) &&
                   this.age == p.age;
        }
    }
}

Test:

@Test
void shouldUsePatternMatchingInEquals() {
    Point p1 = new Point(10, 20);
    Point p2 = new Point(10, 20);

    assertTrue(p1.equals(p2));
    assertFalse(p1.equals(null));
}

Key Insight: Pattern matching replaces 6 lines of equals() boilerplate with 1 line. The instanceof pattern automatically handles null (returns false), type checking, and casting—all atomically. This eliminates an entire class of bugs where type checks and casts could be misaligned.

Example 7: Sealed Types with Pattern Matching (Result)

Pattern matching reaches its full potential with sealed types. A Result can only be Success or Failure—the compiler enforces exhaustiveness. Add a new type, and all pattern matching code fails to compile until updated.

public class ResultPatternExample {

    public sealed interface Result<T> permits Success, Failure {}
    public record Success<T>(T value) implements Result<T> {}
    public record Failure<T>(String error) implements Result<T> {}

    // Pattern matching with sealed types
    public static <T> String describe(Result<T> result) {
        return switch (result) {
            case Success<T> s -> "Success: " + s.value();
            case Failure<T> f -> "Failure: " + f.error();
            // No default needed - compiler knows these are the only two cases!
        };
    }

    // Functional transformation preserving sealed type contracts
    public static <T, U> Result<U> map(Result<T> result, Function<T, U> fn) {
        return switch (result) {
            case Success<T> s -> new Success<>(fn.apply(s.value()));
            case Failure<T> f -> new Failure<>(f.error());
        };
    }
}

Test:

@Test
void shouldEnforceSealedTypeExhaustiveness() {
    Result<String> success = new Success<>("Value");
    Result<String> failure = new Failure<>("Error");

    assertEquals("Success: Value", describe(success));
    assertEquals("Failure: Error", describe(failure));
    assertEquals("Success: 10",
        describe(map(new Success<>(5), x -> x * 2)));
}

Key Insight: Sealed types + pattern matching = compiler enforced exhaustiveness. The compiler knows Success and Failure are the ONLY two cases. If you add a new Result type, all pattern matching code fails to compile until updated. This catches bugs at compile-time instead of runtime, and no default case is needed.

Best Practices

When to Use Pattern Matching

✅ Use pattern matching for:

• Polymorphic method dispatch - replacing instanceof chains

• equals() implementations - cleaner than traditional approach

• Validation with type checks - combining instanceof with business logic

• Guard conditions - when you need type + additional condition

❌ Don't use pattern matching when:

• Polymorphism would be better - if you control the hierarchy, add methods instead

• Type checks indicate design issues - consider refactoring to avoid type checking

• Performance is absolutely critical - pattern matching has negligible overhead, but direct method calls are still faster

When to Use Switch Expressions

✅ Use switch expressions for:

• Mapping enum values - exhaustiveness checking prevents bugs

• Returning values from multi-way branches - cleaner than if-else chains

• Complex conditional logic - when multiple conditions determine a result

❌ Don't use switch expressions when:

• A single if-else would suffice - don't over-engineer

• You need fall-through - rare, but use colon syntax if needed

• Cases have complex, unrelated logic - consider separate methods

Style Guidelines

Prefer modern patterns:

// ✅ Good: concise and clear
if (obj instanceof String s && s.length() > 0) {
    return s.toUpperCase();
}

// ❌ Avoid: old style
if (obj instanceof String) {
    String s = (String) obj;
    if (s.length() > 0) {
        return s.toUpperCase();
    }
}

Use meaningful variable names:

// ✅ Good: descriptive names
if (shape instanceof Circle c) {
    return Math.PI * c.radius() * c.radius();
}

// ❌ Avoid: single letters unless context is obvious
if (shape instanceof Circle x) {
    return Math.PI * x.radius() * x.radius();
}

Group related cases in switch:

// ✅ Good: logically grouped
return switch (day) {
    case MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY -> "Weekday";
    case SATURDAY, SUNDAY -> "Weekend";
};

// ❌ Avoid: unnecessarily separate
return switch (day) {
    case MONDAY -> "Weekday";
    case TUESDAY -> "Weekday";
    // ... repetitive
};

Summary and Next Steps

What we covered:

1. Pattern matching for instanceof (Java 16) eliminates test-and-cast ceremony

2. Switch expressions (Java 14) make switch a first-class expression with exhaustiveness

3. Arrow syntax (->) prevents fall-through bugs

4. yield keyword enables multi-statement branches in switch expressions

5. Pattern variables have compiler-enforced scope based on flow analysis

6. Combining patterns with guards creates powerful conditional logic

7. Sealed types + pattern matching = exhaustiveness guarantees

Migration Strategy

For teams upgrading from Java 8:

Phase 1: Switch Expressions

• Replace switch statements returning values with switch expressions

• Use arrow syntax for new code

• Keep colon syntax for rare fall-through cases

Phase 2: Pattern Matching

• Update equals() methods to use pattern matching

• Replace instanceof-cast chains with pattern matching

• Add guard conditions where appropriate

Phase 3: Combined Patterns

• Refactor complex type hierarchies with sealed types + pattern matching

• Leverage exhaustiveness checking for safer refactoring

Resources

Official Documentation

• JEP 394 - Pattern Matching for instanceof: openjdk.org/jeps/394 The official proposal introducing pattern matching for instanceof in Java 16. Includes design rationale, scope rules, and future directions.

• JEP 361 - Switch Expressions: openjdk.org/jeps/361 Finalized switch expressions in Java 14. Details arrow syntax, yield keyword, and exhaustiveness requirements.

• JEP 325 - Switch Expressions (Preview): openjdk.org/jeps/325 First preview in Java 12, showing the evolution of the feature.

• JEP 354 - Switch Expressions (Second Preview): openjdk.org/jeps/354 Refinements in Java 13 based on community feedback.

Interactive References

• Java Almanac - instanceof Patterns: javaalmanac.io/features/instanceof-patterns/ Interactive examples demonstrating pattern matching for instanceof with runnable code samples.

• Java Almanac - Switch: javaalmanac.io/features/switch/ Comprehensive guide to switch expressions with visual timelines and comparisons.

Code Repository

• GitHub Repository - blog-9mac-dev-code: github.com/dawid-swist/blog-9mac-dev-code All examples from this article with full JUnit tests:

    git clone https://github.com/dawid-swist/blog-9mac-dev-code.git
    cd blog-post-examples/java/2025-10-25-java17-features-every-senior-developer-should-know
    ../../gradlew test --tests *part4*
  

Additional Reading

• Brian Goetz - "Pattern Matching in the Java Object Model": Technical deep dive from Java's language architect

• Inside Java Podcast - Pattern Matching Episodes: Discussions on design decisions and future directions

• Effective Java (3rd Edition) - Item 14: Consider implementing Comparable Shows how pattern matching can simplify comparison logic

Written for blog.9mac.devPart of the "Java 17 Features Every Senior Developer Should Know" series

Previous: Part 3 - Sealed Classes Next: Part 5 - Text Blocks

If you've ever wanted to restrict which classes can extend your base class without making it final, or if you've struggled with maintaining domain model integrity across large codebases, this article is for you. Sealed classes bring algebraic data types to Java, enabling exhaustive pattern matching and compiler-verified completeness checks.

The Problem: Uncontrolled Inheritance

Before Java 17, you had two options for controlling inheritance:

1. Make the class final - No one can extend it at all

2. Leave it open - Anyone, anywhere can extend it

This binary choice created real problems in large codebases. Consider a payment processing system:

// Before Java 17 - open hierarchy
public abstract class Payment {
    public abstract void process();
}

public class CreditCardPayment extends Payment {
    @Override
    public void process() { /* ... */ }
}

public class DebitCardPayment extends Payment {
    @Override
    public void process() { /* ... */ }
}

// Problem: Anyone can add new payment types!
// Some developer in another module:
public class CryptoPayment extends Payment {
    @Override
    public void process() {
        // Oops - we don't handle this in our switch statement!
    }
}

The issues with uncontrolled inheritance:

• No exhaustiveness checking: When you handle Payment types in a switch, the compiler can't verify you've covered all cases

• Domain model fragmentation: Core abstractions can be extended in unpredictable ways

• Breaking changes: Adding a new payment type should be a deliberate, coordinated change—not an afterthought

• Maintenance burden: Developers must constantly check for new subtypes in distant parts of the codebase

Why final and Open Classes Aren't Enough

Making Payment final means you can't have any subtypes—but you need CreditCardPayment and DebitCardPayment. Leaving it open means anyone can add subtypes, breaking your carefully designed switch statements and validation logic.

What we need: A middle ground where Payment can be extended, but only by the classes we explicitly permit.

What Are Sealed Classes?

A sealed class is a class that restricts which other classes may extend it. You explicitly list the permitted subclasses using the permits clause:

public sealed abstract class Payment
    permits CreditCardPayment, DebitCardPayment, CashPayment {
    public abstract void process();
}

Now, only CreditCardPayment, DebitCardPayment, and CashPayment can extend Payment. Any attempt to create an unlisted subclass results in a compile-time error:

// Compile error: CryptoPayment is not listed in permits clause
public class CryptoPayment extends Payment { }

The Three Subclass Modifiers

Every direct subclass of a sealed class must declare its own inheritance policy using one of three modifiers:

1. final - No further subclassing allowed

2. sealed - Further subclassing permitted, but only to explicitly named subtypes

3. non-sealed - Open to unrestricted subclassing (breaks the seal)

// Option 1: final - no more extensions
public final class CreditCardPayment extends Payment {
    @Override
    public void process() { /* ... */ }
}

// Option 2: sealed - controlled multi-level hierarchy
public sealed class BankTransfer extends Payment
    permits DomesticTransfer, InternationalTransfer {
    @Override
    public void process() { /* ... */ }
}

// Option 3: non-sealed - open for extension
public non-sealed class CashPayment extends Payment {
    @Override
    public void process() { /* ... */ }
}

// Now anyone can extend CashPayment
public class TippedCashPayment extends CashPayment { }

Key Characteristics

Sealed classes have specific properties:

• Restricted inheritance: Only explicitly permitted classes can extend/implement

• Exhaustiveness checking: The compiler knows all possible subtypes for switch statements

• Same package/module requirement: Sealed class and permitted subclasses must be in the same package (or module)

• Sealed interfaces: Interfaces can be sealed identically to classes

• Records and sealed types: Records are implicitly final, suitable for sealed type implementations

History of Sealed Classes

Sealed classes evolved through three Java versions based on community feedback and real-world testing.

Java 15: Preview Feature (JEP 360)

Sealed types debuted in September 2020 as a preview feature, requiring the --enable-preview compiler flag. The basic syntax was introduced:

sealed class Shape permits Circle, Rectangle, Triangle { }

final class Circle extends Shape { }
final class Rectangle extends Shape { }
final class Triangle extends Shape { }

What you got:

• Basic sealed and permits keywords

• Requirement for subclasses to use final, sealed, or non-sealed

• Compile-time verification of permitted subclass list

Limitations:

• Preview status meant production use required caution

• Limited IDE support and tooling

• Syntax still being refined based on feedback

Java 16: Second Preview (JEP 397)

March 2021 brought refinements and clarifications:

Improvements:

• Omitting permits - If all subclasses are in the same source file, permits can be omitted

• Better error messages - Clearer compile errors for seal violations

• Sealed interfaces - Full support for sealed interfaces, not just classes

• Record integration - Records work seamlessly as sealed type implementations

// Java 16 - permits clause optional if subclasses in same file
sealed class Result { }
final class Success extends Result { }
final class Failure extends Result { }

Java 17: Standard Feature (JEP 409)

September 2021 marked the graduation of sealed classes to a standard, permanent feature. No more --enable-preview flag needed.

Final enhancements:

• Reflection API - Class.isSealed() and Class.getPermittedSubclasses()

• Pattern matching synergy - Full integration with pattern matching features

• Exhaustive switch - Compiler recognizes when switch covers all sealed subtypes

• Production-ready - Full IDE support, stable API, comprehensive documentation

Basic Syntax and Features

Declaration Syntax

The basic sealed class declaration consists of:

1. The sealed modifier (or sealed interface for interfaces)

2. The class/interface name

3. The permits clause listing allowed subclasses

4. Optional class body

// Sealed class with permits
public sealed abstract class Shape
    permits Circle, Rectangle, Triangle {
    public abstract double area();
}

// Sealed interface
public sealed interface JSONValue
    permits JSONObject, JSONArray, JSONString, JSONNumber, JSONBoolean, JSONNull {
    String toJson();
}

Omitting the permits Clause

If all permitted subclasses are declared in the same source file, you can omit permits:

// All in one file - no permits needed
sealed class Result { }
final class Success extends Result { }
final class Failure extends Result { }

The compiler infers the permitted subclasses from the file contents.

Subclass Requirements

Every direct subclass must:

1. Be in the same package as the sealed parent (or same module if using JPMS)

2. Explicitly extend/implement the sealed parent

3. Choose a modifier: final, sealed, or non-sealed

// ✅ Valid - final subclass
public final class Circle extends Shape {
    @Override
    public double area() { return Math.PI * radius * radius; }
}

// ✅ Valid - sealed subclass with its own hierarchy
public sealed class Polygon extends Shape
    permits Triangle, Rectangle, Pentagon {
    // ...
}

// ✅ Valid - non-sealed subclass (breaks the seal)
public non-sealed class FreeformShape extends Shape {
    // Anyone can extend FreeformShape now
}

// ❌ Invalid - missing final/sealed/non-sealed
public class InvalidShape extends Shape { } // Compile error

Design Philosophy: Why Sealed Controls Only Direct Children

You might wonder: why doesn't sealing a class control the entire inheritance chain below it? Why can I seal a parent class but allow a non-sealed child, which then opens the hierarchy to unlimited extensions?

This design decision reflects a fundamental tension between control and flexibility. Understanding why sealed classes work this way requires looking at a real-world example: the Java Collections Framework.

The Collections Framework Problem

Imagine if Java sealed the Collection interface like this:

// Hypothetical sealed Collection (don't do this!)
public sealed interface Collection<E>
    permits List, Set, Queue {
    // ...
}

public sealed interface List<E> extends Collection<E>
    permits ArrayList, LinkedList, Vector {
    // ...
}

public final class ArrayList<E> implements List<E> {
    // ...
}

This looks reasonable: Collection controls its direct children (List, Set, Queue), and List controls its implementations (ArrayList, LinkedList). But now consider what this breaks:

// User code - This will NOT compile!
public class MyCustomArrayList<E> extends ArrayList<E> {
    // Add custom caching behavior
    @Override
    public E get(int index) {
        // ... custom logic ...
    }
}

Compilation error: MyCustomArrayList is not in the permits clause of List. Your entire ecosystem of third-party libraries breaks overnight—any code that extends ArrayList, LinkedList, HashMap, etc., becomes invalid.

Why This Matters

The Java ecosystem thrives on extensibility. Libraries like Guava, Eclipse Collections, and Apache Commons provide custom collection implementations that extend standard classes. If sealed classes controlled the entire hierarchy, you'd need permission from the Collections framework maintainers every time you wanted a custom implementation.

The sealed classes design recognizes this: each level in the hierarchy independently decides what it permits. This is the key insight.

Pattern 1: Full Control Chain (sealed → sealed → final)

When you want maximal control over the entire hierarchy, use sealed at each level:

// Top level: sealed, permits intermediate levels
public sealed abstract class Animal
    permits Mammal, Bird {
    public abstract String sound();
}

// Middle level: sealed, permits leaf implementations
public sealed abstract class Mammal extends Animal
    permits Dog, Cat {
    // ...
}

// Leaf level: final, no extensions
public final class Dog extends Mammal {
    @Override
    public String sound() { return "woof"; }
}

// Attempting to extend final fails
public class ServiceDog extends Dog { } // ❌ Compile error: Dog is final

What's happening here:

• Animal controls who can extend it (only Mammal and Bird)

• Mammal independently controls its children (only Dog and Cat)

• Dog is final, so the chain ends

• Each level is a checkpoint that can't be bypassed

This creates a closed hierarchy where the compiler knows every possible type at each level.

Pattern 2: Breaking the Chain (sealed → non-sealed → open)

When you want to control the top level but allow flexibility below, use non-sealed as an escape hatch:

// Top level: sealed, permits both sealed and non-sealed children
public sealed abstract class DatabaseConnection
    permits ManagedConnection, UserConnection {
    public abstract void execute(String query);
}

// Branch 1: sealed - tight control
public sealed abstract class ManagedConnection extends DatabaseConnection
    permits PooledConnection, CachedConnection {
    // Framework-controlled connections
}

public final class PooledConnection extends ManagedConnection {
    @Override
    public void execute(String query) { /* ... */ }
}

// Branch 2: non-sealed - BREAKS THE SEAL
public non-sealed abstract class UserConnection extends DatabaseConnection {
    // Users can extend this freely!
}

// Now users can create unlimited custom connections
public class CustomDatabaseConnection extends UserConnection {
    @Override
    public void execute(String query) { /* custom logic */ }
}

public class LoggingConnection extends UserConnection {
    @Override
    public void execute(String query) { /* log then delegate */ }
}

public class MetricsConnection extends UserConnection {
    @Override
    public void execute(String query) { /* record metrics */ }
}

Why this pattern exists:

Non-sealed is the middle ground between:

• sealed: Forces all implementations to be in your control (too restrictive for libraries)

• open: No control at all (doesn't solve the problems sealed classes address)

With non-sealed, you get the best of both worlds:

• The top-level DatabaseConnection remains sealed—you control what kinds of connections exist at the highest level

• UserConnection explicitly breaks the seal—users understand they're entering an open-extension zone

• Users can create unlimited custom implementations without modifying your code or getting compiler errors

This is exactly how the actual Collections Framework would be designed if it were sealed today.

Pattern 3: Final Leaf Nodes (sealed → final)

When you want to prevent further extension, use final:

public sealed abstract class PaymentMethod
    permits CardPayment, BankTransfer, CryptoCurrency {
    public abstract void process(double amount);
}

// Branch 1: final - impossible to extend
public final class CardPayment extends PaymentMethod {
    @Override
    public void process(double amount) {
        // PCI compliance: no extensions allowed for security
    }
}

// Branch 2: sealed - further subdivision possible
public sealed abstract class BankTransfer extends PaymentMethod
    permits DomesticTransfer, InternationalTransfer {
    // ...
}

// Attempting to extend final fails
public class EnhancedCardPayment extends CardPayment { }
// ❌ Compile error: CardPayment is final

Why use final here:

Some types are architectural endpoints. CardPayment handles PCI-compliant operations—you don't want subclasses that might inadvertently bypass security checks. By making it final, you make this intention explicit and prevent dangerous extensions.

Why Not Just Seal Everything?

If you sealed every level all the way down, you'd recreate the Collections Framework problem:

// Too restrictive!
sealed interface Collection<E> permits List, Set, Queue { }
sealed interface List<E> extends Collection<E> permits ArrayList, LinkedList { }
final class ArrayList<E> implements List<E> { }

// Users can't extend ArrayList anymore - ecosystem breaks

Instead, the actual design would be:

// Practical design
sealed interface Collection<E> permits List, Set, Queue { }
non-sealed interface List<E> extends Collection<E> { }
class ArrayList<E> implements List<E> { }

// Users can still extend ArrayList - ecosystem preserved

By using non-sealed strategically, you:

• Establish intent at the top level (what types of collections exist?)

• Allow flexibility where it matters (users can extend implementations)

• Prevent accidents (exhaustive switches over the four main collection types)

• Document constraints (some sealed branches forbid extensions, others allow them)

Sealed Interfaces

Interfaces work identically to classes:

public sealed interface Transport
    permits Car, Bicycle {
    void move();
}

// Records are implicitly final
public record Car(String model, int passengers) implements Transport {
    @Override
    public void move() { System.out.println("Driving " + model); }
}

// Enum values are implicitly final
public enum Bicycle implements Transport {
    MOUNTAIN, ROAD, HYBRID;

    @Override
    public void move() { System.out.println("Pedaling " + this); }
}

Reflection API

Java 17 adds reflection methods for sealed types:

Class<?> shapeClass = Shape.class;

// Check if sealed
boolean isSealed = shapeClass.isSealed(); // true

// Get permitted subclasses
Class<?>[] permitted = shapeClass.getPermittedSubclasses();
// Returns: [Circle.class, Rectangle.class, Triangle.class]

Practical Examples

Example 1: Basic Sealed Classes with Shape Hierarchy

Sealed classes provide controlled inheritance hierarchies where the compiler knows all possible subtypes, enabling exhaustive pattern matching.

// Sealed parent class
public sealed abstract class Shape
    permits Circle, Rectangle, Triangle {
    public abstract double area();
    public abstract String describe();
}

// Final implementations
public final class Circle extends Shape {
    private final double radius;

    public Circle(double radius) {
        if (radius <= 0) {
            throw new IllegalArgumentException("Radius must be positive");
        }
        this.radius = radius;
    }

    @Override
    public double area() {
        return Math.PI * radius * radius;
    }

    @Override
    public String describe() {
        return String.format("Circle[radius=%.2f, area=%.2f]", radius, area());
    }

    public double radius() { return radius; }
}

public final class Rectangle extends Shape {
    private final double width;
    private final double height;

    public Rectangle(double width, double height) {
        if (width <= 0 || height <= 0) {
            throw new IllegalArgumentException("Dimensions must be positive");
        }
        this.width = width;
        this.height = height;
    }

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

    @Override
    public String describe() {
        return String.format("Rectangle[width=%.2f, height=%.2f, area=%.2f]",
            width, height, area());
    }

    public double width() { return width; }
    public double height() { return height; }
}

public final class Triangle extends Shape {
    private final double base;
    private final double height;

    public Triangle(double base, double height) {
        if (base <= 0 || height <= 0) {
            throw new IllegalArgumentException("Dimensions must be positive");
        }
        this.base = base;
        this.height = height;
    }

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

    @Override
    public String describe() {
        return String.format("Triangle[base=%.2f, height=%.2f, area=%.2f]",
            base, height, area());
    }

    public double base() { return base; }
    public double height() { return height; }
}

public class BasicSealedExample {
    public static void main(String[] args) {
        var shapes = List.of(
            new Circle(5.0),
            new Rectangle(4.0, 6.0),
            new Triangle(3.0, 8.0)
        );

        System.out.println("=== Shape Demonstrations ===");
        for (var shape : shapes) {
            System.out.println(shape.describe());
        }

        // Type-specific operations
        System.out.println("\n=== Type-Specific Access ===");
        var circle = new Circle(10.0);
        System.out.println("Circle radius: " + circle.radius());

        var rect = new Rectangle(5.0, 3.0);
        System.out.println("Rectangle dimensions: " + rect.width() + " x " + rect.height());

        // Reflection - discovering sealed hierarchy
        System.out.println("\n=== Reflection ===");
        System.out.println("Shape is sealed: " + Shape.class.isSealed());
        System.out.print("Permitted subclasses: ");
        for (var permitted : Shape.class.getPermittedSubclasses()) {
            System.out.print(permitted.getSimpleName() + " ");
        }
        System.out.println();
    }
}

// Unit tests

@Test
@DisplayName("Should calculate circle area correctly")
void shouldCalculateCircleAreaCorrectly() {
    var circle = new Circle(5.0);

    assertEquals(Math.PI * 25, circle.area(), 0.001);
    assertEquals(5.0, circle.radius());
}

@Test
@DisplayName("Should calculate rectangle area correctly")
void shouldCalculateRectangleAreaCorrectly() {
    var rectangle = new Rectangle(4.0, 6.0);

    assertEquals(24.0, rectangle.area(), 0.001);
    assertEquals(4.0, rectangle.width());
    assertEquals(6.0, rectangle.height());
}

@Test
@DisplayName("Should calculate triangle area correctly")
void shouldCalculateTriangleAreaCorrectly() {
    var triangle = new Triangle(3.0, 8.0);

    assertEquals(12.0, triangle.area(), 0.001);
    assertEquals(3.0, triangle.base());
    assertEquals(8.0, triangle.height());
}

@Test
@DisplayName("Should verify Shape is sealed with correct permitted subclasses")
void shouldVerifyShapeIsSealedWithCorrectPermittedSubclasses() {
    assertTrue(Shape.class.isSealed());

    var permitted = Shape.class.getPermittedSubclasses();
    assertEquals(3, permitted.length);

    var permittedNames = Arrays.stream(permitted)
        .map(Class::getSimpleName)
        .collect(Collectors.toSet());

    assertTrue(permittedNames.contains("Circle"));
    assertTrue(permittedNames.contains("Rectangle"));
    assertTrue(permittedNames.contains("Triangle"));
}

@Test
@DisplayName("Should throw exception for invalid dimensions")
void shouldThrowExceptionForInvalidDimensions() {
    assertThrows(IllegalArgumentException.class, () -> new Circle(0));
    assertThrows(IllegalArgumentException.class, () -> new Circle(-5));
    assertThrows(IllegalArgumentException.class, () -> new Rectangle(0, 5));
    assertThrows(IllegalArgumentException.class, () -> new Triangle(5, -3));
}

Output:

=== Shape Demonstrations ===
Circle[radius=5.00, area=78.54]
Rectangle[width=4.00, height=6.00, area=24.00]
Triangle[base=3.00, height=8.00, area=12.00]

=== Type-Specific Access ===
Circle radius: 10.0
Rectangle dimensions: 5.0 x 3.0

=== Reflection ===
Shape is sealed: true
Permitted subclasses: Circle Rectangle Triangle

Key Insight: Sealed classes give you controlled inheritance hierarchies. Unlike final (no extensions) or open classes (unlimited extensions), sealed classes let you explicitly list permitted subtypes. The compiler enforces this at compile-time, preventing unauthorized extensions.

Example 2: Sealed Interfaces with Records

Sealed interfaces restrict implementations to explicit types with exhaustive checking.

// Sealed interface
public sealed interface Payment
    permits CreditCard, DebitCard, Cash, BankTransfer {
    double amount();
    String description();
}

// Records as implementations (implicitly final)
public record CreditCard(
    String cardNumber,
    String cardHolder,
    double amount,
    String merchantId
) implements Payment {

    public CreditCard {
        if (amount <= 0) {
            throw new IllegalArgumentException("Amount must be positive");
        }
        if (cardNumber == null || cardNumber.length() != 16) {
            throw new IllegalArgumentException("Invalid card number");
        }
    }

    @Override
    public String description() {
        return String.format("Credit Card payment: $%.2f (Card ending %s)",
            amount, cardNumber.substring(12));
    }
}

public record DebitCard(
    String cardNumber,
    String cardHolder,
    double amount,
    String pin
) implements Payment {

    public DebitCard {
        if (amount <= 0) {
            throw new IllegalArgumentException("Amount must be positive");
        }
    }

    @Override
    public String description() {
        return String.format("Debit Card payment: $%.2f (Card ending %s)",
            amount, cardNumber.substring(12));
    }
}

public record Cash(
    double amount,
    String currency
) implements Payment {

    public Cash {
        if (amount <= 0) {
            throw new IllegalArgumentException("Amount must be positive");
        }
    }

    @Override
    public String description() {
        return String.format("Cash payment: %.2f %s", amount, currency);
    }
}

public record BankTransfer(
    String fromAccount,
    String toAccount,
    double amount,
    String reference
) implements Payment {

    public BankTransfer {
        if (amount <= 0) {
            throw new IllegalArgumentException("Amount must be positive");
        }
    }

    @Override
    public String description() {
        return String.format("Bank Transfer: $%.2f (Ref: %s)", amount, reference);
    }
}

public class SealedInterfaceExample {
    public static void main(String[] args) {
        var payments = List.of(
            new CreditCard("1234567890123456", "John Doe", 150.00, "MERCHANT_001"),
            new DebitCard("9876543210987654", "Jane Smith", 75.50, "1234"),
            new Cash(50.00, "USD"),
            new BankTransfer("ACC001", "ACC002", 1000.00, "INV-2024-001")
        );

        System.out.println("=== Payment Processing ===");
        double total = 0.0;
        for (var payment : payments) {
            System.out.println(payment.description());
            total += payment.amount();
        }

        System.out.printf("\nTotal processed: $%.2f\n", total);

        // Type-specific access
        System.out.println("\n=== Type-Specific Operations ===");
        var creditCard = new CreditCard("1111222233334444", "Alice Brown", 299.99, "SHOP_123");
        System.out.println("Card holder: " + creditCard.cardHolder());
        System.out.println("Merchant ID: " + creditCard.merchantId());

        // Reflection
        System.out.println("\n=== Interface Reflection ===");
        System.out.println("Payment is sealed: " + Payment.class.isSealed());
        System.out.print("Permitted implementations: ");
        for (var permitted : Payment.class.getPermittedSubclasses()) {
            System.out.print(permitted.getSimpleName() + " ");
        }
        System.out.println();
    }
}

// Unit tests

@Test
@DisplayName("Should create CreditCard payment with valid data")
void shouldCreateCreditCardPaymentWithValidData() {
    var payment = new CreditCard("1234567890123456", "John Doe", 150.00, "MERCHANT_001");

    assertEquals(150.00, payment.amount());
    assertEquals("John Doe", payment.cardHolder());
    assertEquals("MERCHANT_001", payment.merchantId());
    assertTrue(payment.description().contains("$150.00"));
}

@Test
@DisplayName("Should create DebitCard payment with valid data")
void shouldCreateDebitCardPaymentWithValidData() {
    var payment = new DebitCard("9876543210987654", "Jane Smith", 75.50, "1234");

    assertEquals(75.50, payment.amount());
    assertEquals("Jane Smith", payment.cardHolder());
}

@Test
@DisplayName("Should create Cash payment with currency")
void shouldCreateCashPaymentWithCurrency() {
    var payment = new Cash(50.00, "USD");

    assertEquals(50.00, payment.amount());
    assertEquals("USD", payment.currency());
    assertTrue(payment.description().contains("USD"));
}

@Test
@DisplayName("Should create BankTransfer with reference number")
void shouldCreateBankTransferWithReferenceNumber() {
    var payment = new BankTransfer("ACC001", "ACC002", 1000.00, "INV-2024-001");

    assertEquals(1000.00, payment.amount());
    assertEquals("INV-2024-001", payment.reference());
    assertTrue(payment.description().contains("INV-2024-001"));
}

@Test
@DisplayName("Should verify Payment interface is sealed")
void shouldVerifyPaymentInterfaceIsSealed() {
    assertTrue(Payment.class.isSealed());

    var permitted = Payment.class.getPermittedSubclasses();
    assertEquals(4, permitted.length);
}

@Test
@DisplayName("Should throw exception for invalid payment amounts")
void shouldThrowExceptionForInvalidPaymentAmounts() {
    assertThrows(IllegalArgumentException.class,
        () -> new CreditCard("1234567890123456", "John", 0, "M001"));
    assertThrows(IllegalArgumentException.class,
        () -> new Cash(-10, "USD"));
}

@Test
@DisplayName("Should throw exception for invalid card number")
void shouldThrowExceptionForInvalidCardNumber() {
    assertThrows(IllegalArgumentException.class,
        () -> new CreditCard("123", "John", 100, "M001"));
}

Output:

=== Payment Processing ===
Credit Card payment: $150.00 (Card ending 3456)
Debit Card payment: $75.50 (Card ending 7654)
Cash payment: 50.00 USD
Bank Transfer: $1000.00 (Ref: INV-2024-001)

Total processed: $1275.50

=== Type-Specific Operations ===
Card holder: Alice Brown
Merchant ID: SHOP_123

=== Interface Reflection ===
Payment is sealed: true
Permitted implementations: CreditCard DebitCard Cash BankTransfer

Key Insight: Records are implicitly final, making them suitable for sealed interface implementations. The compiler knows all possible implementations.

Example 3: Multi-level Sealed Hierarchies

Sealed classes can form multi-level hierarchies where intermediate levels are also sealed, creating tree-like type structures.

// Top-level sealed class
public sealed abstract class Vehicle
    permits MotorVehicle, Bicycle {
    private final String brand;

    protected Vehicle(String brand) {
        this.brand = brand;
    }

    public String brand() { return brand; }
    public abstract String describe();
}

// Second-level sealed class
public sealed abstract class MotorVehicle extends Vehicle
    permits Car, Motorcycle {
    private final int engineCC;

    protected MotorVehicle(String brand, int engineCC) {
        super(brand);
        this.engineCC = engineCC;
    }

    public int engineCC() { return engineCC; }
}

// Final implementations at third level
public final class Car extends MotorVehicle {
    private final int doors;
    private final boolean isElectric;

    public Car(String brand, int engineCC, int doors, boolean isElectric) {
        super(brand, engineCC);
        this.doors = doors;
        this.isElectric = isElectric;
    }

    public int doors() { return doors; }
    public boolean isElectric() { return isElectric; }

    @Override
    public String describe() {
        return String.format("Car[brand=%s, engineCC=%d, doors=%d, electric=%b]",
            brand(), engineCC(), doors, isElectric);
    }
}

public final class Motorcycle extends MotorVehicle {
    private final boolean hasSidecar;

    public Motorcycle(String brand, int engineCC, boolean hasSidecar) {
        super(brand, engineCC);
        this.hasSidecar = hasSidecar;
    }

    public boolean hasSidecar() { return hasSidecar; }

    @Override
    public String describe() {
        return String.format("Motorcycle[brand=%s, engineCC=%d, hasSidecar=%b]",
            brand(), engineCC(), hasSidecar);
    }
}

// Final implementation at second level
public final class Bicycle extends Vehicle {
    private final int gears;
    private final String type; // "mountain", "road", "hybrid"

    public Bicycle(String brand, int gears, String type) {
        super(brand);
        this.gears = gears;
        this.type = type;
    }

    public int gears() { return gears; }
    public String type() { return type; }

    @Override
    public String describe() {
        return String.format("Bicycle[brand=%s, gears=%d, type=%s]",
            brand(), gears, type);
    }
}

public class MultiLevelSealedExample {
    public static void main(String[] args) {
        var vehicles = List.of(
            new Car("Tesla", 0, 4, true),
            new Car("BMW", 3000, 2, false),
            new Motorcycle("Harley-Davidson", 1200, false),
            new Motorcycle("Ural", 750, true),
            new Bicycle("Trek", 21, "mountain"),
            new Bicycle("Specialized", 18, "road")
        );

        System.out.println("=== Vehicle Inventory ===");
        for (var vehicle : vehicles) {
            System.out.println(vehicle.describe());
        }

        // Categorize by type
        System.out.println("\n=== Categorization ===");
        long motorVehicles = vehicles.stream()
            .filter(v -> v instanceof MotorVehicle)
            .count();
        long bicycles = vehicles.stream()
            .filter(v -> v instanceof Bicycle)
            .count();

        System.out.println("Motor Vehicles: " + motorVehicles);
        System.out.println("Bicycles: " + bicycles);

        // Type-specific operations
        System.out.println("\n=== Motor Vehicle Details ===");
        var car = new Car("Audi", 2000, 4, false);
        System.out.println("Car doors: " + car.doors());
        System.out.println("Engine CC: " + car.engineCC());

        // Hierarchy reflection
        System.out.println("\n=== Sealed Hierarchy ===");
        System.out.println("Vehicle is sealed: " + Vehicle.class.isSealed());
        System.out.println("MotorVehicle is sealed: " + MotorVehicle.class.isSealed());
        System.out.println("Car is final: " + java.lang.reflect.Modifier.isFinal(Car.class.getModifiers()));
    }
}

// Unit tests

@Test
@DisplayName("Should create Car with correct properties")
void shouldCreateCarWithCorrectProperties() {
    var car = new Car("Tesla", 0, 4, true);

    assertEquals("Tesla", car.brand());
    assertEquals(0, car.engineCC());
    assertEquals(4, car.doors());
    assertTrue(car.isElectric());
}

@Test
@DisplayName("Should create Motorcycle with correct properties")
void shouldCreateMotorcycleWithCorrectProperties() {
    var motorcycle = new Motorcycle("Harley-Davidson", 1200, false);

    assertEquals("Harley-Davidson", motorcycle.brand());
    assertEquals(1200, motorcycle.engineCC());
    assertFalse(motorcycle.hasSidecar());
}

@Test
@DisplayName("Should create Bicycle with correct properties")
void shouldCreateBicycleWithCorrectProperties() {
    var bicycle = new Bicycle("Trek", 21, "mountain");

    assertEquals("Trek", bicycle.brand());
    assertEquals(21, bicycle.gears());
    assertEquals("mountain", bicycle.type());
}

@Test
@DisplayName("Should verify multi-level sealed hierarchy")
void shouldVerifyMultiLevelSealedHierarchy() {
    // Top level is sealed
    assertTrue(Vehicle.class.isSealed());
    var vehiclePermitted = Vehicle.class.getPermittedSubclasses();
    assertEquals(2, vehiclePermitted.length);

    // Second level is sealed
    assertTrue(MotorVehicle.class.isSealed());
    var motorPermitted = MotorVehicle.class.getPermittedSubclasses();
    assertEquals(2, motorPermitted.length);

    // Leaf classes are final
    assertTrue(java.lang.reflect.Modifier.isFinal(Car.class.getModifiers()));
    assertTrue(java.lang.reflect.Modifier.isFinal(Motorcycle.class.getModifiers()));
    assertTrue(java.lang.reflect.Modifier.isFinal(Bicycle.class.getModifiers()));
}

@Test
@DisplayName("Should correctly identify MotorVehicle instances")
void shouldCorrectlyIdentifyMotorVehicleInstances() {
    var car = new Car("BMW", 3000, 4, false);
    var motorcycle = new Motorcycle("Yamaha", 600, false);
    var bicycle = new Bicycle("Giant", 18, "road");

    assertTrue(car instanceof MotorVehicle);
    assertTrue(motorcycle instanceof MotorVehicle);
    assertFalse(bicycle instanceof MotorVehicle);
}

Output:

=== Vehicle Inventory ===
Car[brand=Tesla, engineCC=0, doors=4, electric=true]
Car[brand=BMW, engineCC=3000, doors=2, electric=false]
Motorcycle[brand=Harley-Davidson, engineCC=1200, hasSidecar=false]
Motorcycle[brand=Ural, engineCC=750, hasSidecar=true]
Bicycle[brand=Trek, gears=21, type=mountain]
Bicycle[brand=Specialized, gears=18, type=road]

=== Categorization ===
Motor Vehicles: 4
Bicycles: 2

=== Motor Vehicle Details ===
Car doors: 4
Engine CC: 2000

=== Sealed Hierarchy ===
Vehicle is sealed: true
MotorVehicle is sealed: true
Car is final: true

Key Insight: Multi-level sealed hierarchies let you model complex domain structures with controlled inheritance at each level. The top-level Vehicle permits two branches: MotorVehicle (which is itself sealed) and Bicycle (which is final). This creates a tree structure where each node decides its children's extension policy.

Example 4: Exhaustive Switch with Sealed Types

Sealed types enable exhaustive switch expressions. The compiler verifies all possible subtypes are handled without a default case.

// Sealed JSON value hierarchy
public sealed interface JSONValue
    permits JSONObject, JSONArray, JSONString, JSONNumber, JSONBoolean, JSONNull {
    String toJson();
}

public record JSONObject(java.util.Map<String, JSONValue> values) implements JSONValue {
    @Override
    public String toJson() {
        return values.entrySet().stream()
            .map(e -> "\"" + e.getKey() + "\":" + e.getValue().toJson())
            .collect(java.util.stream.Collectors.joining(",", "{", "}"));
    }
}

public record JSONArray(java.util.List<JSONValue> values) implements JSONValue {
    @Override
    public String toJson() {
        return values.stream()
            .map(JSONValue::toJson)
            .collect(java.util.stream.Collectors.joining(",", "[", "]"));
    }
}

public record JSONString(String value) implements JSONValue {
    @Override
    public String toJson() {
        return "\"" + value.replace("\"", "\\\"") + "\"";
    }
}

public record JSONNumber(double value) implements JSONValue {
    @Override
    public String toJson() {
        return String.valueOf(value);
    }
}

public record JSONBoolean(boolean value) implements JSONValue {
    @Override
    public String toJson() {
        return String.valueOf(value);
    }
}

public enum JSONNull implements JSONValue {
    INSTANCE;

    @Override
    public String toJson() {
        return "null";
    }
}

public class ExhaustiveSwitchExample {
    // Exhaustive switch - no default needed!
    public static String describeType(JSONValue value) {
        return switch (value) {
            case JSONObject obj -> "object with " + obj.values().size() + " properties";
            case JSONArray arr -> "array with " + arr.values().size() + " elements";
            case JSONString str -> "string: \"" + str.value() + "\"";
            case JSONNumber num -> "number: " + num.value();
            case JSONBoolean bool -> "boolean: " + bool.value();
            case JSONNull ignored -> "null value";
            // No default case needed - compiler knows all cases are covered!
        };
    }

    public static int estimateSize(JSONValue value) {
        return switch (value) {
            case JSONObject obj -> obj.values().values().stream()
                .mapToInt(ExhaustiveSwitchExample::estimateSize)
                .sum() + 2; // {} brackets
            case JSONArray arr -> arr.values().stream()
                .mapToInt(ExhaustiveSwitchExample::estimateSize)
                .sum() + 2; // [] brackets
            case JSONString str -> str.value().length() + 2; // quotes
            case JSONNumber num -> String.valueOf(num.value()).length();
            case JSONBoolean bool -> String.valueOf(bool.value()).length();
            case JSONNull ignored -> 4; // "null"
        };
    }

    public static void main(String[] args) {
        // Build sample JSON structure
        var jsonData = new JSONObject(java.util.Map.of(
            "name", new JSONString("John Doe"),
            "age", new JSONNumber(30),
            "active", new JSONBoolean(true),
            "address", JSONNull.INSTANCE,
            "hobbies", new JSONArray(java.util.List.of(
                new JSONString("reading"),
                new JSONString("coding"),
                new JSONString("gaming")
            ))
        ));

        System.out.println("=== JSON Structure ===");
        System.out.println(jsonData.toJson());

        System.out.println("\n=== Type Descriptions (Exhaustive Switch) ===");
        jsonData.values().forEach((key, value) -> {
            System.out.println(key + " -> " + describeType(value));
        });

        System.out.println("\n=== Size Estimation ===");
        System.out.println("Estimated size: " + estimateSize(jsonData) + " characters");
        System.out.println("Actual size: " + jsonData.toJson().length() + " characters");

        // Demonstrate exhaustiveness
        System.out.println("\n=== Exhaustive Pattern Matching ===");
        var values = java.util.List.of(
            new JSONString("test"),
            new JSONNumber(42),
            new JSONBoolean(false),
            JSONNull.INSTANCE
        );

        for (var value : values) {
            System.out.println(describeType(value));
        }
    }
}

// Unit tests

@Test
@DisplayName("Should create JSONString and convert to JSON")
void shouldCreateJSONStringAndConvertToJSON() {
    var json = new JSONString("hello");

    assertEquals("\"hello\"", json.toJson());
}

@Test
@DisplayName("Should create JSONNumber and convert to JSON")
void shouldCreateJSONNumberAndConvertToJSON() {
    var json = new JSONNumber(42.5);

    assertEquals("42.5", json.toJson());
}

@Test
@DisplayName("Should create JSONBoolean and convert to JSON")
void shouldCreateJSONBooleanAndConvertToJSON() {
    var jsonTrue = new JSONBoolean(true);
    var jsonFalse = new JSONBoolean(false);

    assertEquals("true", jsonTrue.toJson());
    assertEquals("false", jsonFalse.toJson());
}

@Test
@DisplayName("Should create JSONNull and convert to JSON")
void shouldCreateJSONNullAndConvertToJSON() {
    var json = JSONNull.INSTANCE;

    assertEquals("null", json.toJson());
}

@Test
@DisplayName("Should create JSONArray and convert to JSON")
void shouldCreateJSONArrayAndConvertToJSON() {
    var json = new JSONArray(java.util.List.of(
        new JSONNumber(1),
        new JSONNumber(2),
        new JSONNumber(3)
    ));

    assertEquals("[1.0,2.0,3.0]", json.toJson());
}

@Test
@DisplayName("Should describe JSON types using exhaustive switch")
void shouldDescribeJSONTypesUsingExhaustiveSwitch() {
    assertEquals("string: \"test\"",
        ExhaustiveSwitchExample.describeType(new JSONString("test")));
    assertEquals("number: 42.0",
        ExhaustiveSwitchExample.describeType(new JSONNumber(42)));
    assertEquals("boolean: true",
        ExhaustiveSwitchExample.describeType(new JSONBoolean(true)));
    assertEquals("null value",
        ExhaustiveSwitchExample.describeType(JSONNull.INSTANCE));
}

@Test
@DisplayName("Should estimate JSON size correctly")
void shouldEstimateJSONSizeCorrectly() {
    assertEquals(6, ExhaustiveSwitchExample.estimateSize(new JSONString("test"))); // "test"
    assertEquals(4, ExhaustiveSwitchExample.estimateSize(JSONNull.INSTANCE)); // null
}

@Test
@DisplayName("Should verify JSONValue interface is sealed")
void shouldVerifyJSONValueInterfaceIsSealed() {
    assertTrue(JSONValue.class.isSealed());
    assertEquals(6, JSONValue.class.getPermittedSubclasses().length);
}

Output:

=== JSON Structure ===
{"hobbies":["reading","coding","gaming"],"address":null,"name":"John Doe","active":true,"age":30.0}

=== Type Descriptions (Exhaustive Switch) ===
hobbies -> array with 3 elements
address -> null value
name -> string: "John Doe"
active -> boolean: true
age -> number: 30.0

=== Size Estimation ===
Estimated size: 88 characters
Actual size: 94 characters

=== Exhaustive Pattern Matching ===
string: "test"
number: 42.0
boolean: false
null value

Key Insight: The compiler enforces exhaustiveness in switches. Adding a new type without updating all switches causes compilation errors.

Example 5: The non-sealed Modifier

The non-sealed modifier breaks the seal, allowing unrestricted subclassing from that point onward in the hierarchy.

// Sealed base class
public sealed abstract class Animal
    permits Mammal, Bird, Fish {
    private final String name;

    protected Animal(String name) {
        this.name = name;
    }

    public String name() { return name; }
    public abstract String sound();
}

// Sealed intermediate class - controlled hierarchy continues
public sealed abstract class Mammal extends Animal
    permits Dog, Cat, Pet {
    protected Mammal(String name) {
        super(name);
    }
}

// Non-sealed class - breaks the seal!
public non-sealed abstract class Pet extends Mammal {
    private String owner;

    protected Pet(String name, String owner) {
        super(name);
        this.owner = owner;
    }

    public String owner() { return owner; }
    public void setOwner(String owner) { this.owner = owner; }
}

// Now anyone can extend Pet - the seal is broken
public class Hamster extends Pet {
    private final String color;

    public Hamster(String name, String owner, String color) {
        super(name, owner);
        this.color = color;
    }

    public String color() { return color; }

    @Override
    public String sound() {
        return "squeak squeak";
    }
}

public class GuineaPig extends Pet {
    private final boolean isLongHaired;

    public GuineaPig(String name, String owner, boolean isLongHaired) {
        super(name, owner);
        this.isLongHaired = isLongHaired;
    }

    public boolean isLongHaired() { return isLongHaired; }

    @Override
    public String sound() {
        return "wheek wheek";
    }
}

// Final implementations in sealed hierarchy
public final class Dog extends Mammal {
    private final String breed;

    public Dog(String name, String breed) {
        super(name);
        this.breed = breed;
    }

    public String breed() { return breed; }

    @Override
    public String sound() {
        return "woof";
    }
}

public final class Cat extends Mammal {
    private final boolean isIndoor;

    public Cat(String name, boolean isIndoor) {
        super(name);
        this.isIndoor = isIndoor;
    }

    public boolean isIndoor() { return isIndoor; }

    @Override
    public String sound() {
        return "meow";
    }
}

// Other sealed branches
public final class Bird extends Animal {
    private final double wingspan;

    public Bird(String name, double wingspan) {
        super(name);
        this.wingspan = wingspan;
    }

    public double wingspan() { return wingspan; }

    @Override
    public String sound() {
        return "chirp";
    }
}

public final class Fish extends Animal {
    private final String waterType;

    public Fish(String name, String waterType) {
        super(name);
        this.waterType = waterType;
    }

    public String waterType() { return waterType; }

    @Override
    public String sound() {
        return "blub";
    }
}

public class NonSealedExample {
    public static void main(String[] args) {
        var animals = java.util.List.of(
            new Dog("Buddy", "Golden Retriever"),
            new Cat("Whiskers", true),
            new Bird("Tweety", 15.5),
            new Fish("Nemo", "saltwater"),
            new Hamster("Fluffy", "Alice", "brown"),
            new GuineaPig("Patches", "Bob", true)
        );

        System.out.println("=== Animal Sounds ===");
        for (var animal : animals) {
            System.out.println(animal.name() + " says: " + animal.sound());
        }

        // Demonstrate non-sealed hierarchy
        System.out.println("\n=== Pet Hierarchy (non-sealed) ===");
        var pets = animals.stream()
            .filter(a -> a instanceof Pet)
            .map(a -> (Pet) a)
            .toList();

        for (var pet : pets) {
            System.out.println(pet.name() + " belongs to " + pet.owner());
        }

        // Reflection on sealed hierarchy
        System.out.println("\n=== Sealed Hierarchy Analysis ===");
        System.out.println("Animal is sealed: " + Animal.class.isSealed());
        System.out.println("Mammal is sealed: " + Mammal.class.isSealed());
        System.out.println("Pet is sealed: " + Pet.class.isSealed()); // false!

        System.out.println("\nMammal permits: ");
        for (var permitted : Mammal.class.getPermittedSubclasses()) {
            System.out.println("  - " + permitted.getSimpleName());
        }
    }
}

// Unit tests

@Test
@DisplayName("Should create Dog with breed information")
void shouldCreateDogWithBreedInformation() {
    var dog = new Dog("Buddy", "Golden Retriever");

    assertEquals("Buddy", dog.name());
    assertEquals("Golden Retriever", dog.breed());
    assertEquals("woof", dog.sound());
}

@Test
@DisplayName("Should create Cat with indoor status")
void shouldCreateCatWithIndoorStatus() {
    var cat = new Cat("Whiskers", true);

    assertEquals("Whiskers", cat.name());
    assertTrue(cat.isIndoor());
    assertEquals("meow", cat.sound());
}

@Test
@DisplayName("Should create Hamster as Pet subclass")
void shouldCreateHamsterAsPetSubclass() {
    var hamster = new Hamster("Fluffy", "Alice", "brown");

    assertEquals("Fluffy", hamster.name());
    assertEquals("Alice", hamster.owner());
    assertEquals("brown", hamster.color());
    assertEquals("squeak squeak", hamster.sound());
}

@Test
@DisplayName("Should create GuineaPig as Pet subclass")
void shouldCreateGuineaPigAsPetSubclass() {
    var guineaPig = new GuineaPig("Patches", "Bob", true);

    assertEquals("Patches", guineaPig.name());
    assertEquals("Bob", guineaPig.owner());
    assertTrue(guineaPig.isLongHaired());
}

@Test
@DisplayName("Should verify Animal and Mammal are sealed but Pet is not")
void shouldVerifyAnimalAndMammalAreSealedButPetIsNot() {
    assertTrue(Animal.class.isSealed());
    assertTrue(Mammal.class.isSealed());
    assertFalse(Pet.class.isSealed()); // non-sealed!
}

@Test
@DisplayName("Should allow unlimited extensions of non-sealed Pet class")
void shouldAllowUnlimitedExtensionsOfNonSealedPetClass() {
    // Hamster and GuineaPig can extend Pet without being in permits clause
    assertTrue(Hamster.class.getSuperclass().equals(Pet.class));
    assertTrue(GuineaPig.class.getSuperclass().equals(Pet.class));
}

@Test
@DisplayName("Should update Pet owner")
void shouldUpdatePetOwner() {
    var hamster = new Hamster("Fluffy", "Alice", "brown");
    assertEquals("Alice", hamster.owner());

    hamster.setOwner("Bob");
    assertEquals("Bob", hamster.owner());
}

Output:

=== Animal Sounds ===
Buddy says: woof
Whiskers says: meow
Tweety says: chirp
Nemo says: blub
Fluffy says: squeak squeak
Patches says: wheek wheek

=== Pet Hierarchy (non-sealed) ===
Fluffy belongs to Alice
Patches belongs to Bob

=== Sealed Hierarchy Analysis ===
Animal is sealed: true
Mammal is sealed: true
Pet is sealed: false

Mammal permits:
  - Dog
  - Cat
  - Pet

Key Insight: The non-sealed modifier strategically breaks the seal at a specific point in the hierarchy. Animal and Mammal remain sealed with controlled inheritance, but Pet allows unlimited extensions. This is useful when you want tight control over core abstractions but flexibility in specific branches—like allowing plugin developers to create custom pet types while keeping the core Animal hierarchy closed.

Best Practices

When to Use Sealed Classes

Use sealed classes when:

1. Domain modeling with closed sets - Payment types, order statuses, geometric shapes, or any domain concept with a fixed set of variants

2. Exhaustive pattern matching required - When you need the compiler to verify you've handled all cases

3. API stability matters - Prevent external code from creating unexpected subtypes

4. Type hierarchy is well-defined - You know all subtypes at design time and they won't change frequently

Don't use sealed classes when:

1. Plugin architectures - If you need third-party extensions, use interfaces

2. Frequently changing hierarchies - Adding new subtypes requires modifying the sealed parent

3. Library APIs with backward compatibility concerns - Sealed classes can't be extended outside your module

Design Patterns with Sealed Classes

1. Algebraic Data Types (ADTs)

Sealed classes with records support algebraic data types (ADTs):

sealed interface Expression permits Constant, Addition, Multiplication {}
record Constant(int value) implements Expression {}
record Addition(Expression left, Expression right) implements Expression {}
record Multiplication(Expression left, Expression right) implements Expression {}

2. State Machines

Model state transitions explicitly:

sealed interface OrderState permits Pending, Confirmed, Shipped, Delivered, Cancelled {}
// Each state can have different properties and transitions

3. Result/Option Types

Type-safe error handling and optional values:

sealed interface Result<T> permits Success, Failure {}
sealed interface Option<T> permits Some, None {}

Combining with Other Features

Sealed + Records - Immutable domain models with minimal boilerplate

sealed interface Vehicle permits Car, Bike {}
record Car(String brand, int doors) implements Vehicle {}
record Bike(String brand, int gears) implements Vehicle {}

Sealed + Pattern Matching - Exhaustive switches without default

return switch (vehicle) {
    case Car c -> "Car with " + c.doors() + " doors";
    case Bike b -> "Bike with " + b.gears() + " gears";
};

Sealed + Enums - Enums are implicitly final, suitable for sealed types

sealed interface TrafficLight permits Red, Yellow, Green {}
enum Red implements TrafficLight { INSTANCE }
enum Yellow implements TrafficLight { INSTANCE }
enum Green implements TrafficLight { INSTANCE }

Package Organization

Keep sealed classes and permitted subclasses in the same package:

com.example.domain/
  ├── Payment.java (sealed interface)
  ├── CreditCard.java (final record)
  ├── DebitCard.java (final record)
  └── Cash.java (final record)

For large hierarchies, use subpackages:

com.example.shapes/
  ├── Shape.java (sealed)
  ├── circle/
  │   └── Circle.java
  ├── polygon/
  │   ├── Polygon.java (sealed)
  │   ├── Triangle.java
  │   └── Rectangle.java
  └── freeform/
      └── FreeformShape.java (non-sealed)

Pitfalls and Limitations

Common Mistakes

1. Forgetting the subclass modifier

sealed class Animal permits Dog, Cat {}

// ❌ Compile error - must use final, sealed, or non-sealed
class Dog extends Animal {}

// ✅ Correct
final class Dog extends Animal {}

2. Subclass in wrong package

package com.example.domain;
sealed class Payment permits CreditCard {}

package com.example.impl; // ❌ Different package!
final class CreditCard extends Payment {} // Compile error

3. Using var with exhaustive switch

// ❌ Doesn't compile - var doesn't work with pattern matching
var result = switch (shape) {
    case var c when c instanceof Circle -> "circle";
    // ...
};

// ✅ Use explicit type patterns
var result = switch (shape) {
    case Circle c -> "circle";
    case Rectangle r -> "rectangle";
    // ...
};

Performance Considerations

Memory overhead - Sealed classes have the same memory footprint as regular classes. No additional overhead.

instanceof checks - Pattern matching with sealed types is fast. The JVM can optimize switches over sealed hierarchies because it knows all possible types.

Reflection - Class.isSealed() and getPermittedSubclasses() have negligible overhead. Use freely.

Limitations

1. Cannot seal classes from other modules

You can't make java.lang.String sealed—you don't own it.

2. No runtime enforcement

Sealed classes are compile-time only. Reflection can still create proxies or use Unsafe to bypass restrictions (but don't do this).

3. Limited to same module/package

In JPMS (Java Platform Module System), sealed classes and subclasses must be in the same module. For non-modular projects, they must be in the same package.

4. Cannot change permits clause without breaking changes

Adding or removing permitted subclasses is a breaking change for anyone using exhaustive switches.

Migration Strategies

From open hierarchies:

1. Identify all current subclasses

2. Add sealed and permits to parent

3. Add final, sealed, or non-sealed to all subclasses

4. Search for switch statements and remove default where appropriate

From final classes:

• If you have a final class and want to add subtypes, change to sealed with explicit permits

• This is non-breaking for existing code

Summary and Next Steps

In this article, we explored Sealed Classes (JEP 409), one of Java 17's most powerful features for domain modeling and type safety.

What we covered:

• The problem: Uncontrolled inheritance creates maintenance burdens and prevents compiler verification

• Sealed classes solution: Explicitly list permitted subclasses with the permits clause

• Three subclass modifiers: final (no extensions), sealed (controlled extensions), non-sealed (open extensions)

• Exhaustive pattern matching: Compiler-verified switches without default cases

• Multi-level hierarchies: Sealed classes at multiple levels for complex domain models

• Practical patterns: Result types, algebraic data types, state machines

When to use sealed classes:

• Domain modeling with closed sets (payment types, shapes, order states)

• APIs where you control all implementations

• Type hierarchies that benefit from exhaustive checking

When to avoid sealed classes:

• Plugin architectures requiring third-party extensions

• Frequently changing hierarchies

• Library APIs with strict backward compatibility requirements

What's Next?

In Part 4, we'll explore Pattern Matching and Switch Expressions—two features that work with sealed classes. You'll learn:

• Pattern matching for instanceof (JEP 394)

• Modern switch expressions with arrow syntax (JEP 361)

• Guards and pattern combinations

• Exhaustive switches with sealed types

• Practical examples combining all three features

Pattern matching and sealed classes together bring functional programming concepts to Java, enabling expressive, type-safe code with minimal boilerplate.

All code examples from this article are available in the GitHub repository:

git clone https://github.com/dawid-swist/blog-9mac-dev-code.git
cd blog-post-examples/java/2025-10-25-java17-features-every-senior-developer-should-know
../../gradlew test

See you in Part 4, where we'll unlock the full power of sealed classes with pattern matching!

This article is part of the "Java 17 Features Every Senior Developer Should Know" series. Check out Part 1: Introduction & var and Part 2: Records if you haven't already.

Previous: Part 2 - Part 2: Records Next: Part 4 - Pattern Matching & Switch Expressions

Welcome back to our comprehensive series on Java 17 features! In Part 1, we explored the var keyword and how type inference reduces boilerplate in local variable declarations. Today, we're diving into one of Java's most impactful features: Records (JEP 395).

If you've ever groaned while writing yet another data class with getters, equals, hashCode, and toString methods, this article is for you. Records eliminate this ceremony entirely, letting you declare data carriers in a single line while the compiler handles the rest.

The Problem: Boilerplate in Data Classes

Before Java 16, creating a simple data class meant writing dozens of lines of repetitive code. Let's look at a typical example - a Point class representing coordinates:

public final class Point {
    private final int x;
    private final int y;

    public Point(int x, int y) {
        this.x = x;
        this.y = y;
    }

    public int getX() { return x; }
    public int getY() { return y; }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        Point point = (Point) o;
        return x == point.x && y == point.y;
    }

    @Override
    public int hashCode() {
        return Objects.hash(x, y);
    }

    @Override
    public String toString() {
        return "Point[x=" + x + ", y=" + y + "]";
    }
}

That's 30+ lines of code just to store two integers! And the problems don't stop there:

• Error-prone: Forget to update equals() when adding a field? Your tests will miss subtle bugs.

• Maintenance burden: Every field addition means updating multiple methods.

• Cluttered code: The ceremony obscures the intent: "this class holds x and y coordinates."

• Refactoring friction: Renaming fields requires changes in 4-5 places.

The Lombok Compromise

Many teams turned to Project Lombok as a temporary solution:

@Value // Generates immutable class with all boilerplate
public class Point {
    int x;
    int y;
}

Lombok works, but it has downsides:

• Requires IDE plugins and annotation processors

• Generated code is invisible in source form

• Not part of the Java language specification

• Can cause build tool complications

• Creates team friction ("Do we really need another dependency?")

The Java community needed a native language solution. Enter Records.

What Are Records?

A record is a special kind of class designed to be a transparent carrier for immutable data. When you declare a record, the compiler automatically generates:

1. Private final fields for each component

2. Public accessor methods (not getters - just the component name)

3. A canonical constructor accepting all components

4. Proper equals() method comparing all components

5. Proper hashCode() method combining all components

6. A toString() method with record-specific format

Here's how the Point class looks as a record:

public record Point(int x, int y) {
}

That's it. One line. The compiler generates the equivalent of all 30+ lines we wrote manually.

Key Characteristics

Records have specific properties that distinguish them from regular classes:

• Immutability: All components are implicitly final

• Transparency: The state is part of the public API contract

• Nominal typing: Each record declaration creates a distinct type

• Restrictions: Records cannot extend other classes (they implicitly extend java.lang.Record)

• Final: Records are implicitly final - they cannot be subclassed

History of Records

Records didn't appear overnight. They evolved through multiple Java versions based on community feedback.

Java 14: Preview Feature (JEP 359)

Records debuted in March 2020 as a preview feature, requiring the --enable-preview compiler flag. The basic syntax was introduced:

record Point(int x, int y) {}

What you got:

• Canonical constructor

• Accessor methods (p.x(), not p.getX())

• equals(), hashCode(), toString() implementations

• Ability to add custom methods

Limitations:

• Preview status meant production use required caution

• Limited to top-level declarations

• Couldn't implement interfaces (initially)

Java 15: Second Preview (JEP 384)

September 2020 brought refinements based on developer feedback:

New capabilities:

• Local records - declare records inside methods

• Compact constructor syntax - validation without repeating parameters

• Interface implementation - records can now implement interfaces

• Nested records - records within classes or other records

// Local record - new in Java 15
public void processOrders(List<Order> orders) {
    record OrderSummary(String customer, double total) {}

    var summaries = orders.stream()
        .map(o -> new OrderSummary(o.customer(), o.total()))
        .toList();
}

Java 16: Standard Feature (JEP 395)

March 2021 marked the graduation of records to a standard, permanent feature. No more --enable-preview flag needed.

Additional enhancements:

• Generic records - record Pair<T, U>(T first, U second) {}

• Static members - static fields and methods allowed

• Annotation support - full annotation capabilities

• Reflection API - Class.isRecord(), getRecordComponents()

Basic Syntax and Features

Declaration Syntax

The basic record declaration consists of:

1. The record keyword

2. The record name

3. Component list in parentheses (the header)

4. Optional body in curly braces

// Minimal record - just the header
record Point(int x, int y) {}

// Record with validation
record Range(int start, int end) {
    // Compact constructor
    public Range {
        if (start > end) {
            throw new IllegalArgumentException(
                "start (" + start + ") must not exceed end (" + end + ")"
            );
        }
    }
}

What the Compiler Generates

When you declare record Point(int x, int y) {}, the compiler creates:

public final class Point extends Record {
    private final int x;
    private final int y;

    // Canonical constructor
    public Point(int x, int y) {
        this.x = x;
        this.y = y;
    }

    // Accessor methods (NOT getters!)
    public int x() { return x; }
    public int y() { return y; }

    // equals comparing all components
    @Override
    public boolean equals(Object obj) {
        return obj instanceof Point other &&
               x == other.x &&
               y == other.y;
    }

    // hashCode combining all components
    @Override
    public int hashCode() {
        return Objects.hash(x, y);
    }

    // toString with record-specific format
    @Override
    public String toString() {
        return "Point[x=" + x + ", y=" + y + "]";
    }
}

Canonical Constructor

The canonical constructor is the constructor that takes all components in order. The compiler generates it automatically:

record Point(int x, int y) {}

// Compiler generates:
// public Point(int x, int y) { ... }

You can provide your own canonical constructor if needed:

record Point(int x, int y) {
    // Explicit canonical constructor
    public Point(int x, int y) {
        if (x < 0 || y < 0) {
            throw new IllegalArgumentException("Coordinates must be non-negative");
        }
        this.x = x;
        this.y = y;
    }
}

Compact Constructor

Java 15 introduced the compact constructor - a more concise way to customize the canonical constructor:

record Range(int start, int end) {
    // Compact constructor - no parameter list!
    public Range {
        // Validation runs BEFORE field initialization
        if (start > end) {
            throw new IllegalArgumentException("Invalid range");
        }
        // Field assignments happen automatically after this block
    }
}

The compact constructor is syntactic sugar. The compiler transforms it into the canonical constructor, inserting field assignments at the end.

You can also normalize data:

record Person(String name, int age) {
    public Person {
        // Normalize before storing
        name = name.trim().toUpperCase();
        age = Math.max(0, age); // Ensure non-negative
    }
}

Custom Methods

Records can have instance and static methods:

record Rectangle(int width, int height) {
    // Instance method
    public int area() {
        return width * height;
    }

    // Static factory method
    public static Rectangle square(int side) {
        return new Rectangle(side, side);
    }

    // "Wither" method - returns modified copy
    public Rectangle withWidth(int newWidth) {
        return new Rectangle(newWidth, height);
    }
}

Practical Examples

Let's explore records through six practical examples, each with complete code and JUnit tests.

Example 1: Basic Records with Validation

Records provide immutable data carriers with minimal boilerplate. The compiler automatically generates equals(), hashCode(), toString(), and accessor methods.

// Basic record representing 2D coordinates
public record Point(int x, int y) {
}

// Record with validation using compact constructor
public record Range(int start, int end) {
    public Range {
        if (start > end) {
            throw new IllegalArgumentException(
                "start must not exceed end: start=" + start + ", end=" + end
            );
        }
    }

    public boolean contains(int value) {
        return value >= start && value <= end;
    }
}

public class BasicRecordExample {
    public static void main(String[] args) {
        // Point examples
        var p1 = new Point(10, 20);
        var p2 = new Point(10, 20);
        var p3 = new Point(30, 40);

        System.out.println("Point p1: " + p1);
        System.out.println("Accessing components: x=" + p1.x() + ", y=" + p1.y());

        // Equality (value-based)
        System.out.println("p1.equals(p2): " + p1.equals(p2));  // true
        System.out.println("p1 == p2: " + (p1 == p2));           // false
        System.out.println("p1.hashCode() == p2.hashCode(): " + (p1.hashCode() == p2.hashCode())); // true

        // Range examples
        var r1 = new Range(1, 10);
        System.out.println("\nRange: " + r1);
        System.out.println("Contains 5? " + r1.contains(5));
        System.out.println("Contains 15? " + r1.contains(15));

        // Validation
        try {
            var invalid = new Range(10, 1);
        } catch (IllegalArgumentException e) {
            System.out.println("Expected error: " + e.getMessage());
        }
    }
}

// Unit tests

@Test
@DisplayName("Should create Point with x and y coordinates")
void shouldCreatePointWithCoordinates() {
    var point = new Point(10, 20);

    assertEquals(10, point.x());
    assertEquals(20, point.y());
}

@Test
@DisplayName("Should compare Points by value equality")
void shouldComparePointsByValueEquality() {
    var p1 = new Point(10, 20);
    var p2 = new Point(10, 20);
    var p3 = new Point(10, 30);

    assertEquals(p1, p2);
    assertNotEquals(p1, p3);
    assertEquals(p1.hashCode(), p2.hashCode());
}

@Test
@DisplayName("Should generate toString in record format")
void shouldGenerateToStringInRecordFormat() {
    var point = new Point(10, 20);

    assertEquals("Point[x=10, y=20]", point.toString());
}

@Test
@DisplayName("Should throw exception when creating Range with start greater than end")
void shouldThrowExceptionWhenCreatingRangeWithStartGreaterThanEnd() {
    var exception = assertThrows(
        IllegalArgumentException.class,
        () -> new Range(10, 1)
    );

    assertTrue(exception.getMessage().contains("start must not exceed end"));
}

Output:

Point p1: Point[x=10, y=20]
Accessing components: x=10, y=20
p1.equals(p2): true
p1 == p2: false
p1.hashCode() == p2.hashCode(): true

Range: Range[start=1, end=10]
Contains 5? true
Contains 15? false
Expected error: start must not exceed end: start=10, end=1

Key Insight: Records provide value semantics out of the box. Two Point instances with the same coordinates are considered equal, making them perfect for map keys and set elements.

Example 2: Generic Records

Generic records enable reusable, type-safe data structures with full type inference support.

// Generic pair - holds two values of potentially different types
public record Pair<T, U>(T first, U second) {
    public Pair<U, T> swap() {
        return new Pair<>(second, first);
    }
}

// Generic record with bounded type parameter - only Number subtypes allowed
public record Box<T extends Number>(T value) {
    public double doubleValue() {
        return value.doubleValue();
    }

    public static Box<Integer> ofInt(int value) {
        return new Box<>(value);
    }
}

public class GenericRecordExample {
    public static void main(String[] args) {
        // Pair with different types
        var pair1 = new Pair<>("age", 30);
        System.out.println("String-Integer pair: " + pair1);
        System.out.println("First: " + pair1.first() + ", Second: " + pair1.second());

        // Swap elements
        var swapped = pair1.swap();
        System.out.println("Swapped: " + swapped);

        // Box with bounded type
        var intBox = Box.ofInt(42);
        var doubleBox = new Box<>(3.14);
        System.out.println("Integer box: " + intBox);
        System.out.println("  as double: " + intBox.doubleValue());
        System.out.println("Double box: " + doubleBox);

        // Nested generics
        var nested = new Pair<>(new Pair<>(1, 2), "coordinates");
        System.out.println("Nested pair: " + nested);
        System.out.println("Inner first: " + nested.first().first());
    }
}

// Unit tests

@Test
@DisplayName("Should create generic Pair with different types")
void shouldCreateGenericPairWithDifferentTypes() {
    var p1 = new Pair<>("age", 30);
    assertEquals("age", p1.first());
    assertEquals(30, p1.second());

    var p2 = new Pair<>(42, "answer");
    assertEquals(42, p2.first());
    assertEquals("answer", p2.second());
}

@Test
@DisplayName("Should swap Pair elements")
void shouldSwapPairElements() {
    var original = new Pair<>("key", 123);
    var swapped = original.swap();

    assertEquals(123, swapped.first());
    assertEquals("key", swapped.second());
    assertEquals("key", original.first());
}

@Test
@DisplayName("Should create Box with bounded generic type")
void shouldCreateBoxWithBoundedGenericType() {
    var intBox = new Box<>(42);
    var doubleBox = new Box<>(3.14);

    assertEquals(42.0, intBox.doubleValue());
    assertEquals(3.14, doubleBox.doubleValue(), 0.001);
}

@Test
@DisplayName("Should support nested Pairs")
void shouldSupportNestedPairs() {
    var nested = new Pair<>(new Pair<>(1, 2), "coordinates");

    assertEquals(1, nested.first().first());
    assertEquals(2, nested.first().second());
    assertEquals("coordinates", nested.second());
}

Output:

String-Integer pair: Pair[first=age, second=30]
First: age, Second: 30
Swapped: Pair[first=30, second=age]
Integer box: Box[value=42]
  as double: 42.0
Double box: Box[value=3.14]
Nested pair: Pair[first=Pair[first=1, second=2], second=coordinates]
Inner first: 1

Key Insight: Generic records combine type safety with reusability. The bounded type parameter in Box<T extends Number> ensures only numeric types can be stored while still providing generic flexibility.

Example 3: Records with Custom Methods

Records can contain rich behavior while maintaining immutability. The "wither" pattern allows creating modified copies.

// Person record with custom methods and validation
public record Person(String firstName, String lastName, int age) {
    public Person {
        firstName = firstName.trim();
        lastName = lastName.trim();
        if (age < 0) {
            throw new IllegalArgumentException("Age cannot be negative: " + age);
        }
    }

    public String fullName() {
        return firstName + " " + lastName;
    }

    public boolean isAdult() {
        return age >= 18;
    }

    // Wither method - returns modified copy
    public Person withAge(int newAge) {
        return new Person(firstName, lastName, newAge);
    }
}

// Money record with business logic
public record Money(BigDecimal amount, String currency) {
    public Money {
        if (amount.compareTo(BigDecimal.ZERO) < 0) {
            throw new IllegalArgumentException("Amount cannot be negative");
        }
        currency = currency.toUpperCase();
    }

    public Money add(Money other) {
        if (!currency.equals(other.currency)) {
            throw new IllegalArgumentException("Currency mismatch");
        }
        return new Money(amount.add(other.amount), currency);
    }

    public static Money dollars(double amount) {
        return new Money(BigDecimal.valueOf(amount), "USD");
    }
}

public class RecordMethodsExample {
    public static void main(String[] args) {
        // Person examples
        Person person = new Person("  Alice  ", "  Smith  ", 30);
        System.out.println("Person: " + person);
        System.out.println("Full name: " + person.fullName());
        System.out.println("Is adult: " + person.isAdult());

        // Wither pattern
        Person older = person.withAge(31);
        System.out.println("After birthday: " + older);
        System.out.println("Original unchanged: " + person);

        // Money examples
        Money m1 = Money.dollars(10.50);
        Money m2 = Money.dollars(5.25);
        System.out.println("\nm1: " + m1);
        System.out.println("m2: " + m2);
        System.out.println("Sum: " + m1.add(m2));
    }
}

// Unit tests

@Test
@DisplayName("Should normalize names and validate age in Person")
void shouldNormalizeNamesAndValidateAge() {
    Person person = new Person("  Alice  ", "  Smith  ", 30);

    assertEquals("Alice", person.firstName());
    assertEquals("Smith", person.lastName());
    assertEquals("Alice Smith", person.fullName());
    assertTrue(person.isAdult());
}

@Test
@DisplayName("Should create modified copy using wither pattern")
void shouldCreateModifiedCopyUsingWitherPattern() {
    Person p1 = new Person("Bob", "Jones", 15);
    assertFalse(p1.isAdult());

    Person p2 = p1.withAge(25);

    assertTrue(p2.isAdult());
    assertEquals(25, p2.age());
    assertEquals(15, p1.age()); // Original unchanged
}

@Test
@DisplayName("Should add Money with same currency")
void shouldAddMoneyWithSameCurrency() {
    Money m1 = Money.dollars(10.50);
    Money m2 = new Money(new BigDecimal("5.25"), "USD");

    Money sum = m1.add(m2);

    assertEquals(new BigDecimal("15.75"), sum.amount());
    assertEquals("USD", sum.currency());
}

@Test
@DisplayName("Should throw exception when adding Money with different currencies")
void shouldThrowExceptionWhenAddingMoneyWithDifferentCurrencies() {
    Money usd = Money.dollars(10);
    Money eur = new Money(BigDecimal.TEN, "EUR");

    assertThrows(IllegalArgumentException.class, () -> usd.add(eur));
}

Output:

Person: Person[firstName=Alice, lastName=Smith, age=30]
Full name: Alice Smith
Is adult: true
After birthday: Person[firstName=Alice, lastName=Smith, age=31]
Original unchanged: Person[firstName=Alice, lastName=Smith, age=30]

m1: Money[amount=10.50, currency=USD]
m2: Money[amount=5.25, currency=USD]
Sum: Money[amount=15.75, currency=USD]

Key Insight: The "wither" pattern (withAge()) is common in records - since records are immutable, methods that would "modify" state instead return a new instance with the changed value.

Example 4: Records Implementing Interfaces

Records work seamlessly with interfaces, enabling polymorphism while maintaining concise syntax.

// Interface for drawable objects
public interface Drawable {
    void draw();
    double area();

    default String description() {
        return "Drawable shape with area: " + area();
    }
}

// Circle record implementing Drawable
public record Circle(int x, int y, int radius) implements Drawable {
    public Circle {
        if (radius <= 0) {
            throw new IllegalArgumentException("Radius must be positive");
        }
    }

    @Override
    public void draw() {
        System.out.println("Drawing circle at (" + x + ", " + y +
                         ") with radius " + radius);
    }

    @Override
    public double area() {
        return Math.PI * radius * radius;
    }
}

// Rectangle record implementing Drawable
public record Rectangle(int x, int y, int width, int height) implements Drawable {
    public Rectangle {
        if (width <= 0 || height <= 0) {
            throw new IllegalArgumentException("Width and height must be positive");
        }
    }

    @Override
    public void draw() {
        System.out.println("Drawing rectangle at (" + x + ", " + y + ") " +
                         width + "x" + height);
    }

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

    public boolean isSquare() {
        return width == height;
    }
}

public class RecordInterfaceExample {
    public static void main(String[] args) {
        // Drawable shapes
        Circle circle = new Circle(10, 20, 5);
        circle.draw();
        System.out.println("Area: " + circle.area());
        System.out.println("Description: " + circle.description());

        Rectangle rect = new Rectangle(0, 0, 100, 50);
        rect.draw();
        System.out.println("Area: " + rect.area());
        System.out.println("Is square: " + rect.isSquare());

        // Polymorphism
        List<Drawable> shapes = List.of(
            new Circle(0, 0, 10),
            new Rectangle(0, 0, 20, 30),
            new Circle(5, 5, 15)
        );

        System.out.println("\nPolymorphic behavior:");
        for (Drawable shape : shapes) {
            System.out.println(shape.getClass().getSimpleName() + " - " +
                             shape.description());
        }
    }
}

// Unit tests

@Test
@DisplayName("Should implement Drawable interface for Circle and Rectangle")
void shouldImplementDrawableInterface() {
    Circle circle = new Circle(10, 20, 5);
    Rectangle rect = new Rectangle(0, 0, 100, 50);

    assertTrue(circle instanceof Drawable);
    assertTrue(rect instanceof Drawable);
}

@Test
@DisplayName("Should calculate areas correctly")
void shouldCalculateAreasCorrectly() {
    Circle c = new Circle(0, 0, 5);
    Rectangle r = new Rectangle(0, 0, 10, 20);

    assertTrue(c.area() > 78 && c.area() < 79); // π * 5²
    assertEquals(200.0, r.area(), 0.001);       // 10 * 20
}

@Test
@DisplayName("Should support polymorphic collections")
void shouldSupportPolymorphicCollections() {
    List<Drawable> shapes = List.of(
        new Circle(10, 20, 5),
        new Rectangle(30, 40, 100, 50),
        new Circle(60, 70, 15)
    );

    assertEquals(3, shapes.size());
    assertTrue(shapes.get(0) instanceof Circle);
    assertTrue(shapes.get(1) instanceof Rectangle);
}

@Test
@DisplayName("Should check if Rectangle is square")
void shouldCheckIfRectangleIsSquare() {
    Rectangle square = new Rectangle(0, 0, 10, 10);
    Rectangle rect = new Rectangle(0, 0, 10, 20);

    assertTrue(square.isSquare());
    assertFalse(rect.isSquare());
}

Output:

Drawing circle at (10, 20) with radius 5
Area: 78.53981633974483
Description: Drawable shape with area: 78.53981633974483
Drawing rectangle at (0, 0) 100x50
Area: 5000.0
Is square: false

Polymorphic behavior:
Circle - Drawable shape with area: 314.1592653589793
Rectangle - Drawable shape with area: 600.0
Circle - Drawable shape with area: 706.8583470577034

Key Insight: Records work seamlessly with interfaces, enabling polymorphism while maintaining all the benefits of concise syntax and generated methods.

Example 5: Nested Records

Records compose naturally to model complex domain objects. Each record maintains its own invariants while composing into larger structures.

// Address record - represents a physical address
public record Address(String street, String city, String zipCode, String country) {
    public Address {
        if (street == null || street.isBlank()) {
            throw new IllegalArgumentException("Street cannot be blank");
        }
        if (city == null || city.isBlank()) {
            throw new IllegalArgumentException("City cannot be blank");
        }
        // Normalize zip code (remove spaces)
        zipCode = zipCode.replaceAll("\\s", "");
        // Normalize country to uppercase
        country = country.toUpperCase();
    }

    public String format() {
        return street + ", " + city + " " + zipCode + ", " + country;
    }

    public boolean isInCountry(String countryCode) {
        return country.equalsIgnoreCase(countryCode);
    }
}

// Employee record - contains nested Address
public record Employee(String name, int id, Address address) {
    public Employee {
        if (name == null || name.isBlank()) {
            throw new IllegalArgumentException("Name cannot be blank");
        }
        if (id <= 0) {
            throw new IllegalArgumentException("ID must be positive: " + id);
        }
    }

    public String getFullAddress() {
        return address.format();
    }

    public String getCity() {
        return address.city();
    }

    public Employee relocate(Address newAddress) {
        return new Employee(name, id, newAddress);
    }

    public boolean worksInCountry(String countryCode) {
        return address.isInCountry(countryCode);
    }
}

public class NestedRecordsExample {
    public static void main(String[] args) {
        // Simple nesting
        Address addr = new Address("123 Main St", "Springfield", "12345", "USA");
        Employee emp = new Employee("Alice Smith", 1001, addr);

        System.out.println("Employee: " + emp.name());
        System.out.println("ID: " + emp.id());
        System.out.println("City: " + emp.getCity());
        System.out.println("Full address: " + emp.getFullAddress());
        System.out.println("Works in USA: " + emp.worksInCountry("USA"));

        // Relocation
        Address newAddr = new Address("456 Oak Ave", "Portland", "97201", "USA");
        Employee relocated = emp.relocate(newAddr);

        System.out.println("\nOriginal city: " + emp.getCity());
        System.out.println("New city: " + relocated.getCity());
    }
}

// Unit tests

@Test
@DisplayName("Should access nested Address properties from Employee")
void shouldAccessNestedAddressProperties() {
    Address addr = new Address("123 Main St", "Springfield", "12345", "USA");
    Employee emp = new Employee("Alice Smith", 1001, addr);

    assertEquals("Alice Smith", emp.name());
    assertEquals("Springfield", emp.address().city());
    assertEquals("12345", emp.address().zipCode());
}

@Test
@DisplayName("Should format full address from nested record")
void shouldFormatFullAddressFromNestedRecord() {
    Address addr = new Address("123 Main St", "Springfield", "12345", "USA");
    Employee emp = new Employee("Bob Jones", 1002, addr);

    String expected = "123 Main St, Springfield 12345, USA";
    assertEquals(expected, emp.getFullAddress());
}

@Test
@DisplayName("Should create relocated Employee with new Address")
void shouldCreateRelocatedEmployeeWithNewAddress() {
    Address addr1 = new Address("123 Main St", "Springfield", "12345", "USA");
    Employee emp1 = new Employee("Charlie", 1003, addr1);

    Address addr2 = new Address("456 Oak Ave", "Portland", "97201", "USA");
    Employee emp2 = emp1.relocate(addr2);

    assertEquals("Portland", emp2.address().city());
    assertEquals("Springfield", emp1.address().city()); // Original unchanged
    assertEquals(emp1.id(), emp2.id());
    assertEquals(emp1.name(), emp2.name());
}

@Test
@DisplayName("Should normalize zip code removing spaces")
void shouldNormalizeZipCodeRemovingSpaces() {
    Address addr = new Address("123 Main", "City", "12 345", "USA");
    assertEquals("12345", addr.zipCode());
}

Output:

Employee: Alice Smith
ID: 1001
City: Springfield
Full address: 123 Main St, Springfield 12345, USA
Works in USA: true

Original city: Springfield
New city: Portland

Key Insight: Nested records model complex domain objects naturally. Each record maintains its own invariants while composing into larger structures.

Example 6: Performance Considerations

Understanding how records perform is crucial for production use - memory layout, equality operations, and collection performance.

// Small record for memory demonstration
public record SmallRecord(int x, int y) {
}

// Larger record for comparison
public record LargeRecord(long a, long b, long c, long d, long e) {
}

// Record for equality testing
public record TestRecord(String field1, String field2, int field3, long field4) {
}

// Coordinate record for collection performance
public record Coordinate(int x, int y) {
    public int manhattanDistance() {
        return Math.abs(x) + Math.abs(y);
    }
}

// Color record demonstrating caching pattern
public record Color(int r, int g, int b) {
    private static final Map<String, Color> CACHE = new ConcurrentHashMap<>();

    public Color {
        if (r < 0 || r > 255 || g < 0 || g > 255 || b < 0 || b > 255) {
            throw new IllegalArgumentException(
                "RGB values must be 0-255: r=" + r + ", g=" + g + ", b=" + b
            );
        }
    }

    public static Color of(int r, int g, int b) {
        String key = r + "," + g + "," + b;
        return CACHE.computeIfAbsent(key, k -> new Color(r, g, b));
    }

    public static void clearCache() {
        CACHE.clear();
    }

    public static final Color RED = Color.of(255, 0, 0);
    public static final Color GREEN = Color.of(0, 255, 0);
    public static final Color BLUE = Color.of(0, 0, 255);

    public String toHex() {
        return String.format("#%02X%02X%02X", r, g, b);
    }
}

public class RecordPerformanceExample {
    public static void main(String[] args) {
        // Memory estimates
        System.out.println("=== Memory Layout ===");
        System.out.println("SmallRecord: ~24 bytes");
        System.out.println("LargeRecord: ~56 bytes");

        // Equality performance
        System.out.println("\n=== Equality Performance ===");
        TestRecord r1 = new TestRecord("alpha", "beta", 100, 200L);
        TestRecord r2 = new TestRecord("alpha", "beta", 100, 200L);

        int iterations = 1_000_000;
        long start = System.nanoTime();
        for (int i = 0; i < iterations; i++) {
            r1.equals(r2);
        }
        long duration = System.nanoTime() - start;
        System.out.println("1M equality checks: " + duration / 1_000_000 + "ms");

        // HashMap performance
        System.out.println("\n=== HashMap Performance ===");
        Map<Coordinate, String> map = new HashMap<>();
        for (int i = 0; i < 1000; i++) {
            map.put(new Coordinate(i, i * 2), "value" + i);
        }
        System.out.println("Inserted 1000 records as keys");
        System.out.println("Lookup test: " + map.get(new Coordinate(500, 1000)));

        // Caching pattern
        System.out.println("\n=== Caching Pattern ===");
        Color.clearCache();
        Color red1 = Color.of(255, 0, 0);
        Color red2 = Color.of(255, 0, 0);
        System.out.println("red1 == red2 (same instance): " + (red1 == red2));
        System.out.println("RED constant: " + Color.RED.toHex());
    }
}

// Unit tests

@Test
@DisplayName("Should have comparable memory overhead to manual classes")
void shouldHaveComparableMemoryOverhead() {
    SmallRecord small = new SmallRecord(10, 20);
    LargeRecord large = new LargeRecord(1L, 2L, 3L, 4L, 5L);

    // Records have same overhead as equivalent manual classes
    assertNotNull(small);
    assertNotNull(large);
}

@Test
@DisplayName("Should perform equality checks efficiently")
void shouldPerformEqualityChecksEfficiently() {
    TestRecord r1 = new TestRecord("alpha", "beta", 100, 200L);
    TestRecord r2 = new TestRecord("alpha", "beta", 100, 200L);

    long start = System.nanoTime();
    for (int i = 0; i < 1_000_000; i++) {
        r1.equals(r2);
    }
    long duration = System.nanoTime() - start;

    assertTrue(duration < 100_000_000); // Under 100ms
}

@Test
@DisplayName("Should work efficiently as HashMap keys")
void shouldWorkEfficientlyAsHashMapKeys() {
    Map<Coordinate, String> map = new HashMap<>();

    for (int i = 0; i < 1000; i++) {
        map.put(new Coordinate(i, i * 2), "value" + i);
    }

    Coordinate key = new Coordinate(500, 1000);
    assertEquals("value500", map.get(key));

    // Check hash distribution
    Set<Integer> hashCodes = new HashSet<>();
    for (Coordinate coord : map.keySet()) {
        hashCodes.add(coord.hashCode());
    }
    assertTrue(hashCodes.size() > 950); // Good hash distribution
}

@Test
@DisplayName("Should support caching pattern with factory method")
void shouldSupportCachingPatternWithFactoryMethod() {
    Color.clearCache();
    Color red1 = Color.of(255, 0, 0);
    Color red2 = Color.of(255, 0, 0);

    assertSame(red1, red2); // Same instance from cache
    assertEquals(red1, red2); // Also value equality
}