Java instanceof Pattern Matching: Syntax and Scope

java instanceof pattern matching removes the redundant cast that follows a traditional type check. Instead of testing the type and casting in two separate statements, you declare a pattern variable directly in the instanceof expression, and the compiler restricts its scope to the code paths where the type test is guaranteed to have succeeded.

if (obj instanceof String s) {
    System.out.println(s.length());
}

The variable s is a pattern variable. It is implicitly final and its type is String, so no explicit cast is needed. Like the traditional operator, the pattern form returns false for null, which means a pattern variable is never null when it is in scope.

The Problem With Traditional instanceof Casts

Before Java 16, the standard way to check a type and use the value looked like this:

if (obj instanceof String) {
    String s = (String) obj;
    System.out.println(s.length());
}

The cast is redundant because the instanceof check already proved the type. The two statements are separate, so the relationship between them is implicit. If code is inserted between the check and the cast, or if the variable is reassigned, the cast can become unsafe. Pattern matching collapses the check and the binding into one expression, so there is no window in which the relationship can break.

Core Syntax of Pattern Matching

The pattern form follows the shape obj instanceof Type variableName. The type must be a reference type, and the variable name is required. The pattern variable's type is the tested type, so s is String in the example above.

The pattern variable is in scope only where the compiler can prove the instanceof test succeeded. This is called flow scoping, and it applies across the surrounding control flow, not just the immediate block.

if (obj instanceof String s) {
    // s is in scope here
}
// s is not in scope here

The same rule applies in a ternary expression:

String result = (obj instanceof String s) ? s : "default";

And in a while loop, where the condition is re-evaluated each iteration:

while (obj instanceof String s) {
    obj = s.substring(1);
}

In the loop, s is in scope in the body because the condition must have matched for the body to execute.

Flow Scoping Rules

The scope of a pattern variable is determined by the compiler's flow analysis, and the operators around the instanceof change where the variable is available.

With &&, the right operand is only evaluated when the left operand is true, so the pattern variable is in scope there:

if (obj instanceof String s && s.length() > 3) {
    // s is in scope
}

With ||, the right operand may be evaluated when the instanceof failed, so the pattern variable is not definitely assigned. This code does not compile:

if (obj instanceof String s || s.length() > 3) {
    // compile error: s is not definitely assigned
}

With a negated test and an early return, the pattern variable becomes available after the block:

if (!(obj instanceof String s)) {
    return;
}
// s is in scope here
System.out.println(s.length());

The compiler tracks that reaching this point implies the instanceof succeeded. These rules are part of the language specification, so they behave identically across implementations.

Record Patterns

Java 21 added record patterns, which destructure a record's components as part of the type test:

record Point(int x, int y) {}

if (obj instanceof Point(int x, int y)) {
    System.out.println(x + y);
}

The pattern Point(int x, int y) matches any Point and binds x and y to its components. You can use var for components you do not need:

if (obj instanceof Point(int x, var y)) {
    // only x is used
}

Nested patterns combine a record pattern with type patterns:

record Circle(Point center, double radius) {}

if (obj instanceof Circle(Point(int x, int y), double r)) {
    System.out.println("Center: " + x + ", " + y);
}

A nested pattern does not match when a component is null. A Circle whose center is null fails the Point(int x, int y) pattern, so the if body does not execute.

Pattern Matching in Switch

Java 21 also introduced pattern matching for switch, which uses case labels with type patterns and optional when guards:

switch (obj) {
    case String s when s.length() > 3 -> System.out.println("Long string: " + s);
    case String s -> System.out.println("Short string: " + s);
    case Integer i -> System.out.println(i * 2);
    default -> System.out.println("Unknown type");
}

The when clause is the switch equivalent of combining instanceof with &&. Case order matters: the first matching case wins, so more specific patterns must appear before more general ones. Unlike instanceof, a switch over a null value throws NullPointerException unless a case null is present.

Runtime Behavior and Performance

At the bytecode level, the pattern form performs the same instanceof type check as the traditional operator and does not require a separate checkcast instruction, because the compiler already knows the type. The JIT treats both forms equivalently in practice, so the benefit is source-level clarity rather than runtime speed.

The maintainability gain is real. When you refactor a method that uses pattern matching, the compiler catches scope mistakes that would previously require a runtime test. Using a pattern variable outside its valid scope is a compile error, not a ClassCastException.

Compatibility and Migration

The feature arrived in stages:

A codebase targeting Java 17 can use instanceof pattern matching but not record patterns. Java 21 is the first LTS release with all three features.

Migration is incremental. You can replace traditional instanceof plus cast pairs one at a time, and the behavior is identical, so existing tests should pass without modification. The main risk is scope-related: if code relied on a variable being in scope after a negated instanceof, the pattern form changes where the variable is available. In practice, this surfaces as a compile error, not a runtime failure, which is exactly the kind of failure the feature is designed to prevent.