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

2. Never catch Exception broadly — catch specific exceptions. Never swallow exceptions silently.

3. Optional for nullable returns — never for parameters:

   // ✅ Return type
   public Optional<Task> findById(String id) { ... }
   
   // ❌ Parameter — use overloading or @Nullable instead
   public void process(Optional<String> filter) { ... }

Interfaces and DI

1. Program to interfaces, inject via constructor:

   // ✅ Interface in consumer package
   public interface TaskStorage {
       Task getById(String id);
       void save(Task task);
   }
   
   // ✅ Constructor injection (Spring auto-wires)
   @Service
   public class TaskService {
       private final TaskStorage storage;
       public TaskService(TaskStorage storage) { this.storage = storage; }
   }

2. Prefer constructor injection over @Autowired field injection. No field injection — ever.