Check the Implementation

The first time I tried to use MOXy, I was not able to tell whether I had actually configured it correctly. So, first of all, you may want to check which implementation of JAXB is being used for the domain classes you are trying to handle.

The following code checks to see which implementation is used to handle YourDomainClass.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

static final String MOXY_JAXB_CONTEXT = "org.eclipse.persistence.jaxb.JAXBContext";
static final String METRO_JAXB_CONTEXT = "com.sun.xml.bind.v2.runtime.JAXBContextImpl";

private void checkProvider() throws JAXBException {
    JAXBContext jc = JAXBContext.newInstance(YourDomainClass.class);

    String jaxbContextImpl = jc.getClass().getName();
    if(MOXY_JAXB_CONTEXT.equals(jaxbContextImpl)) {
        System.out.println("EclipseLink MOXy");
    } else if(METRO_JAXB_CONTEXT.equals(jaxbContextImpl)) {
        System.out.println("Metro");
    } else {
        System.out.println("Other");
    }
}

Set Up MOXy

Create a jaxb.properties file containing this:

javax.xml.bind.context.factory=org.eclipse.persistence.jaxb.JAXBContextFactory

This file needs to be placed in the same packages as the domain classes you want MOXy to handle.

What does that mean?

Let’s say you have a class called Customer and you want that class to use MOXy. Let’s assume the class is in the org.myself.myapp.mybeans package. Then you must also place the jaxb.properties file in the same location as your Customer.java file - i.e. in the org.myself.myapp.mybeans package.

Later on we will see that you may also need to configure your build process to ensure that this properties file is copied to the same location as the compiled Customer.class file - because that is where the properties file ultimately needs to be located: alongside its related class files.

JAXB Libraries and JARs

The module java.se.ee was removed from Java 11. See JEP-320. This module includes JAXB (and JAX-WS and others). To use JAXB in Java 11 and newer, you therefore need to add it to your project as a separate library. This is shown below, using a Maven POM example.

The contents of my pom.xml are shown below - note that only two dependencies are needed: the JAXB API and an implementation (in our case, MOXy from the EclipseLink project):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

<dependency>  
    <groupId>org.eclipse.persistence</groupId>  
    <artifactId>eclipselink</artifactId>  
    <version>2.7.6</version>  
</dependency>  

<!--   
     Use 2.3.1 below to prevent "illegal   
     reflective access operation" warnings.  
-->  
<dependency>  
    <groupId>javax.xml.bind</groupId>  
    <artifactId>jaxb-api</artifactId>  
    <version>2.3.1</version>  
</dependency>  

<!--

<dependency>  
    <groupId>com.sun.xml.bind</groupId>  
    <artifactId>jaxb-core</artifactId>  
    <version>2.3.0.1</version>  
</dependency>

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

<dependency>  
    <groupId>com.sun.xml.bind</groupId>  
    <artifactId>jaxb-impl</artifactId>  
    <version>2.3.1</version>  
</dependency>  
-->

In the above POM, the following artifacts are shown:

There is also this:

1
2
3
4
5
6

<dependency>
    <groupId>com.sun.xml.bind</groupId>
    <artifactId>jaxb-ri</artifactId>
    <version>2.3.3</version>
    <type>pom</type>
</dependency>

This is a standalone bundle of the Glassfish (Metro) JAXB reference implementation. You can find the xjc and schemagen tools inside this JAR, since these tools are also no longer a part of the core Java distribution. You can download the JAR from here, unzip it, and then look in the bin directory to find the tools' binaries.

Deploy MOXy

Remember to ensure the MOXy properties file is copied from the source folder to the correct target, as part of the Maven/Ant/Gradle build process.

For a Maven-based project, the following section will ensure the properties file is copied correctly:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<build>  
    <resources>  
        <resource>  
            <directory>src/main/java</directory>  
            <excludes>  
                <exclude>**/*.java</exclude>  
            </excludes>  
        </resource>  
    </resources>  
</build>  

MOXy v3+ and Jakarta

The above documentation relates to MOXy version 2.7. However, newer versions exist. As of this update, the latest available version is 3.0.0.

To use MOXy v3+, you need to account for the recent migration of several JEE products to the Jakarta project. As part of this migration, many packages which used to be part of javax are now part of jakarta.

You can read more about the background to these changes here: Transition from Java EE to Jakarta EE.

To update an older (v2) version of MOXy using javax to a newer (v3) version of MOXy using jakarta, you need to make the following changes:

Step 1)

Change the contents of the jaxb.properties file to the following:

jakarta.xml.bind.context.factory=org.eclipse.persistence.jaxb.JAXBContextFactory

Note the changed reference to jakarta, for the bind context.

Step 2)

Change all of your jaxb imports to refer to jakarta instead of javax. So, for example, change this:

1

import javax.xml.bind.JAXBContext; // old import

to this:

1

import jakarta.xml.bind.JAXBContext; // new import

Step 3)

Use the following two dependencies in your pom.xml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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

<dependency>
    <groupId>org.eclipse.persistence</groupId>
    <artifactId>eclipselink</artifactId>
    <version>3.0.0</version>
</dependency>

These two dependencies are sufficient to support an updated version of the code example presented in the following example:

XPath Based Mapping using MOXy

The code in that example is a good test case, since it uses MOXy’s support for XPath-based mapping (a feature not available in the Metro implementation of JAXB).