Java 9 前/后使用 JAXB (包括支持 javax.* 或 jakarta.*) | 隔叶黄莺 Yanbin Blog

2024-03-22 | 阅读(205)

使用 Java 处理 Object 与 XML 之间的转换时 JAXB(Java Architecture for XML Binding) 仍然被广泛使用。但随着 Java 9 模块化后把 JAXB 从标准 JDK 中移除后，和 Java EE 8(Jakarta EE 8) 到 Jakarta EE 9 的变迁时命名空间由 javax.* 变成了 jakarta.*，我们在使用 JAXB 时需作出相应的适配。

本文分别使用 Java 1.8, 17，通过 Maven 插件 jaxb2-maven-plugin 的 xjc (从 xsd 文件生成 Java 类), 和如何切换 jakarta.* 命名空间，由此可给我们对使用了 JAXB 的项目升级 JDK 时指明方向。从而不致于因不了解每部分组件的具体功效而在 pom.xml 中胡乱配置，比如之前对 jaxb2-maven-plugin 插件本身配置了多余的 org.glassfish.jaxb:jaxb-xjc 和 org.glassfish.jaxb:jaxb-runtime 依赖，也未能理解 jaxb2-maven-plugin 与 org.glassfish.jaxb:jaxb-runtime 之间的版本对应关系。

实验准备，创建简单的 Maven 项目，并在路径 src/main/xsd/ 下新建 Schema 文件 sample.xsd，内容为

<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="item">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="title" type="xs:string"/>
                <xs:element name="note" type="xs:string" minOccurs="0"/>
                <xs:element name="quantity" type="xs:positiveInteger"/>
                <xs:element name="price" type="xs:decimal"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

<?xml version="1.0" encoding="UTF-8" ?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:element name="item">

<xs:complexType>

<xs:sequence>

<xs:element name="title" type="xs:string"/>

<xs:element name="note" type="xs:string" minOccurs="0"/>

<xs:element name="quantity" type="xs:positiveInteger"/>

<xs:element name="price" type="xs:decimal"/>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

如果再加上将要的测试代码 Client.java 的话，该 Maven 项目的目录结构就是

├── pom.xml
└── src
    └── main
        ├── com
        │   └── example
        │       └── Client.java
        └── xsd
            └── sample.xsd

├── pom.xml

└── src

└── main

├── com

│ └── example

│ └── Client.java

└── xsd

└── sample.xsd

下面分别用在 Java 9 前后的版本进行测试，Java 9 之前选择最流行的 Java 8, 之后的以 JDK 17 作为代表。

Java 1.8 中使用 xjc

Java 9 之前在 JDK 中内含 JAXB 组件，所以在 Java 8 中应用它很简单。

关于 jaxb2-maven-plugin xjc 的用法请参考官方的 Basic Examples - Java Generation. 我们多数时候遵循该插件的约定，可使对插件的配置最小化，如把 xsd 文件放在 src/main/xsd 中, 由 xsd 生成的 Java 源文件会在 target/generated-sources/jaxb 中, 该插件会自动把此目录自动作为源文件目录。xjc goal 会关联到 Maven 的 generate-sources Phase，所以 mvn compile 命令也就会自动生成 Java 文件和编译。

在 Maven 的 pom.xml 文件，只要在 build/plugins 中加上以下部分

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>jaxb2-maven-plugin</artifactId>
    <version>2.3.1</version>
    <executions>
        <execution>
            <id>sample</id>
            <goals>
                <goal>xjc</goal>
            </goals>
            <configuration>
                <packageName>com.example.generation</packageName>
            </configuration>
        </execution>
    </executions>
</plugin>

<groupId>org.codehaus.mojo</groupId>

<artifactId>jaxb2-maven-plugin</artifactId>

<id>sample</id>

<goals>

</goals>

<packageName>com.example.generation</packageName>

</configuration>

</execution>

</executions>

</plugin>

现在执行 mvn 命令

mvn clean compile

在 target/generated-sources/jaxb/com/example/generation下生成 Item.java 和 ObjectFactory.java 文件

写一段代码进行测试 com/example/Client

package com.example;

import com.example.generation.Item;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Marshaller;
import java.math.BigDecimal;

public class Client {

