Sealed types and pattern matching

Records gave you a tidy way to hold data: a circle is its radius, a rectangle is its width and height. As soon as a program holds several kinds of record, it keeps asking the same question: which kind is this one, and what is inside it? This lesson gives you Java's tools for that question. You will test a value's type and unpack its parts in a single step, and you will close a family of types so the compiler can check that you handled every member.

The old way: check, then cast#

Picture a small drawing app with three kinds of shape. A circle is a radius, a rectangle is a width and a height, and a triangle is a base and a height. That is plain data, so each kind is a record. The rectangle is called Rect to keep the lines short.

An interface called Shape ties the three together, so that one array can hold them all. Shapehas no methods yet. It only says “all of these are shapes”.

Now the app needs the area of any shape. With what you learned in polymorphism, you check the kind with instanceof, then cast to reach the record's accessors.

It prints 3.141592653589793, 12.0 and 6.0. It works, but read one branch out loud: “if shape is a Circle, declare a Circle called c, and set it to shape cast to Circle.” That is the word Circle three times for one idea.

The repetition also hides a trap. The test and the cast are separate lines, and Java does not connect them. A copy-paste slip such as Rect r = (Rect) shape; inside the triangle branch compiles without complaint, then stops the program with a ClassCastException the first time a triangle arrives. And the last line, return 0;, is there only because the compiler cannot tell whether the three checks cover every possible shape.

The instanceof pattern: test and name in one step#

Since Java 16 you can put a variable name straight after the type in an instanceof test: shape instanceof Circle c. Read it as “is shape a Circle? If so, call it c”. When the test passes, Java creates c, already typed as Circle and already holding the shape. When the test fails, there is no c at all. You never write the cast yourself, so you cannot cast to the wrong type.

This is your first pattern: a description of what a value should look like, plus names for the parts you want if it does. Checking a value against a pattern is called pattern matching. Circle c is a type pattern, a type to test for and a name to use, and c is its pattern variable.

Same three areas, and each branch now names its type once. Step through it and watch the trace: c, r and t each appear only inside the branch whose test passed.

Where the pattern variable exists

A pattern variable exists only where Java can be sure the test passed. Java works that out from the logic around the test, and these are the cases you will meet most:

• After &&, it exists. In shape instanceof Circle c && c.radius() > 10 the right side only runs when the left side was true, so c is ready to use.
• After ||, it does not. In shape instanceof Circle c || c.radius() > 10 the right side runs exactly when the shape is not a circle, so there is no circle to ask. javac stops with cannot find symbol.
• Below a negated test that returns, it exists. Write if (!(shape instanceof Rect r)) return ...; and every line after that if can only be reached by a rectangle, so r works for the rest of the method.

The loop prints a single line, Big circle: Circle[radius=12.0]. The small circle fails the size check and the rectangle fails the type check. Then squareCheck prints a square with side 5.0, a rectangle, but not a square and not a rectangle.

Look at how squareCheck begins. It deals with the odd case first and returns, so the rest of the method reads as the normal path, with r ready and no extra level of indentation.

Patterns in a switch#

A quick recap: the arrow form of switch

You met the arrow form and switch expressions in making decisions: after an arrow only that case's code runs, with no fall-through and so no break, and a switch can produce a value. This lesson puts patterns into that form. Here it is on a plain number once more.

It prints rectangle. One rule from that lesson matters again below: a switch expression must produce a value whatever comes in. An int can hold over four billion different values and the cases cover three of them, so the default line is required.

Type patterns in case labels

A case label can hold a type pattern, the same Circle c you wrote after instanceof. Java tries the cases from top to bottom and runs the first one that matches. Here is the area method again:

The same three areas come out. The method now reads like a table: a circle uses this formula, a rectangle that one, a triangle the third.

Why is the default there? Shape is an ordinary interface, so any class in any file may implement it. Tomorrow someone could write record Hexagon(double side) implements Shape {}, and this switch has no case for it. A switch expression must produce a value for every possible shape, and with an open interface that takes a catch-all case, which is what default is. Delete it and javac refuses with the switch expression does not cover all possible input values. Hold on to that: two sections from now, a new keyword makes the default unnecessary.

Guards: case ... when

