Why Upgrade from Java 8 to Java 17? A Practical Guide with Multi‑Release JARs

1. Introduction

Java 17, an LTS version, has been released for over half a month. Many applications still run on older Java versions such as Java 8 or Java 11. This article explains why you should upgrade and helps you perform the migration to Java 17.

Common reasons to upgrade include compact strings (Java 9), the new HttpClient (Java 11), switch expressions (Java 12), text blocks (Java 13), records and pattern matching (Java 14), etc.

Each new Java release brings substantial garbage‑collector improvements, making the runtime faster and more memory‑efficient.

2. What needs to change during the upgrade?

Your code and its dependencies may break if removed APIs are used. Ensure dependencies are up‑to‑date and check for framework versions that support the target Java release. Deprecated APIs are first marked before removal; jumping directly from Java 8 to Java 17 can hit many pitfalls.

For detailed API changes, consult resources such as “The Java Version Almanac” by Marc Hoffmann and Cay Horstmann.

3. Multi‑release JARs

If some components must remain compatible with older JDKs, Java 9’s multi‑release JAR feature (JEP 238) allows packaging different class versions in a single JAR.

Example: an Application class that runs on any JDK and a Student class compiled for Java 8.

public class Application {
    public static void main(String[] args) {
        Student student = new Student("James ");
        System.out.println("Implementation " + student.implementation());
        System.out.println("Student name James contains a blank: " + student.isBlankName());
    }
}

Java 8 version of Student:

public class Student {
    private final String firstName;
    public Student(String firstName) { this.firstName = firstName; }
    boolean isBlankName() { return firstName == null || firstName.trim().isEmpty(); }
    static String implementation() { return "class"; }
}

Java 14 record version (Java 11+ API):

public record Student(String firstName) {
    boolean isBlankName() { return firstName.isBlank(); }
    static String implementation() { return "record"; }
}

Build‑tool configuration (e.g., Maven) can produce a JAR that uses the record on Java 17 and the class on older runtimes. See the author's GitHub repository for a complete example.

4. Deprecated and removed features

Before upgrading, update your IDE, build tools, and dependencies. Plugins such as Maven Versions Plugin or Gradle Versions Plugin help list outdated libraries.

Some modules have been relocated, e.g., JAXB moved from javax.xml.bind:jaxb-api to jakarta.xml.bind:jakarta.xml.bind-api. Use tools like Old GroupIds Alerter to detect such changes.

JavaFX was removed from the JDK after Java 11; you can add it from Gluon or OpenJFX.

Fonts were removed after Java 11; on Linux you may need to install fontconfig manually.

Java Mission Control is now a separate download (JDK Mission Control).

Java EE modules were removed in Java 11; replace them with Jakarta EE equivalents (e.g., jakarta.xml.bind.*).

Table 1 (image) lists removed Java EE modules and their replacements.

Other removals include CORBA (no official replacement), Nashorn (add nashorn‑core dependency if needed), and experimental GraalVM compilers (removed in Java 17, see JEP 410).

5. Finding unsupported class files

Errors like “Unsupported class file major version 61” indicate that a library or plugin does not support Java 17. Upgrade the offending tool to a version that targets the new JDK.

6. JDK internal APIs

Java 16/17 encapsulate internal APIs, affecting frameworks such as Lombok. Update dependencies to avoid using these APIs. As a last resort, you can open modules with

--add-opens=jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED

, but it is better to stop using internal APIs.

7. Conclusion

Upgrade dependencies and replace removed features to avoid most issues. Follow a structured approach: ensure the code compiles, run tests, then run the application. Communicate the migration plan to your team and organization to make the transition smoother.

The author's open‑source microservice component mica already supports Java 17, and the latest MyBatis‑Plus version is compatible as well.