    public static void main(String[] args) throws JAXBException {
        Item item = new Item();
        item.setPrice(BigDecimal.valueOf(12.0));
        item.setTitle("Hello");

        JAXBContext jaxbContext = JAXBContext.newInstance(Item.class);
        Marshaller marshaller = jaxbContext.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);

        marshaller.marshal(item, System.out);
    }
}

package com.example;

import com.example.generation.Item;

import javax.xml.bind.JAXBContext;

import javax.xml.bind.JAXBException;

import javax.xml.bind.Marshaller;

import java.math.BigDecimal;

public class Client {

public static void main(String[] args) throws JAXBException {

Item item = new Item();

item.setPrice(BigDecimal.valueOf(12.0));

item.setTitle("Hello");

JAXBContext jaxbContext = JAXBContext.newInstance(Item.class);

Marshaller marshaller = jaxbContext.createMarshaller();

marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);

marshaller.marshal(item, System.out);

}

执行该 Java 代码，得到输出

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<title>Hello</title>
<price>12.0</price>
</item>

如果查看当前目录的结构是

.
├── pom.xml
├── src
│   └── main
│       ├── java
│       │   └── com
│       │       └── example
│       │           └── Client.java
│       └── xsd
│           └── sample.xsd
└── target
    ├── classes
    │   └── com
    │       └── example
    │           ├── Client.class
    │           └── generation
    │               ├── Item.class
    │               └── ObjectFactory.class
    ├── generated-sources
    │   ├── annotations
    │   └── jaxb
    │       ├── META-INF
    │       │   └── sun-jaxb.episode
    │       └── com
    │           └── example
    │               └── generation
    │                   ├── Item.java
    │                   └── ObjectFactory.java
    └── jaxb2

├── pom.xml

├── src

│ └── main

│ ├── java

│ │ └── com

│ │ └── example

│ │ └── Client.java

│ └── xsd

│ └── sample.xsd

└── target

├── classes

│ └── com

│ └── example

│ ├── Client.class

│ └── generation

│ ├── Item.class

│ └── ObjectFactory.class

├── generated-sources

│ ├── annotations

│ └── jaxb

│ ├── META-INF

│ │ └── sun-jaxb.episode

│ └── com

│ └── example

│ └── generation

│ ├── Item.java

│ └── ObjectFactory.java

└── jaxb2

注意到我们这里所用的 jaxb2-maven-plugin 插件版本是 2.3.1, 在 MVN REPOSITORY jaxb2-maven-plugin 的最新版本有

升级 jaxb2-maven-plugin 插件到 2.4 或 2.5.0 也可正常工作. 但只有 2.3.1 可配置 <generateEpisode>false</generateEpisode> 而不用生成 *.episode 文件.

那么升级到 3.1.0 后会怎么样呢？

可正常执行 mvn genreate-sources，但生成的 Item.java 和 ObjectFactory.java 导入的包由 javax.* 变成了 jakarta.*, 由此可知 jaxb2-maven-plugin 的 3.1.0 是个分水岭，它是为 Jakarta EE 9 服务的。

Java 17 中使用 xjc

现在我们直接从 Java 8 跳到 Java 17, 已经知道这其中起关键性的阻碍是 Java 9 的模块化把 JAXB 从标准 JDK 的拿掉了。

如果我们对前面的代码(为避免编译错误先把 Client.java 代码注释掉)，只是切换 Java 到版本 17, 继续用 jaxb2-maven-plugin:2.3.1，直接运行

mvn clean generate-sources

出现错误

Execution sample of goal org.codehaus.mojo:jaxb2-maven-plugin:2.3.1:xjc failed: A required class was missing while executing org.codehaus.mojo:jaxb2-maven-plugin:2.3.1:xjc: com/sun/codemodel/CodeWriter

升级插件到 2.4 后再次执行 mvn clean generate-sources, 得到新的错误

Caused by: java.lang.ClassNotFoundException: javax.activation.MimeTypeParseException

升级插件到 2.5.0 后 mvn clean generate-source 顺利通过, 但无法通过编译(mvn compile), 错误中有许多如下信息

package javax.xml.bind.annotation does not exist

因为 jaxb2-maven-plugin 生成的源文件 Item.java 中要导入的类如下

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
.......

