Java and JVM Project Structure, Source Sets, Compilation, Testing, Packaging, and Toolchains: Configuration, Design Choices, and Tradeoffs

1. A build design is a set of contracts

The best build layout is not the one with the most knobs. It is the one that makes important contracts obvious: where production/test code lives, what Java release consumers can rely on, which JDKs are allowed to compile/test, what artifact is produced, and how CI reproduces those choices. Every deviation from convention is a maintenance obligation.

2. Conventional directories versus custom source layout

Convention gives Maven, Gradle, IDEs, code search, and new contributors a shared vocabulary. Custom layouts are sometimes required for legacy migration, generated sources, mixed-language repositories, or integration-test separation, but they should solve a concrete problem.

If a custom directory is chosen, document who produces it, whether it is authored or generated, which compile task consumes it, and whether it enters the published artifact.

3. Library versus application packaging

A library is primarily consumed by another build through coordinates and metadata. An application is primarily executed and may need a main class, runtime dependency distribution, launcher script, container image, or platform-specific package. A plain JAR can serve either role only if the surrounding runtime contract is clear.

4. Build-runtime JDK versus compiler release target

Running the build on a newer JDK can unlock a supported Maven/Gradle runtime while still producing code for an older deployment baseline. That separation is useful, but only if encoded deliberately. Depending only on JAVA_HOME makes the compiler identity ambient and allows developer/CI drift.

<properties>
  <maven.compiler.release>17</maven.compiler.release>
</properties>

java {
    toolchain { languageVersion = JavaLanguageVersion.of(21) }
}
tasks.withType<JavaCompile>().configureEach {
    options.release = 17
}

The Gradle example says two things: project JVM tasks should use Java 21, and Java compilation should emit/validate against Java 17. Maven can express the release target in the POM and select a different JDK through Maven Toolchains where required.

5. Installed, auto-detected, or provisioned toolchains

Toolchain auto-detection reduces manual path configuration, but “found a JDK” is not a provenance policy. CI images often deliberately preinstall approved JDKs. Auto-provisioning can improve developer ergonomics, but it introduces a download repository and distribution trust decision that should be controlled by organization policy.

6. IDE settings are a developer convenience, not the authoritative CI contract

An IDE can have a project SDK, language level, compiler settings, and its own build delegation behavior. Those settings may be useful, but the repository build must remain authoritative. If “Build in IDE” passes while ./mvnw verify or ./gradlew build fails, diagnose the model/toolchain difference rather than weakening the CLI build.

7. Toolchain convenience has a supply-chain boundary

JDK archives, wrapper distributions, plugins, annotation processors, and dependencies all execute or influence code during the build. An auto-downloaded JDK is therefore not merely “developer tooling”; it is executable input. Prefer trusted vendor/distribution sources, verify wrapper and distribution integrity according to current tooling, and do not give untrusted builds broad credentials.

8. Worked decision — internal Java service with Java 17 production runtime

Assume an organization’s runtime platform is Java 17, developer workstations commonly have JDK 21, and CI uses an approved JDK 21 image. The service has a normal production/test split and publishes an application JAR.

This design is not universally correct; it is correct because each choice matches a stated constraint and has observable evidence.

9. Design anti-patterns

• Changing source directories solely to make the repository “look cleaner.”
• Using targetCompatibility/sourceCompatibility alone when strict API compatibility is required and --release is available.
• Assuming a toolchain’s Java version and the deployment target must always be identical.
• Hard-coding local JDK paths or relying on IDE-only compiler settings.
• Letting toolchain provisioning download from an unreviewed third-party source.
• Packaging test fixtures or test framework classes into the production artifact accidentally.

Knowledge check

Summary

Source layout, packaging, compiler target, build-runtime JDK, and toolchain selection are independent design choices. Prefer conventions until a real requirement justifies deviation, encode compatibility in the repository build, keep IDE state subordinate to CLI/CI, and treat provisioned JDKs as supply-chain inputs.

Official references and version notes

These lessons were finalized against current primary documentation on 2026-08-23. Build-tool, plugin, JDK, repository, and IDE behavior is version-sensitive; verify the exact versions used by your project and CI before applying a production policy.

• Apache Maven — Releases History
• Maven Compiler Plugin — Setting --release
• Apache Maven Toolchains Plugin
• Maven — Guide to Using Toolchains
• Gradle — Java Plugin
• Gradle — Toolchains for JVM Projects
• Gradle — Compatibility Matrix
• JUnit 5.13.4 User Guide