Understanding and Solving `java.lang.NoClassDefFoundError: javax/xml/bind/JAXBException` in Java 9+

Introduction

When transitioning from JDK 6/7/8 to JDK 9+, developers using JAXB (Java Architecture for XML Binding) may encounter the java.lang.NoClassDefFoundError: javax/xml/bind/JAXBException. This error arises due to significant changes in how Java handles its standard libraries starting with Java 9. Specifically, JAXB classes are no longer included by default on the classpath in these newer JDK versions. This tutorial explains why this error occurs and provides solutions for both quick fixes and long-term handling across different JDKs.

Background

What is JAXB?

JAXB is a framework that allows Java developers to map Java objects to XML representations. It facilitates easy conversion between XML data and Java objects, which is particularly useful in applications involving communication with web services or reading/writing configuration files.

Changes Introduced by Java 9+

Java 9 introduced the concept of modules through Project Jigsaw, altering how libraries are packaged and accessed. This modular system aimed to provide better encapsulation and maintainability but resulted in certain standard APIs, like JAXB, being removed from the default classpath (from JDK 11 onwards).

The Problem

When running applications that depend on JAXB in Java 9+, you might encounter the java.lang.NoClassDefFoundError for javax/xml/bind/JAXBException. This is because:

JDK 9: Modules such as java.xml.bind, which contains JAXB, are no longer included by default.
JDK 11 and later: These modules are completely removed from the JDK.

Solutions

Quick Fixes (For Java 9/10)

If you’re working with Java 9 or 10, there are a few quick ways to address this issue:

Add JAXB Module at Runtime:

You can include the java.xml.bind module using the following command-line option when running your application:
```
--add-modules java.xml.bind
```
Include All Java EE Modules (Java 9/10 only):

Alternatively, you can make all Java EE modules available by specifying:
```
--add-modules java.se.ee
```
Note that this approach will not work in Java 11 as java.se.ee was removed.
Environment Variable Approach:

For mixed environments (Java 8 and above), set the JDK_JAVA_OPTIONS environment variable to include necessary modules:
```
JDK_JAVA_OPTIONS=--add-modules java.xml.bind
```
Ignoring Unrecognized Options:

Use the JVM option -XX:+IgnoreUnrecognizedVMOptions for running Java 9+ applications on older JDKs without causing errors due to unrecognized options.

Long-term Solutions (For JDK 11 and Beyond)

Since JAXB modules are removed from JDK starting with version 11, you’ll need to include them externally in your project:

Add JAXB Dependencies Manually:

Use Maven or Gradle dependencies to add the necessary libraries manually.

For Maven, add these dependencies to your pom.xml file:

<dependency>
    <groupId>jakarta.xml.bind</groupId>
    <artifactId>jakarta.xml.bind-api</artifactId>
    <version>4.0.0</version>
</dependency>

<dependency>
    <groupId>org.glassfish.jaxb</groupId>
    <artifactId>jaxb-runtime</artifactId>
    <version>4.0.0</version>
</dependency>

For Gradle, add these dependencies to your build.gradle file:

dependencies {
    implementation 'jakarta.xml.bind:jakarta.xml.bind-api:4.0.0'
    implementation 'org.glassfish.jaxb:jaxb-runtime:4.0.0'
}

Use Alternative Implementations:

Consider using alternative implementations like EclipseLink MOXy if specific features or compatibility are required.

Note on Package Changes

With the move to Jakarta EE, package names have changed from javax.xml.bind to jakarta.xml.bind. Ensure your source code is updated accordingly when using newer JAXB versions.

Conclusion

The transition away from including JAXB in JDKs post-9/11 requires developers to adapt their project setups either by temporarily adding modules or migrating to external dependencies. By understanding these changes and applying the solutions discussed, you can ensure smooth usage of JAXB across different Java versions.