java-idioms

Java Idioms and Patterns

Java rewards clarity, type safety, and robust ecosystem tooling. Modern Java (17+ LTS) favors records, sealed classes, and pattern matching. Idiomatic Java = clean, readable, framework-aware.

Scope: Java coding idioms. Test naming: .agents/rules/testing-strategy.md. Logging: @.agents/skills/logging-implementation/SKILL.md.

Modern Java Features (17+ LTS)

1. Records for immutable data carriers:

   // ✅ Concise, immutable, auto-generated equals/hashCode/toString
   public record CreateTaskRequest(String title, Priority priority) {}
   
   // ❌ Verbose boilerplate POJO
   public class CreateTaskRequest { /* getters, setters, equals, hashCode... */ }
   

2. Sealed classes for constrained hierarchies:

   public sealed interface TaskResult permits Success, Failure, Pending {}
   public record Success(Task task) implements TaskResult {}
   public record Failure(String reason) implements TaskResult {}
   public record Pending(String taskId) implements TaskResult {}
   

3. Pattern matching with switch:

   return switch (result) {
       case Success(var task) -> ResponseEntity.ok(task);
       case Failure(var reason) -> ResponseEntity.badRequest().body(reason);
       case Pending(var id) -> ResponseEntity.accepted().body(id);
   };
   

4. Text blocks for queries and templates:

   String query = """
       SELECT t.id, t.title, t.priority
       FROM tasks t
       WHERE t.user_id = ?
       ORDER BY t.created_at DESC
       """;
   

5. Virtual threads (21+) for I/O-bound work:

   try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
       executor.submit(() -> fetchUser(userId));
       executor.submit(() -> fetchTasks(userId));
   }
   

Error Handling

1. Domain exception hierarchies — never raw Exception:

   public abstract class DomainException extends RuntimeException {
       protected DomainException(String message) { super(message); }
   }
   
   public class NotFoundException extends DomainException {
       private final String resource;
       private final String resourceId;
       public NotFoundException(String resource, String resourceId) {
           super(String.format("%s '%s' not found", resource, resourceId));
           this.resource = resource;
           this.resourceId = resourceId;
       }
   }