Understanding Guarded Patterns in Java

Guarded Patterns in Java

In modern programming, especially when dealing with complex conditional logic, simplifying the code and enhancing readability is crucial. Guarded patterns provide a clean and expressive way to handle such logic, ensuring that your programs are both robust and easy to understand. 

A Guarded Pattern is a programming construct to enhance pattern matching capabilities. It allows the inclusion of additional conditions (guards) alongside patterns in switch expressions or statements. These guards ensure that the pattern is matched only when the condition evaluates to true.

In this article, we will explore guarded patterns in Java, their purpose, usage, and implementation, complete with detailed code examples.

What Are Guarded Patterns?

Guarded patterns are conditional constructs that help in expressing business logic more concisely and clearly. They allow developers to specify conditions ("guards") that must be satisfied before certain code is executed. While not a native feature in Java, the concept can be implemented using existing Java constructs like:

1. Switch expressions with pattern matching

2. If-else chains with predicates

3. Optional chaining

Key Use Cases for Guarded Patterns

1. Pattern Matching in Switch Statements: Simplifies complex conditional logic.

2. Input Validation: Ensures preconditions are met before proceeding.

3. Conditional Execution: Executes specific code blocks based on guards.

Syntax of Guarded Patterns

Guarded patterns in Java are defined with the when keyword:

switch (object) {
    case Type pattern when (condition) -> action;
    default -> defaultAction;
}

Here:

• Type specifies the expected type.

• pattern is the matched pattern.

• when (condition) is the guard condition.

Pattern Label Dominance in Guarded Patterns vs. Normal Patterns

• Dominance in Normal Patterns

Normal patterns rely on the specificity and order of the labels. Overlapping patterns must be ordered so that more specific ones come first.

Example:

switch (object) {
    case Integer i -> System.out.println("Integer");
    case Number n -> System.out.println("Number");
}

Here, Integer dominates over Number due to its specificity.

• Dominance in Guarded Patterns

Guarded patterns add an extra layer of complexity by including conditions. A guarded pattern is dominant only if both its pattern and condition are more specific than any other matching case.

Example:

switch (object) {
    case Integer i when (i > 10) -> System.out.println("Large Integer");
    case Integer i -> System.out.println("Integer");
}

Here, the first case dominates when i > 10.

• Dominance for Constant Labels in Guarded Patterns vs. Normal Pattern

Constant labels maintain precedence, but the guard modifies when the label is considered dominant.

Example:

switch (object) {
    case "Admin" when (isAdminActive()) -> System.out.println("Active Admin");
    case "Admin" -> System.out.println("Inactive Admin");
}

---

Scope of Pattern Variables in Guarded Patterns

The scope of variables declared in patterns is limited to the guard clause and the associated action. They are not accessible outside their case.

Example: Let’s dive into practical examples.

• Example 1: Guarded Patterns with Switch Expressions

Java 17 introduced pattern matching for switch expressions, which can be combined with guards for expressive conditional logic.

sealed interface Shape permits Circle, Rectangle {}

final class Circle implements Shape {
    double radius;
    Circle(double radius) { this.radius = radius; }
}

final class Rectangle implements Shape {
    double length, width;
    Rectangle(double length, double width) {
        this.length = length;
        this.width = width;
    }
}

public class GuardedPatternExample {
    public static void main(String[] args) {
        Shape shape = new Circle(5.0);

        String description = switch (shape) {
            case Circle c && (c.radius > 0) -> "A circle with radius " + c.radius;
            case Rectangle r && (r.length > 0 && r.width > 0) ->
                "A rectangle with dimensions " + r.length + " x " + r.width;
            default -> "Unknown shape or invalid dimensions";
        };

        System.out.println(description);
    }
}

Explanation

• The && operator in case statements acts as a guard.

• Only when the guard condition evaluates to true will the corresponding code block execute.

• Example 2: Guarded Patterns for Input Validation

Validating input before performing operations is a common requirement. Using guarded patterns can make the validation logic cleaner.

public class InputValidationExample {
    public static void main(String[] args) {
        String input = "12345";

        boolean isValid = validateInput(input);
        System.out.println(isValid ? "Valid input" : "Invalid input");
    }

    static boolean validateInput(String input) {
        return switch (input) {
            case String s && (s.length() > 3 && s.matches("\\d+")) -> true;
            default -> false;
        };
    }
}

Explanation

• The validateInput method uses a guarded pattern to ensure that the input is numeric and longer than three characters.

• Example 3: Using Guarded Patterns in Custom Logic

Consider a scenario where you want to categorize people based on age and profession.

