Skip to main content
Frequently Asked QuestionsLinks: Table of Contents | Single HTML | Single PDF

Frequently Asked Questions

1. JAXB 2.0
Q: Which version of Java SE does Eclipse Implementation of JAXB 4.0.3 require?
Q: Can I run my existing JAXB 1.x/2.x applications on the Eclipse Implementation of JAXB runtime?
Q: What if I want to port my JAXB 1.x/2.x application to Jakarta XML Binding runtime?
Q: Where are schemagen and xjc command line scripts available?
Q: Are the Jakarta XML Binding runtime API's thread safe?
Q: Why can't I cast the unmarshalled object into the generated type.
Q: Which jar files do I need to distribute with my application that uses the Eclipse Implementation of JAXB?
Q: How can I cause the Marshaller to generate CDATA blocks?
Q: Can I access <xs:any/> as a DOM node?
Q: How do I find out which version of the Eclipse Implementation of JAXB I'm using?

1. JAXB 2.0

Q:

Which version of Java SE does Eclipse Implementation of JAXB 4.0.3 require?

A:

Java SE 11 or higher.

Q:

Can I run my existing JAXB 1.x/2.x applications on the Eclipse Implementation of JAXB runtime?

A:

This is not supported.

Q:

What if I want to port my JAXB 1.x/2.x application to Jakarta XML Binding runtime?

A:

You need to replace references to javax.xml.bind package by jakarta.xml.bind package, recompile your schema with the newer xjc and modify your application code to work with the new bindings.

Q:

Where are schemagen and xjc command line scripts available?

A:

They are included only in the zip distribution.

Q:

Are the Jakarta XML Binding runtime API's thread safe?

A:

The Jakarta XML Binding Specification currently does not address the thread safety of any of the runtime classes. In the case of the Eclipse Implementation of JAXB, the JAXBContext class is thread safe, but the Marshaller, Unmarshaller, and Validator classes are not thread safe.

For example, suppose you have a multi-thread server application that processes incoming XML documents by Jakarta XML Binding. In this case, for the best performance you should have just one instance of JAXBContext in your whole application like this:

class MyServlet extends HttpServlet {
    static final JAXBContext context = initContext();

    private static JAXBContext initContext() {
        return JAXBContext.newInstance("....", MyServlet.class.getClassLoader());
    }
}

And each time you need to unmarshal/marshal/validate a document. Just create a new Unmarshaller/Marshaller/Validator from this context, like this:

public void doGet(HttpServletRequest req, HttpServletResponse resp) {
    Unmarshaller u = context.createUnmarshaller();
    u.unmarshal(...);
}

This is the simplest safe way to use the Eclipse Implementation of JAXB from multi-threaded applications.

If you really care about the performance, and/or your application is going to read a lot of small documents, then creating Unmarshaller could be relatively an expensive operation. In that case, consider pooling Unmarshaller objects. Different threads may reuse one Unmarshaller instance, as long as you don't use one instance from two threads at the same time.

Q:

Why can't I cast the unmarshalled object into the generated type.

A:

When you invoke JAXBContext.newInstance("aaa.bbb.ccc"), it tries to load classes and resources using the same classloader used to load the JAXBContext class itself. This classloader may be different from the classloader which was used to load your application (see the picture Parent/Child classloader). In this case, you'll see the above error. This problem is often seen with application servers, Jakarta EE containers, Ant, JUnit, and other applications that use sophisticated class loading mechanisms.

Figure 1. Parent/Child classloader

Parent/Child classloader

With some applications, things get even more complicated when the Jakarta XML Binding-generated code can be loaded by either classloader. In this case, JAXBContext.newInstance("aaa.bbb.ccc") will work but the JVM ends up loading two copies of the generated classes for each class loader. As a result, unmarshalling works but an attempt to cast the returned object into the expected type will fail, even though its getClass().getName() returns the expected name.

The solution for both situations is to pass your curent class loader like this:

JAXBContext.newInstance("aaa.bbb.ccc", this.getClass().getClassLoader());

In general, if you are writing code that uses Jakarta XML Binding, it is always better to explicitly pass in a class loader, so that your code will work no matter where it is deployed.

Q:

Which jar files do I need to distribute with my application that uses the Eclipse Implementation of JAXB?

A:

$JAXB_HOME/mod/jakarta.xml.bind-api.jar
$JAXB_HOME/mod/jakarta.activation-api.jar
$JAXB_HOME/mod/angus-activation.jar
$JAXB_HOME/mod/jaxb-core.jar
$JAXB_HOME/mod/jaxb-impl.jar

Q:

How can I cause the Marshaller to generate CDATA blocks?

A:

This functionality is not available from Eclipse Implementation of JAXB directly, but you can configure an Apache Xerces-J XMLSerializer to produce CDATA blocks. Please review the JaxbCDATASample.java sample app for more detail.

Q:

Can I access <xs:any/> as a DOM node?

A:

In Eclipse Implementation of JAXB, <xs:any/> is handled correctly without any customization.

  1. If it's strict, it will map to Object or List<Object> and when you unmarshal documents, you'll get objects that map to elements (such as JAXBElements or classes that are annotated with XmlRootElement).

  2. If it's skip, it will map to org.w3c.dom.Element or List<Element> and when you unmarshal documents, you'll get DOM elements.

  3. If it's lax, it will map to the same as with strict, and when you unmarshal documents, you'll get either:

    1. JAXBElements

    2. classes that are annotated with XmlRootElement

    3. DOM elements

Q:

How do I find out which version of the Eclipse Implementation of JAXB I'm using?

A:

Run the following command

$ java -jar jaxb-xjc.jar -version

Alternatively, each Eclipse Implementation of JAXB jar has version information in its META-INF/MANIFEST.MF, such as this:

Manifest-Version: 1.0
Specification-Title: Jakarta XML Binding
Specification-Version: 4.0
Specification-Vendor: Eclipse Foundation
Implementation-Title: Eclipse Implementation of JAXB
Implementation-Version: 4.0.3
Implementation-Vendor: Eclipse Foundation
Implementation-Vendor-Id: org.eclipse
Build-Id: 2022-05-18 22:33
Class-Path: jaxb-core.jar jaxb-impl.jar

Back to the top