java-generic

name	java-generic
description	Universal guidelines, patterns, and best practices for Java development. Use when working on any Java project, class, or backend.
version	2.0.0
kind	guidance
triggers	["work on java project","create java class","java backend"]
intent	execution
guardrails	["Do not use System.out.println; always use SLF4J with a concrete backend (Logback or Log4j2).","Manage all dependencies via Maven (`pom.xml`) or Gradle (`build.gradle`). Never install JARs manually.","Strictly adhere to OOP principles and SOLID design.","Do not swallow checked exceptions; handle them with context-rich logging, or wrap and rethrow as domain-specific unchecked exceptions.","Prefer immutability: `final` fields, `List.of()` / `Map.of()` / `Set.of()`, and records for pure data carriers.","Never use raw types; always parameterize generics (`List<String>`, not `List`)."]
tools	["bash"]
created_at	2026-05-30T00:00:00.000Z
updated_at	2026-07-29T00:00:00.000Z

Java development guidelines

0. Java version target

• Target Java 21 LTS unless the runtime constrains you to an earlier version.
• Prefer modern constructs over legacy alternatives:
  • Records for immutable data carriers instead of boilerplate POJOs.
  • Sealed classes/interfaces to model closed hierarchies (replacing enum abuse).
  • Pattern matching (instanceof patterns, arrow-arm switch) over verbose if-else chains.
  • Text blocks ("""...""") for multiline SQL, JSON templates, etc.
  • var where the type is obvious from context.
  • Virtual threads (Executors.newVirtualThreadPerTaskExecutor()) for I/O-bound concurrency; do not hand-manage pools for such workloads.
  • SequencedCollection when ordering guarantees matter.

1. Environment & SDKMAN

• SDKMAN manages Java, Maven, and Gradle on Linux and macOS.

• Check for and use these if set: SDKMAN_DIR, SDKMAN_CANDIDATES_DIR, SDKMAN_PLATFORM, JAVA_HOME, and the version-specific JAVA11_HOME, JAVA17_HOME, JAVA21_HOME.

• Dependency caches are shared and must not be bypassed. When M2_HOME is set it is the Maven local repository — pass it through rather than letting Maven default to ~/.m2. Same for GOPATH, CARGO_HOME, NPM_CONFIG_CACHE, and PIP_CACHE_DIR in polyglot projects.

  ./mvnw -Dmaven.repo.local="$M2_HOME" <goals>    # when M2_HOME is set
  

2. Build tools & execution

• Always use the project wrapper (./mvnw, ./gradlew) to compile, test, package.
• Never rely on a globally installed Maven or Gradle unless it is explicitly managed through SDKMAN — version mismatches follow.