Sometimes the type alone is not enough. A rectangle whose width equals its height is a square, and the app should say so. You can add a condition to a case with the word when. The condition is called a guard.

case Rect r when r.width() == r.height() matches when the shape is a rectangle and the condition is true. The guard can already use r. If the shape is a rectangle but the condition is false, Java carries on to the next case, case Rect r, which takes every other rectangle. The circles work the same way, so the four lines are a square of side 2.0, a 2.0 by 5.0 rectangle, a dot and a circle of radius 3.0.

Order matters. Put a guarded case above the plain case for the same type. If case Rect r came first, it would take every rectangle, squares included, and the square case could never run. javac rejects that with this case label is dominated by a preceding case label. A case is dominated when a case above it already matches everything it could match. The habit that avoids it: specific cases first, general ones last.

case null

A Shape variable can also hold null, the value that means “no object”. A switch on null stops the program with a NullPointerException, and a default does not catch it. If null is a value you expect, give it a case of its own:

This prints nothing picked yet. When null and every unmatched shape deserve the same answer, put both on one line: case null, default -> "something else";.

Key idea

A switch with patterns tries its cases from top to bottom and runs the first one that matches. A guard narrows a case; when the guard is false, the search carries on below.

Record patterns: unpack the parts#

Look at what the area cases do with their variable: case Rect r -> r.width() * r.height(). The only reason to name the rectangle r is to call its two accessors. A record pattern skips that step. It checks the type and lifts the components straight out into variables of their own:

Read Rect(double w, double h)as “a Rect, whose width I will call w and whose height I will call h”. It is new Rect(3.0, 4.0)run backwards. Construction puts values in, in the order of the record's header, and the record pattern takes them out in the same order. Java calls the accessors for you.

The names are yours to choose, which is why the triangle's base can be b here. The order and the types must fit the record.

var: let Java fill in the types

Writing double for every component gets repetitive. Inside a pattern you may write var instead, and Java uses the component's own type: Rect(var w, var h) still gives you two double variables. (var works for ordinary local variables too, which you will meet in modern Java syntax.)

A record pattern can carry a guard, and it works after instanceof as well:

The first four lines come from describe, where the guard when w == h uses the unpacked width and height directly. The last line comes from the if: picked instanceof Rect(var w, var h) && w == h tests the type, unpacks the rectangle and compares its sides in one condition, and prints The second shape is a square of side 2.0.

1public class Main {
2    public static void main(String[] args) {
3        Shape[] shapes = { new Rect(3.0, 3.0), new Rect(3.0, 5.0), new Circle(3.0) };
4        for (Shape shape : shapes) {
5            System.out.println(shape + " is a square: " + isSquare(shape));
6        }
7    }
8 
9    static boolean isSquare(Shape shape) {
10        // TODO: return true only for a Rect whose width equals its height.
11        // Use instanceof with a record pattern.
12        return false;
13    }
14}
15 
16interface Shape {}
17record Circle(double radius) implements Shape {}
18record Rect(double width, double height) implements Shape {}

Nested record patterns

A record can hold another record. In the drawing app a sticker has a shape and a color: record Sticker(Shape shape, String color) {}. A record pattern can hold another record pattern in a component's place, so one case can unpack the sticker and the shape inside it.

Sticker(Circle(var r), var color)matches only a sticker whose shape is a circle, and it hands you the circle's radius and the sticker's color together. A nested pattern matches only if every part matches. If the inside does not fit, Java moves on to the next case. So the first two stickers print a red circle, radius 2.0 and a blue square.

The last case, Sticker(var shape, var color), takes any sticker at all, because var accepts whatever is in its slot. That is why this switch needs no default. The green triangle lands there and prints the shape through the record's toString: a green Triangle[base=3.0, height=4.0].

2.0
4.0
6.0

Sealed types: closing the family#

Every switch over Shape so far has needed a default, because Shape is open: any class anywhere may implement it. But the drawing app has exactly three shapes, and you would like Java to know that too. Since Java 17 you can say so:

sealed means the family is closed, and permits is its guest list: only the types named there may implement Shape. Try to add a fourth shape that is not on the list, such as record Star(int points) implements Shape {}, and javac stops you with class is not allowed to extend sealed class: Shape (as it is not listed in its 'permits' clause). The message says “class” and “extend” even for an interface and a record; it uses the general words.