import javax.xml.bind.annotation.XmlAccessType;

import javax.xml.bind.annotation.XmlAccessorType;

.......

这些原本属性 JAXB 模块的类已由 Java 9 从核模块中移除了，要使用的话还须从外界重新引入, 也就是 JAXB Runtime

从 https://mvnrepository.com/search?q=jaxb-runtime 可找到几个相关的 JAXB Runtime, 如

org.glassfish.jaxb:jaxb-runtime
com.sun.xml.bind:jaxb-impl
org.mule.glassfish.jaxb:jaxb-runtime
javax.xml.bin:jaxb-api

等等，从多方面来看还是 org.glassfish.jaxb:jaxb-runtime 更流行，所以在 pom.xml 中加上依赖

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

<groupId>org.glassfish.jaxb</groupId>

<artifactId>jaxb-runtime</artifactId>

</dependency>

再次执行

mvn clean compile

通过

在 org.glassfish.jaxb:jaxb-runtime 中实际是引入了 jakarta.xml.bind:jakarta.xml.bind-api 来支援 javax.xml.bind.* 的。当前 org.glassfish.jaxb:jaxb-runtime 比 2.3.9 更高的版本有 3.x 和 4.x，我们需把它的版本压制在 2.x 是因为 3.x 和 4.x 所关联的 jakarta.xml.bind:jakarta.xml.bind-api 的包名 javax.xml.bind.* 变成了 jakarta.xml.bind.* 了。

通过一系列的测试，我们可以总结出 jaxb2-maven-plugin 和 org.glassfish.jaxb:jaxb-runtime 的版本应如何搭配，支持项目中的 javax.* 或 jakarta.* 命名空间(如升级了 SpringBoot 到 3.2.x, 使用了 Tomcat 10 等)

继续使用 javax.* 命名空间

jaxb2-maven-plugin: 2.x(2.5.0)
org.glassfish.jaxb:jaxb-runtime: 2.x(2.3.9)

要采用新的 jarkata.* 命名空间

jaxb2-maven-plugin: 3.x+(3.1.0)
org.glassfish.jaxb:jaxb-runtime:3.x+(4.0.5)

