copilot-setting java.instructions.md

Java 8 Conventions

This project is Java 8. AI models default to modern Java, and that pull is strong — treat it as a bias to correct, not a preference to follow. A newer-version symbol won't compile, but the convention and correctness rules below fail only at review or runtime — don't lean on the build to catch them. If you are not certain something exists in Java 8, verify against this file before writing it — never guess.

Language Boundary (Java 9+ Forbidden)

• var, records, sealed classes, text blocks, pattern matching
• List.of(), Map.of(), Set.of() — use Arrays.asList() / Collections.unmodifiableMap() (note: Arrays.asList is fixed-size but element-mutable and allows nulls, unlike List.of — wrap in Collections.unmodifiableList when true immutability matters)
• String.isBlank(), String.strip() — use StringUtils or .trim().isEmpty()
• Optional.ifPresentOrElse(), Optional.stream()
• Module system (module-info.java)
• try-with-resources on a pre-declared effectively-final variable (Java 9) — declare the resource inside the try (...) parentheses instead; try-with-resources itself is Java 7 and stays mandatory for JDBC (instructions/sql.instructions.md)

Optional

• Return type only — never field, parameter, or collection element
• orElse() for cheap defaults; orElseGet() for expensive computation
• orElseThrow(SomeException::new) over .get() — .get() throws cryptic NoSuchElementException. Note: Java 8 requires the supplier form orElseThrow(() -> new ...) — the no-arg orElseThrow() is Java 10+.

Streams

• One operation per line; break chain at .collect()
• Never modify external state inside forEach / map / filter
• Prefer for loop for simple iterations with side effects

Date and Time

• Use java.time (LocalDate, LocalDateTime, ZonedDateTime, Instant, Duration) for business logic, computation, and internal date handling — a Java 8 feature and the default for new code
• Two hard exceptions on this stack — Hibernate 4.2 has no java.time support (that arrived in Hibernate 5's hibernate-java8 module) and JSTL 1.2 <fmt:formatDate> accepts only java.util.Date:
  • hbm.xml-mapped entity date fields stay java.util.Date / java.sql.Timestamp — a LocalDateTime field has no Hibernate 4.2 type mapping (fails, or silently persists as a serialized BLOB)
  • dates passed to a JSP for <fmt:formatDate> stay java.util.Date (instructions/jsp.instructions.md)
• Convert at the service boundary with Date.from(instant) / Date.toInstant() between java.time logic and the persistence / view layers
• Still avoid java.util.Calendar (mutable, error-prone) in new code