Pattern Matching in Java - CryptoPayment MatchException

Every Java codebase written before Java 16 has at least one method that looks like a long chain of instanceof checks followed by explicit casts. It works, but it's noisy, repetitive, and a quiet source of bugs — cast the wrong type and you get a ClassCastException at runtime with no compiler warning. The real cost isn't the extra line; it's the cognitive overhead of mentally tracking which type you've already confirmed while reading through a wall of if-else branches.

Pattern matching was introduced to solve exactly this friction. It lets the compiler carry the type knowledge forward so you don't have to. Instead of check → cast → use (three steps), you get check-and-bind (one step). This isn't just syntactic sugar — it's a language-level guarantee: the binding variable is only in scope where the compiler can prove the type holds, which eliminates an entire class of runtime errors.

By the end of this article you'll understand how pattern matching for instanceof works at the bytecode level, how switch pattern matching (Java 21) lets you write exhaustive, compiler-verified dispatch logic, how sealed classes and records compose with patterns to build airtight domain models, and what production gotchas can bite you even when everything compiles cleanly. We'll go deep — this is the stuff that separates developers who know the syntax from those who understand the design.

What is Pattern Matching in Java?

Pattern matching is a language feature that combines type checking with variable binding in a single operation. Instead of writing:

``java if (obj instanceof String) { String s = (String) obj; // use s } ``

You write:

``java if (obj instanceof String s) { // use s directly } ``

This is not just shorter — it eliminates a whole class of bugs where the cast fails because the type changed between check and cast. The binding variable is only in scope if the pattern matches, so you can't accidentally use it outside the branch.

Each step widens the scope: from simple type checks to complex data structure destructuring and exhaustive dispatch.

package io.thecodeforge.matching;

// Traditional approach vs pattern matching
public class ShapeMatcher {
    public static void main(String[] args) {
        Object shape = new Circle(5.0);
        
        // Old way
        if (shape instanceof Circle) {
            Circle c = (Circle) shape;
            System.out.println("Area: " + c.area());
        }
        
        // Pattern matching
        if (shape instanceof Circle c) {
            System.out.println("Area: " + c.area());
        }
    }
    
    static class Circle {
        double radius;
        Circle(double r) { radius = r; }
        double area() { return Math.PI * radius * radius; }
    }
}

Instanceof Pattern Matching in Depth

The simplest form of pattern matching is the instanceof pattern, stabilized in Java 16. It allows you to write:

``java if (obj instanceof String s && s.length() > 5) { // s is a String and length > 5 } ``

Note the conjunction: the pattern variable s is available in the subsequent conditions of the same expression due to flow scoping. This works with &&, ||, and negation (!).

Flow scoping means the compiler tracks when a variable is definitely matched. For example: ``java if (!(obj instanceof String s)) { // s is NOT in scope here } // s is NOT in scope here either, because we can't guarantee it matched ``

But if you combine with ||: ``java if (obj instanceof String s || obj instanceof Integer i) { // Here neither s nor i is reliably in scope because either could be true } `` The compiler is conservative — it only allows pattern variables where they are guaranteed to be bound on all paths leading to that code point.

This precision means you can write complex type checks without worrying about variable leaks.

package io.thecodeforge.matching;

public class FlowScopingDemo {
    public static void main(String[] args) {
        Object obj = "hello world";
        
        // Works: pattern variable in scope in then-block
        if (obj instanceof String s && s.length() > 3) {
            System.out.println("Long string: " + s);
        }
        
        // Does NOT compile: pattern variable not definitely assigned
        // if (obj instanceof String s || obj instanceof Integer i) {
        //     System.out.println(s);  // compile error
        // }
        
        // Negation with explicit scope
        if (!(obj instanceof String s)) {
            // s not in scope here
            System.out.println("Not a string");
        } else {
            // s is in scope here: compiler knows it matched
            System.out.println("String length: " + s.length());
        }
    }
}

Switch Pattern Matching and Exhaustiveness

Java 21 brought pattern matching to switch statements and expressions. This is where the real power lies: you can now match on multiple patterns, including guards (using when), and the compiler will check that all cases are covered.

Basic switch pattern matching: ``java String formatted = switch (shape) { case Circle c -> "Circle radius: " + c.radius(); case Rectangle r -> "Rectangle area: " + r.area(); case Square s -> "Square side: " + s.side(); default -> "Unknown shape"; }; ``

But the real game-changer is exhaustiveness with sealed classes. If your hierarchy is sealed, you can omit the default clause: ```java sealed interface Shape permits Circle, Rectangle, Square { }

String formatted = switch (shape) { case Circle c -> "Circle radius: " + c.radius(); case Rectangle r -> "Rectangle area: " + r.area(); case Square s -> "Square side: " + s.side(); // No default needed — compiler knows all cases covered }; ``` If you later add a new subtype to the permits clause, the switch will fail to compile until you add the missing case. This is a powerful safety net.

Guards allow you to add extra conditions: ``java case Shape s when s.area() > 100 -> "Large shape: " + s; `` The guard is evaluated after the pattern matches. If the guard fails, the next case is tried.

Total patterns like case Object o act as a catch-all when you cannot use sealed classes. But they disable exhaustiveness checking — use sparingly.

package io.thecodeforge.matching;

public class SwitchPatternDemo {
    sealed interface Shape permits Circle, Rectangle, Square { }
    record Circle(double radius) implements Shape {
        double area() { return Math.PI * radius * radius; }
    }
    record Rectangle(double width, double height) implements Shape {\n        double area() { return width * height; }
    }
    record Square(double side) implements Shape {
        double area() { return side * side; }
    }
    
    public static void main(String[] args) {
        Shape shape = new Circle(5.0);
        String description = switch (shape) {
            case Circle c && c.radius() > 3 -> "Big circle";
            case Circle c -> "Small circle";
            case Rectangle r -> "Rectangle";
            case Square s -> "Square";
            // No default needed
        };
        System.out.println(description);
    }
}

Record Patterns and Destructuring

Record patterns (final in Java 21) allow you to destructure a record into its components directly in a pattern match. This is especially powerful when combined with switch:

```java record Point(int x, int y) { } record Line(Point start, Point end) { }

String describe(Object obj) { return switch (obj) { case Point(int x, int y) -> "Point at (" + x + ", " + y + ")"; case Line(Point(var x1, var y1), Point(var x2, var y2)) -> "Line from (" + x1 + "," + y1 + ") to (" + x2 + "," + y2 + ")"; default -> "Unknown"; }; } ```

Note the use of var in nested patterns — you can omit the type when it's clear from the record component type. You can also use guards on the destructured values: ``java case Point(int x, int y) when x == y -> "Diagonal point"; ``

Record patterns work with both switch and instanceof: ``java if (obj instanceof Point(int x, int y)) { System.out.println("Point at " + x + ", " + y); } ``

This is a massive reduction in boilerplate for data-centric code — no more manual getter calls or if-null checks.

package io.thecodeforge.matching;

public class RecordPatternDemo {
    record Point(int x, int y) { }
    record Circle(Point center, double radius) { }
    
    public static void main(String[] args) {
        Object obj = new Circle(new Point(3, 4), 5.0);
        String desc = switch (obj) {
            case Circle(Point(var x, var y), var r) when r > 10.0 -> 
                "Large circle at (" + x + "," + y + ")";
            case Circle(Point(var x, var y), var r) -> 
                "Circle at (" + x + "," + y + ") radius " + r;
            case Point p -> "Point at (" + p.x() + "," + p.y() + ")";
            default -> "Unknown";
        };
        System.out.println(desc);
    }
}

Production Gotchas and Performance Considerations

Pattern matching in Java is designed to be efficient, but there are nuances:

1. Pattern ordering matters: In switch, patterns are tried in order. If you have overlapping patterns (e.g., Number n before Integer i), the more specific pattern will never match. The compiler warns about unreachable code in simple cases but not in all.
2. Guard evaluation order: The guard is evaluated after the pattern matches. If the guard throws an exception, it propagates as if it were any other runtime exception. Guards that depend on mutable state can cause nondeterministic behaviour.
3. Null handling: In switch expressions, null does not match any pattern unless you have an explicit case null. Before Java 21, switch threw NullPointerException. Now you can handle null:
4. ```java
5. switch (obj) {
6. case null -> "null";
7. case String s -> s;
8. // ...
9. }
10. ```
11. Performance: For switch over sealed classes with a small number of subtypes (≤ 10), the JVM uses tableswitch which is O(1). For larger sets or non-sealed hierarchies, it may fall back to lookupswitch or a series of instanceof checks. In practice, the performance difference is negligible for most code.
12. Bytecode size: Record patterns and nested patterns can lead to significantly larger bytecode because each component becomes a getter call. This is rarely a problem but can affect startup time on class-loading-heavy applications.
13. Backwards compatibility: Pattern matching on existing legacy code may introduce subtle changes if you refactor a long if-else chain. Always test thoroughly.

package io.thecodeforge.matching;

public class NullHandlingDemo {
    public static void main(String[] args) {
        Object obj = null;
        String result = switch (obj) {
            case null -> "Received null";
            case String s -> "String: " + s;
            case Integer i -> "Integer: " + i;
            default -> "Unknown";
        };
        System.out.println(result);
    }
}

Pattern Matching Syntax — What You Actually Write vs. Regex Confusion

New devs often confuse pattern matching in Java with regex patterns from java.util.regex. They're completely different. The pattern() method on Matcher returns a Pattern object for regex — it has nothing to do with instanceof or switch pattern matching introduced in Java 16+. In production, I've seen teams waste hours debugging because someone assumed Pattern.matches() would work like instanceof pattern matching. It won't. Pattern matching in Java 21 uses instanceof with a variable binding: if (obj instanceof String s) — that's the syntax. No regex involved. The compiler checks types, not text. When you see matcher.pattern(), you're looking at a compiled regex, not a type pattern. Keep them separate in your head. One matches text strings against wildcards. The other matches object types against Java's type hierarchy. Your IDE's autocomplete will suggest both. Know which one you need before you type.

// io.thecodeforge
import java.util.regex.Pattern;

public class PatternVsRegex {
    public static void main(String[] args) {
        // This is REGEX — NOT pattern matching
        Pattern regex = Pattern.compile("G.*s$");
        String input = "GeeksForGeeks";
        System.out.println("Regex matches: " + regex.matcher(input).matches());

        Object obj = "GeeksForGeeks";
        // This is PATTERN MATCHING (Java 16+)
        if (obj instanceof String s && s.startsWith("G")) {
            System.out.println("Pattern matched string: " + s);
        }
    }
}

Exhaustiveness — Why Your Switch Compiles but Blows Up at Runtime

Switch pattern matching in Java 21 requires exhaustiveness when you use sealed classes or enums. The compiler forces you to handle all subtypes. But here's the production trap: if you use a plain interface without sealed, the compiler cannot enforce exhaustiveness. Your switch compiles fine. Your tests pass. Then at 3 AM, a new implementation gets introduced via classpath scanning or reflection, and your switch silently falls through or throws a MatchException. I fixed this exact bug in a payment routing service. The team added a new payment provider enum value but forgot to update the switch. In production, unmatched patterns throw MatchException at runtime. The fix: always add a default case even when you think the compiler has your back. Use sealed classes for domain types you control. For external interfaces, write a unit test that uses reflection to verify all implementations are covered. Your future self will thank you when the on-call phone stays silent.

// io.thecodeforge
sealed interface Payment permits CreditCard, PayPal, Crypto {}
record CreditCard(String cardNum) implements Payment {}
record PayPal(String email) implements Payment {}
record Crypto(String wallet) implements Payment {}

public class ExhaustiveSwitch {
    public static String process(Payment p) {
        return switch(p) {
            case CreditCard c -> "Processing card ending " + c.cardNum().substring(12);
            case PayPal e -> "Sending invoice to " + e.email();
            case Crypto w -> "Confirming wallet " + w.wallet();
            // Uncomment below or get MatchException at runtime
            // default -> throw new IllegalArgumentException("Unknown payment: " + p);
        };
    }

    public static void main(String[] args) {
        System.out.println(process(new CreditCard("1234567890123456")));
    }
}

Nested Record Patterns — Destructuring Without the Boilerplate

Record patterns let you destructure nested objects in a single line. Before Java 21, extracting values from deeply nested records meant five lines of null checks and getter calls. Now you write if (obj instanceof Order(var id, Address(var street, var city))) and the compiler extracts everything. But here's the production reality: the compiler generates synthetic accessor methods for record components. If your record has complex validation in the constructor, those accessors still run on every match. I flattened a Logstash-shaped slowdown by caching a deeply nested record pattern match that was being called on every HTTP request. The fix: match early, destructure once, pass the extracted values. Also, nullable record components break pattern matching — a null in a nested position causes the match to fail silently. If your JSON deserialization sets fields to null (looking at you, Jackson), your pattern matching will never trigger. Validate your data before attempting pattern matches on it.

// io.thecodeforge
record Address(String street, String city) {}
record Order(long id, Address address) {}

public class NestedRecords {
    public static String extractCity(Object obj) {
        // Before Java 21: 5 lines of null checks
        // Java 21: one line destructuring
        return switch (obj) {
            case Order(var id, Address(var street, var city)) -> 
                "Order " + id + " ships to " + city;
            case null -> "Null object received";
            default -> "Not an order";
        };
    }

    public static void main(String[] args) {
        var order = new Order(42L, new Address("123 Main", "Springfield"));
        System.out.println(extractCity(order));
    }
}