完整的 pom.xml 的配置如下

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>test</groupId>
    <artifactId>testxjc-java17</artifactId>
    <version>1.0-SNAPSHOT</version>
    <name>java17-jaxb</name>

    <properties>
        <jaxb2-plugin-version>3.1.0</jaxb2-plugin-version>
        <jaxb-runtime-version>4.0.5</jaxb-runtime-version>
    </properties>

   <dependencies>
        <dependency>
            <groupId>org.glassfish.jaxb</groupId>
            <artifactId>jaxb-runtime</artifactId>
            <version>${jaxb-runtime-version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>jaxb2-maven-plugin</artifactId>
                <version>${jaxb2-plugin-version}</version>
                <executions>
                    <execution>
                        <id>sample</id>
                        <goals>
                            <goal>xjc</goal>
                        </goals>
                        <configuration>
                            <packageName>com.example.generation</packageName>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

<artifactId>testxjc-java17</artifactId>

<version>1.0-SNAPSHOT</version>

<jaxb2-plugin-version>3.1.0</jaxb2-plugin-version>

<jaxb-runtime-version>4.0.5</jaxb-runtime-version>

</properties>

<groupId>org.glassfish.jaxb</groupId>

<artifactId>jaxb-runtime</artifactId>

<version>${jaxb-runtime-version}</version>

</dependency>

</dependencies>

<build>

<groupId>org.codehaus.mojo</groupId>

<artifactId>jaxb2-maven-plugin</artifactId>

<version>${jaxb2-plugin-version}</version>

<id>sample</id>

<goals>

</goals>

<packageName>com.example.generation</packageName>

</configuration>

</execution>

</executions>

</plugin>

</plugins>

</build>

</project>

jaxb2-plugin-version 和 jaxb-runtime-version 根据用 javax.* 还是 jakarta.* 包名来选择相应的版本。如果打算各路依赖都尽量往高的版本去升，那就选择用 jakarta.* 的命名空间吧。

要是使用了高版本的 Maven 插件, 最后把 Client.java 恢复回来，把其中的 javax.* 替换成 jakarta.* 就能正常工作了。

另外两个问题

JDK 21 与 Lombok 的兼容性

在 JDK 21 中在使用 jaxb2-maven-plugin 插件时，如果项目中使用了 Lombok 1.8.30 之前版本的话会出现出错

Fatal error compiling: java.lang.NoSuchFieldError:
Class com.sun.tools.javac.tree.JCTree$JCImport does not have member field 'com.sun.tools.javac.tree.JCTree qualid'

把 Lombok 升级到与 JDK 21 兼容的 1.18.30 版本即可。

使用了 jaxb 命名空间的自定义 Schema

如果在自定义 xsd 文件中使用了 xmlns:jaxb 的话，执行 mvn generate-sources 也会出问题，例如有一个 user.xsd 文件

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:jaxb="https://java.sun.com/xml/ns/jaxb" jaxb:version="1.0">
  <xs:element name="userapi">
    <xs:annotation>
      <xs:appinfo>
        <jaxb:class name="UserRequest"/>
      </xs:appinfo>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
          <xs:sequence>
            <xs:element name="name" type="xs:string"/>
            <xs:element name="address" type="xs:string" minOccurs="0"/>
          </xs:sequence>
        </xs:choice>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:jaxb="https://java.sun.com/xml/ns/jaxb" jaxb:version="1.0">

<xs:element name="userapi">

<xs:annotation>

<xs:appinfo>

<jaxb:class name="UserRequest"/>

</xs:appinfo>

</xs:annotation>

<xs:complexType>

<xs:sequence>

<xs:element name="name" type="xs:string"/>

<xs:element name="address" type="xs:string" minOccurs="0"/>

</xs:sequence>

</xs:choice>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

出错信息为

[WARNING] null [-1,-1]
org.xml.sax.SAXParseException: No JAXB customization was detected in the schema but the prefix "jaxb" is used for other namespace URIs. If you did intend to use JAXB customization, make sure the namespace URI is "https://jakarta.ee/xml/ns/jaxb"
at com.sun.tools.xjc.reader.xmlschema.parser.IncorrectNamespaceURIChecker.endDocument (IncorrectNamespaceURIChecker.java:70)
at org.xml.sax.helpers.XMLFilterImpl.endDocument (XMLFilterImpl.java:485)
at org.xml.sax.helpers.XMLFilterImpl.endDocument (XMLFilterImpl.java:485)
at org.xml.sax.helpers.XMLFilterImpl.endDocument (XMLFilterImpl.java:485)
at com.sun.tools.xjc.reader.internalizer.VersionChecker.endDocument (VersionChecker.java:100)

这可不仅仅是一个警告信息，实际上无法生成 UserRequest 类。我们需要按照信息中的提示，把前面 user.xsd 中 xs:schema 声明部分改成

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:jaxb="https://jakarta.ee/xml/ns/jaxb" jaxb:version="3.0">

1 2	<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:jaxb="https://jakarta.ee/xml/ns/jaxb" jaxb:version="3.0">

这样就能正常了。

本文链接 https://yanbin.blog/java-9-jaxb-including-javax-jakarta/, 来自隔叶黄莺 Yanbin Blog

1 Comment

Inline Feedbacks

View all comments

Perry Conn

7 months ago

Your writing has a way of making even the most complex topics accessible and engaging. I'm constantly impressed by your ability to distill complicated concepts into easy-to-understand language.

seetimee on 体验 Python FastAPI 的并发能力及线, 进程模型感谢
Yanbin on Mockito 3.4.0 开始可 Mock 静态方法有一个补救，新写了一篇 https://yanbin.blog/mockito-mock-static-method-in-multiple...
Yanbin on 升级到 Spring Boot 3 后 javax.inject.Named 不可用怎么，被抄袭了！算是被机器翻译引用的？
oleksi on 升级到 Spring Boot 3 后 javax.inject.Named 不可用https://www.springcloud.io/post/2023-02/springboot-3-javax-inject-name...
Zhe on 体验 Python FastAPI 的并发能力及线, 进程模型你在trio下得用 trio.sleep()，调用asyncio.sleep() 就会报错。

M	T	W	T	F	S	S
				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