Source/Target Compatibility

What Source/Target Compatibility Controls — and Why It's Not One Setting

The previous page established that compile time and runtime are genuinely separate phases. Source/target compatibility is where that distinction becomes a compiler flag: source controls which language syntax javac will accept from your .java files, and target controls which bytecode version it emits for the JVM to run later — potentially a much older JVM than the one doing the compiling. Developing on JDK 21 while deploying to a fleet of Java 11 servers is the ordinary case this exists to handle, and getting it wrong doesn't always fail loudly.

// BEFORE — compiling on JDK 17 for a Java 8 target, using only -source/-target
$ javac -source 8 -target 8 OrderService.java
public class OrderService {
    public boolean isValidCode(String code) {
        return !code.isBlank();   // COMPILES — javac only checks syntax against Java 8,
                                     // it never checks whether isBlank() actually EXISTS
                                     // in Java 8's API. It doesn't; isBlank() is Java 11.
    }
}
// This class compiles cleanly, ships, and throws NoSuchMethodError the moment
// it actually runs on a real Java 8 JVM — a failure -source/-target can't see
// coming, because JDK 17's own bootclasspath was silently used to resolve
// String during compilation.

// AFTER — using --release, which restricts the API surface too
$ javac --release 8 OrderService.java
// error: cannot find symbol
//   symbol: method isBlank()
// Caught at compile time — the build fails HERE, not in production on a
// server that doesn't have this method at all.

The Compiler Options

Using javac directly

# Compile Java 11 syntax, targeting Java 11 bytecode
javac --source 11 --target 11 OrderService.java
javac -source 11 -target 11 OrderService.java   # short form, same effect

# The recommended form since Java 9 — see below for why
javac --release 11 OrderService.java

Source restricts syntax; target restricts bytecode — independently

// With --source 8: this fails — var didn't exist yet
var orders = new ArrayList<Order>();   // Error!

// With --source 11: this compiles fine
var orders = new ArrayList<Order>();   // OK

// --target independently controls the produced class file version —
// a class compiled with --target 11 simply refuses to load on a Java 8 JVM,
// regardless of whether its source used any Java 9+ syntax at all

The --release Option — Why It's the Only Safe Default

Introduced in Java 9, --release sets source and target together, and — this is the part -source/-target cannot do — restricts the visible JDK API surface to exactly what existed in that version, using a bundled symbol table rather than whatever JDK happens to be running the compiler.

# Equivalent in intent to this, but built in and verified — not something
# you'd want to hand-maintain a matching bootclasspath JAR for yourself
javac --release 11 OrderService.java
# vs. the old, fragile manual equivalent:
# javac -source 11 -target 11 -bootclasspath <path-to-jdk11-rt.jar> OrderService.java

Build Tool Configuration

Maven — maven-compiler-plugin

<!-- Recommended: release (Java 9+) -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.13.0</version>
    <configuration>
        <release>17</release>
    </configuration>
</plugin>

<!-- Shorthand: properties section -->
<properties>
    <maven.compiler.release>17</maven.compiler.release>
</properties>

Gradle — Kotlin DSL

// Toolchain — recommended; also selects a matching JDK if one isn't already installed
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(17))
    }
}

// Direct release option on the compile task
tasks.withType<JavaCompile> {
    options.release.set(17)
}

Cross-Compilation — Developing Ahead of Your Deployment Target

// Scenario: develop on JDK 21, deploy to a fleet still running Java 11
<properties>
    <maven.compiler.release>11</maven.compiler.release>
</properties>

// --release 11 rejects every Java 12+ addition at compile time, not deploy time:
// records, sealed classes, pattern matching, text blocks, virtual threads —
// all become compile errors immediately, rather than runtime surprises

Troubleshooting

// "source release X requires target release X or later"
// Cause: target is set lower than source
javac --source 17 --target 11 OrderService.java   // Error — target can't be older than source

// "class file has wrong version X.0, should be Y.0"
// Cause: running bytecode on a JVM OLDER than the target it was compiled for
// — this is the JVM enforcing the class file version check covered in full
// on Version Compatibility

// "cannot find symbol" for an API that clearly exists in your JDK's docs
// Cause: --release is doing its job — that API doesn't exist in the release
// version you specified, even though it exists in the JDK actually running javac

Checking effective settings

# Maven
mvn help:effective-pom | grep -A5 "maven-compiler-plugin"

# Gradle
./gradlew properties | grep -i java

# The actual class file version that was produced
javap -verbose OrderService.class | grep "major version"

Best Practices and Common Pitfalls

Interview Questions