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);
    }
}