Every member says what comes below it

A sealed type lists its direct members. Each member must then say whether the family goes on below it, with one of three modifiers:

Leave the modifier off and javac complains: sealed, non-sealed or final modifiers expected. The shapes above needed none of this, because a record is automatically final. Nothing can extend a record.

Sealed classes

sealed works on classes too. Here an abstract class closes its family, and its three members use one modifier each:

Car is final, so that branch ends there. Truck is sealed with a list of its own, so only FireTruck may extend it. Bike is non-sealed, so any class may extend it, and RacingBike does without appearing on any list.

The switch still handles every vehicle. case Truck t takes plain trucks, because the fire truck was already taken by the case above it. case Bike b takes every bike, including kinds nobody has written yet. The output is a car with 4 wheels, a truck with 6 wheels, a fire truck with a ladder, then a bike with 2 wheels twice.

One more detail lets this switch skip the default: Vehicle is abstract, so no object is ever a plain Vehicle. If it were not abstract, the switch would need a case for Vehicle itself.

Key idea

A sealed type names every direct member. Each member is final (nothing below it), sealed (its own short list) or non-sealed (open to anyone).

Exhaustiveness: the compiler checks every case#

Because Shape is sealed, the compiler knows that a shape can only be a circle, a rectangle or a triangle. A switch that handles those three handles every shape there can ever be, so the default can go:

A switch that handles every possible value is exhaustive. Java checks that every switch expression is exhaustive when it compiles your code, before anything runs. With an open interface you needed a catch-all such as default to pass that check. With a sealed one, listing every member is enough.

When you forget a case

Take the same program, delete the triangle case, and compile it with a real JDK:

Read it the way you read any compile error: the file and line (Main.java:10), the complaint, and a caret under the switch. The message does not say which kind is missing. You find it by comparing the cases with the permits list. You find out while compiling, at your desk, long before a user draws the first triangle.

Adding a new member

The check earns its keep when the family grows. Say the app gets squares. You write record Square(double side) implements Shape {} and add Square to the permits list. Every switch over Shape that has no square case and no default now fails to compile, each with the error above. Together those errors are a complete to-do list of the places where squares need a decision.

Now imagine those switches had kept a default. Everything compiles, and every square quietly takes the default branch: an area of 0, a description of “some other shape”. Nothing tells you. That is why, for a sealed type, you list every member and leave default out.

Key idea

Over a sealed type, leave out default. Then adding a member turns every switch that forgot it into a compile error: a to-do list you can trust.

The fine print

• A guarded case never counts. case Rect r when r.width() > 10 on its own does not cover rectangles, because its condition could be false, so you still need a case for the rest. Java does not try to reason about what the condition says.
• The rule also covers switch statements that use patterns or case null. Such a switch must be exhaustive even when it produces no value, and javac then reports the switch statement does not cover all possible input values. An old-style switch on an int, a String or an enum, with no patterns, still does not have to be.
• A chain of if and instanceof gets no such check at all, sealed type or not. Exhaustiveness checking comes only with a switch.

Try the rule for yourself below. Comment cases out, bring them back, add a Square to the family, and read javac's verdict. When the switch compiles, send a value through and see which case takes it.

Two ways to give every shape an area#

Step back and compare all this with polymorphism. There, each class carried its own version of a method, and Java picked the right version at run time. The shapes can work that way too. The interface declares area(), and each record supplies its own:

Same output, and no switch anywhere: the loop calls shape.area() and each record answers for itself. Neither version is wrong. They arrange the same pieces of code in two directions, which is easiest to see as a table.

A method in every class cuts this table into rows. Each record holds its own row: every job, for one kind of shape. A switch cuts the table into columns. Each method holds one column: one job, for every kind of shape.

The column style has a name: data-oriented programming. In plain words, you keep the data as plain records, close the set of kinds with sealed, and write each operation as a method with a switch over that set. The records know nothing about drawing or describing; each operation knows how to handle every kind.

Each style makes a different change easy. With a method in every class, a new kind is one new class and nothing else changes, but a new job means editing every class. With switches, a new job is one new method and the records stay as they are, while a new kind means visiting every switch. The compiler makes that visit safe by naming each switch you must touch.