public class GuardedPatternCategorization {
    public static void main(String[] args) {
        record Person(String name, int age, String profession) {}

        Person person = new Person("Alice", 30, "Engineer");

        String category = switch (person) {
            case Person p && (p.age < 18) -> "Minor";
            case Person p && (p.age >= 18 && p.age < 60) && ("Engineer".equals(p.profession)) -> "Working Engineer";
            case Person p && (p.age >= 60) -> "Senior Citizen";
            default -> "Unknown";
        };

        System.out.println("Category: " + category);
    }
}

Explanation

• Multiple guards can be applied to refine the matching logic.

• This approach avoids deeply nested if-else chains.

• Example 4: Combining Guarded Patterns with Optional

Guarded patterns can be combined with the Optional class to handle nullable or optional values elegantly.

import java.util.Optional;

public class GuardedPatternsWithOptional {
    public static void main(String[] args) {
        Optional<String> optionalName = Optional.of("John");

        String message = optionalName
            .filter(name -> name.length() > 3)
            .map(name -> "Hello, " + name)
            .orElse("Name is too short or not present");

        System.out.println(message);
    }
}

Explanation

• Guards are implemented through filter to validate the conditions.

• map applies the transformation only if the condition is satisfied.

• Example 5: Guarded Patterns in Collections

When working with collections, guarded patterns can be used to filter and process elements conditionally.

import java.util.List;

public class GuardedPatternsInCollections {
    public static void main(String[] args) {
        List<Integer> numbers = List.of(1, -2, 3, -4, 5);

        numbers.stream()
            .filter(num -> num > 0) // Guard condition
            .forEach(num -> System.out.println("Positive number: " + num));
    }
}

Explanation

• The filter method acts as a guard to allow only positive numbers.

• Example 6: Guarded Patterns for Error Handling

Guarded patterns can streamline error-handling mechanisms by checking preconditions before executing code blocks.

public class GuardedPatternErrorHandling {
    public static void main(String[] args) {
        try {
            processOrder(-5);
        } catch (IllegalArgumentException e) {
            System.out.println(e.getMessage());
        }
    }

    static void processOrder(int quantity) {
        if (quantity <= 0) {
            throw new IllegalArgumentException("Quantity must be positive");
        }

        System.out.println("Order processed with quantity: " + quantity);
    }
}

---

Advanced Use Case: Combining Guarded Patterns and Functional Programming

With the introduction of guarded patterns in Java, developers can now craft solutions that combine the expressiveness of pattern matching with the power of functional programming. This synergy allows for the creation of clean, concise, and maintainable code, especially in scenarios that involve complex data transformations and validations.

Why Combine Guarded Patterns and Functional Programming?

1. Enhanced Readability: Guarded patterns reduce nested conditionals, while functional programming promotes concise expressions.

2. Modularity: Functions as first-class citizens can complement guarded patterns by encapsulating reusable logic.

3. Error Reduction: Clear separation of pattern matching and business logic minimizes errors.

4. Expressive Control Flows: Combining these paradigms allows for declarative and expressive code structures.

Syntax Overview

switch (object) {
    case Type pattern when (condition) -> action;
    default -> defaultAction;
}

Combined with functional programming:

list.stream()
    .filter(obj -> matchesPattern(obj))
    .map(obj -> transform(obj))
    .forEach(System.out::println);

Practical Examples

Example #1: Processing Events with Functional Pipelines

Scenario: You are building an event processor that handles various types of events based on their priority and type.

sealed interface Event permits HighPriority, LowPriority {}
record HighPriority(String message) implements Event {}
record LowPriority(String message) implements Event {}

void processEvents(List<Event> events) {
    events.stream()
          .forEach(event ->
              switch (event) {
                  case HighPriority e when (e.message.contains("Critical")) ->
                      handleCriticalEvent(e);
                  case LowPriority e when (e.message.contains("Info")) ->
                      handleInfoEvent(e);
                  default ->
                      logUnhandledEvent(event);
              }
          );
}

void handleCriticalEvent(HighPriority event) {
    System.out.println("Handling critical event: " + event.message);
}

void handleInfoEvent(LowPriority event) {
    System.out.println("Handling informational event: " + event.message);
}

void logUnhandledEvent(Event event) {
    System.out.println("Unhandled event: " + event);
}

Functional Aspects:

• Stream API: Used to iterate over events.

• Guarded Patterns: Enable conditional processing of events based on type and content.

Example #2: Validating User Input with Guards and Lambdas

Scenario: Validate user input based on roles and permissions.

record User(String name, String role, boolean isActive) {}

void validateUsers(List<User> users) {
    users.stream()
         .filter(user ->
             switch (user) {
                 case User u when ("Admin".equals(u.role) && u.isActive) -> true;
                 case User u when ("Guest".equals(u.role) && !u.isActive) -> true;
                 default -> false;
             }
         )
         .forEach(user -> System.out.println("Valid user: " + user.name));
}

Functional Aspects:

• Filtering: Guarded patterns combined with filter allow selective processing.

• Lambdas: Enable concise iteration.

Example #3: Dynamic Data Transformation Using Streams and Guards

Scenario: Transform data objects based on their type and attributes.

sealed interface Shape permits Circle, Rectangle {}
record Circle(double radius) implements Shape {}
record Rectangle(double length, double breadth) implements Shape {}

List<String> transformShapes(List<Shape> shapes) {
    return shapes.stream()
                 .map(shape ->
                     switch (shape) {
                         case Circle c when (c.radius > 10) -> "Large Circle with radius: " + c.radius;
                         case Rectangle r when (r.length == r.breadth) -> "Square with side: " + r.length;
                         case Rectangle r -> "Rectangle: " + r.length + " x " + r.breadth;
                         default -> "Unknown shape";
                     }
                 )
                 .toList();
}

Functional Aspects:

• Mapping: Combines guarded patterns with map for dynamic transformation.

• Declarative Style: Avoids imperative conditionals.

Best Practices

1. Minimize Complexity: Avoid overly complex guards to maintain readability.

2. Reuse Logic: Encapsulate reusable conditions into methods or lambdas.

3. Combine Judiciously: Use functional programming constructs where they enhance clarity and performance.

4. Debugging: Ensure proper logging for unmatched cases in guarded patter

Guarded Patterns and Exhaustiveness

When using guarded patterns, it's important to note that the Java compiler does not consider them when determining the exhaustiveness of a switch statement. 

A switch statement is considered exhaustive when it accounts for all possible values of the selector expression. In Java, ensuring exhaustiveness is essential to prevent runtime exceptions due to unhandled cases. Traditionally, this is achieved by including all possible cases or a default case.

This means that even if your guarded patterns logically cover all possible scenarios, the compiler requires an unguarded pattern or a default case to ensure exhaustiveness.

Consider the following example:

public class Main {
    public static void main(String[] args) {
        RecordB recordB = new RecordB(true);

        switch (recordB) {
            case RecordB b when b.bool() -> System.out.println("It's true");
            case RecordB b when !b.bool() -> System.out.println("It's false");
        }
    }

    record RecordB(boolean bool) { }
}

In this code, both cases are guarded patterns. While they seem to cover all boolean possibilities (true and false), the compiler will raise an error indicating that the switch statement does not cover all possible input values. This is because the compiler does not evaluate the when conditions for exhaustiveness.

Ensuring Exhaustiveness with Guarded Patterns

To ensure that your switch statement is exhaustive when using guarded patterns, you should include an unguarded pattern or a default case. This approach guarantees that all possible input values are accounted for, satisfying the compiler's requirements.

Revising the previous example:

public class Main {
    public static void main(String[] args) {
        RecordB recordB = new RecordB(true);

        switch (recordB) {
            case RecordB b when b.bool() -> System.out.println("It's true");
            case RecordB b when !b.bool() -> System.out.println("It's false");
            default -> throw new IllegalStateException("Unexpected value: " + recordB);
        }
    }

    record RecordB(boolean bool) { }
}

Here, the default case ensures that the switch statement is exhaustive, even though logically, the guarded patterns cover all scenarios.

Java 23 Support for Primitive types

With Java 23, there is a support for both primitive types in patterns and reference types. Please note that the primitive type is still in preview feature and it can change in future release. Here is detailed article on Primitive Types in Patterns, instanceof, and switch in Java 23 and I have also included example for guarded pattern for primitive types usecase

Conclusion

Guarded patterns in Java enhance code clarity, reduce redundancy, and make conditional logic more expressive. While Java does not have native support for guarded patterns as in some functional languages, the combination of features like switch expressions, pattern matching, and functional programming constructs provides powerful alternatives. By adopting these techniques, developers can write clean, concise, and maintainable code.

Incorporating guarded patterns into your projects will help you handle complex logic more elegantly, leading to more robust and readable applications.

Last Words

Sometimes, you will face issues like 

patterns in switch are not supported at language level '17' for which you will need to update to Java 21 for guarded patterns.
If you are looking for JEP reference for guarded patterns here are those:

https://openjdk.org/jeps/441

https://openjdk.org/jeps/406

And here is detailed documentation of Guarded Patterns: https://docs.oracle.com/en/java/javase/21/language/pattern-matching-switch.html