JAXB-3 JAXB API

劳灵均

2023-12-01

3 JAXB API

该章节将讲述，如何通过 JAXB 提供的接口(API)，将 Java 类对象转换为 XML 文档。

3.1 JAXBContext 解读

被缓存的JAXBContext，为了性能上的考虑，将会对JAXBContext做缓存，不过缓存使用到了WeakReference，不用担心 GC 问题。
每次在创建JAXBContext实例时，JAXBContext内部都需要维护好Java类和XML之间的映射关系，这个操作十分消耗性能。不过JAXBContext是线程安全的，可以共享。一种较好的做法是，在程序初始化时，传入所有的Class，在使用时直接调用创建好的JAXBContext实例，而不是在每次使用时创建。
JAXBContext 是线程安全的，但是 Marshaller, Unmarshaller 都不是线程安全的。
在多线程环境下，应该使用类似下面的方式来初识化JAXBContext。

class MyServlet extends HttpServlet {
    static final JAXBContext context = initContext();
    private static JAXBContext initContext() {
        return JAXBContext.newInstance("....", MyServlet.class.getClassLoader());
    }
}

同时，在使用JAXB时，可以类似下面的方式获取Unmarshaller/Marshaller。

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

JAXBContext 提供了四种静态方法，方便使用者直接调用。为什么是四种而不是四个呢？因为它们有很多重载的方法，名称都是相同的，参数不同而已。

3.1.1 newInstance()

应用程序可以通过多种途径获得 JAXBContext 实例，它们拥有相同的函数名，只是参数不同。
使用类名 Xxx.class
创建 JAXB 实例，最常见的方式是传入特定的class.

// 使用类名 Xxx.class
JAXBContext instance = JAXBContext.newInstance(Student.class);

使用包路径加上类名 com.x.xx.Xxx.class
如果存在同名的Java对象，则可以指定完整路径：

// 使用包路径加上类名 com.x.xx.Xxx.class
JAXBContext instance = JAXBContext.newInstance(com.example.bean.Student.class);

多个类之间使用逗号分隔开
如果有多个对象需要注册，则可以：

// 多个类之间使用逗号分隔开
JAXBContext instance = JAXBContext.newInstance(Student.class, Teacher.class);

传入完整包名
或者也可以对某一个package包下所有的对象编组：

// 传入完整包名
JAXBContext instance = JAXBContext.newInstance("com.example.bean");

这时候并不是指定的包中所有的Class都会用来创建JAXBContext。按照JAXB的规范，我们需要在对应的包中创建一个 jaxb.index 文件，然后在其中指定创建JAXBContext时需要用到的Class，每个Class名称占一行。否则，会报错 “com.example.bean” 不包含 ObjectFactory.class 或 jaxb.index
完整包名之间使用冒号分隔开
甚至对多个package包下所有的对象编组：

// 完整包名之间使用冒号分隔开
JAXBContext instance = JAXBContext.newInstance("com.example.bean:com.example.pojo");

3.1.2 createMarshaller()

创建一个Marshaller对象，用于将Java内容转换为XML数据。
对使用工厂方法手动创建的内容进行编组与unmarshal操作结果的内容进行编组没有本质区别。客户端可以将Java内容编组成java.io.OutputStream或者java.io.Writer的XML数据。编组程序可以生成已经注册号的SAX2事件流，也可以生成一个DOM节点对象。

3.1.3 createUnmarshaller()

创建一个可以用来将 XML 数据转换为 java 内容树的 Unmarshaller 对象。该方法允许将模式中声明的任何全局 XML 元素解组为实例文档的根元素。

3.1.4 createBinder()

创建一个可用于关联/原地解组/编组操作的 Binder 对象。如果不传参数，默认使用W3C DOM创建一个Binder。

3.2 静态方法提供者 JAXB

javax.xml.bind.JAXB是2.1版本新增的工具类，其中所有的 public 方法均为静态方法，可以直接通过类名调用。它存在的意义就是帮助使用者简单，快速上手JAXB。

3.2.1 JAXB.unmarshal(…)

有很多重载的方法，方便使用者传入不同类型的参数。使用者不需要关心实现的细节，传入你需要转换的数据，加上需要生成的类，就能得到需要的数据。

public static <T> T unmarshal( URI xml, Class<T> type ) {}

返回值使用的是泛型T，可以得到任意对象

3.2.2 JAXB.marshal(…)

同样有很多重载的方法，方便使用者传入不同类型的参数。

public static void marshal( Object jaxbObject, URL xml ) {}

第一个参数是对象Obj，可以传入任意对象

注：自 JAXB 1.0 以后，验证已经发生了很大的变化。Validator 类已经废弃，成为了一个可选项。这意味着建议您不要使用此类，实际上，根据您的 JAXB 提供者，该类甚至根本不可用。

3.3 JAXBContext Marshaller 的转换参数

1、格式化输出 Marshaller.JAXB_FORMATTED_OUTPUT
默认的序列化操作，结果是正确的，但是显示成一行不便于阅读，可以通过添加属性JAXB_FORMATTED_OUTPUT 来修正：

2、编码字符集 Marshaller.JAXB_ENCODING
如果需要改输出XML的字符编码，可以添加属性JAXB_ENCODING：

@Test
public void test2() throws JAXBException {
    Marshaller marshaller = context.createMarshaller();
    marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
    marshaller.setProperty(Marshaller.JAXB_ENCODING, "ISO-8859-1");
    marshaller.marshal(one, System.out);
}

得到的结果：

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<one>
    <name>Test one</name>
</one>

已经不再是默认的UTF-8。

3、描述文件地址 Marshaller.JAXB_SCHEMA_LOCATION
有时候，程序可能需要指定 xsi:schemaLocation，则可以添加属性JAXB_SCHEMA_LOCATION：

@Test
public void test3() throws JAXBException {
    Marshaller marshaller = context.createMarshaller();
    marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
    marshaller.setProperty(Marshaller.JAXB_SCHEMA_LOCATION, "http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd");
    marshaller.marshal(one, System.out);
}

得到的结果：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<one xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.org/schema/beans/spring-beans.xsd">
    <name>Test one</name>
</one>

xsi:schemaLocation 其实是 Namespace 为 “http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd” 里的 schemaLocation 属性，它定义了 XML Namespace 和对应的XSD（Xml Schema Definition）文档的位置的关系。在Spring的配置文件中，时常能见到这个属性。

4、声明无文件地址 Marshaller.JAXB_NO_NAMESPACE_SCHEMA_LOCATION
如果没有Namespeace，但是需要使用Schema，就需要用到JAXB_NO_NAMESPACE_SCHEMA_LOCATION：

@Test
public void test4() throws JAXBException {
    Marshaller marshaller = context.createMarshaller();
    marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
    marshaller.setProperty(Marshaller.JAXB_NO_NAMESPACE_SCHEMA_LOCATION, "ehcache.xsd");
    marshaller.marshal(one, System.out);
}

得到的结果：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<one xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ehcache.xsd">
    <name>Test one</name>
</one>

5、取消XML头信息 Marshaller.JAXB_FRAGMENT
JAXB_FRAGMENT 是一个多面手，在不同的输出场景下，表现出不同的效果。

@Test
public void test5_1() throws JAXBException {
    Marshaller marshaller = context.createMarshaller();
    marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
    marshaller.setProperty(Marshaller.JAXB_FRAGMENT, true);
    marshaller.marshal(one, System.out);
}

在这里指定JAXB_FRAGMENT=true，表明结果不再声明XML头信息，得到的结果：

<one>
    <name>Test one</name>
</one>

可以看到，第一行的XML声明不见了。
如果使用到了SAX方式，可以发现如下不同：

@Test
public void test5_2() throws JAXBException {
    Marshaller marshaller = context.createMarshaller();
    marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
//  marshaller.setProperty(Marshaller.JAXB_FRAGMENT, true);
    marshaller.marshal(one, new MyContentHandler());
}

输出结果：

startDocument
endDocument

如果将注释的一行代码放开，再次运行程序将不能得到任何输出。JAXB_FRAGMENT的默认值为false，在其他场景下也有不同的表现。

3.4 JAXB API 封装

如果要对 Student.java 进行 XML 操作(对象树与 XML 相转换)，有如下步骤
1）使用 JAXBContext.newInstance(…) 初始化 JAXBContext
2）创建 Marshaller 或 Unmarshaller 实例
3）对 XML 文档进行操作

以下通过对 Student.java 的 JAXB API 封装做示例，可以通过多种方式对 Student.java 进行 XML 操作，最优的方式是对每个 XML 封装一个 Java Class，如下：

/**
 * a single ton object that is responsible for converting XML to a <Sample> object and <Sample> to an XML.
 */
public class SampleXmlSerializer {
    //  the singleton instance
    private volatile static SampleXmlSerializer instance;

    //  marshaller and unmarshaller
    private final Marshaller marshaller;      //  java to xml
    private final Unmarshaller unmarshaller;  //  xml to java

    private SampleXmlSerializer() throws JAXBException {
        //  create the JAXBContext object only here, to prevent memory leak
        JAXBContext jc = JAXBContext.newInstance(Sample.class);
        marshaller = jc.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
        unmarshaller = jc.createUnmarshaller();
    }

    /**
     * @return the singleton's instance (create it if necessary)
     * @throws JAXBException if an error occurred while initializing the object
     */
    public static SampleXmlSerializer getInstance() throws JAXBException {
        if (instance == null) {
            synchronized (SampleXmlSerializer.class) {
                //  double check the reference
                if (instance == null) {
                    instance = new SampleXmlSerializer();
                }
            }
        }
        return instance;
    }

    /**
     * serializes a request object to an XML string
     * @param request callback request
     * @return the given request serialized to an XML string
     * @throws JAXBException if an error occurs during marshaling
     */
    public String serialize(Sample request) throws JAXBException {
        //  output string
        StringWriter writer = new StringWriter();
        //  marshal the request
        synchronized (marshaller) {
            marshaller.marshal(request, writer);
        }
        return writer.toString();
    }

    /**
     * deserializes a request object from a given XML string
     * @param xmlString XML input string
     * @return callback request object that was deserialized from the input string
     * @throws JAXBException if an error occurs during unmarshalling
     * @throws ClassCastException if the deserialized object is not an instance of <Sample>
     */
    public Sample deserialize(String xmlString) throws JAXBException {
        StringReader reader = new StringReader(xmlString);
        JAXBElement<Sample> element;
        synchronized (unmarshaller) {
            element = (JAXBElement<Sample>) unmarshaller.unmarshal(reader);
        }
        return element.getValue();
    }

}

以上的 XmlSerialier 工具类，使用单实例(Singleton)保证对 Student.java 的 JAXBContext 上下文只运算一次，避免多次调用浪费运算资源；提供 serialize 和 deserialize 方法，对 Student.java 的 XML 序列化和反序列化提供支持。
另外一种方式，使用静态方法对 JAXB 的 API 进行二次封装，该方式不推荐在产品中使用。

/**
 * serializes a request object to an XML string
 * @param obj
 * @return
 */
public static String convertToXml(Object obj) {
    StringWriter sw = new StringWriter();
    try {
        JAXBContext context = JAXBContext.newInstance(obj.getClass());

        Marshaller marshaller = context.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
        
        marshaller.marshal(obj, sw);
    } catch (JAXBException e) {
        e.printStackTrace();
    }
    return sw.toString();
}

采用同样的方式，可以将 marshaller 后的数据输出到其他位置。

封装 marshal( Object jaxbElement, java.io.Writer writer )
StringWriter sw = new StringWriter();
封装 marshal( Object jaxbElement, java.io.Writer writer )
FileWriter fw = new FileWriter(path);
封装 marshal( Object jaxbElement, java.io.OutputStream os )
PrintStream out = System.out;

/**
 * deserializes a request object from a given XML string
 */
public static Object convertXmlStrToObject(Class clazz, String xmlStr) {
    Object xmlObject = null;
    try {
        JAXBContext context = JAXBContext.newInstance(clazz);
        Unmarshaller unmarshaller = context.createUnmarshaller();
        StringReader sr = new StringReader(xmlStr);
        xmlObject = unmarshaller.unmarshal(sr);
    } catch (JAXBException e) {
        e.printStackTrace();
    }
    return xmlObject;
}

支持多种输入源，

封装 unmarshal( Reader reader )
StringReader sr = new StringReader(xmlStr);
或 FileReader fr = new FileReader(xmlPath);

上一章：JAXB-2 JAXB Annotation 注解
目录：学习 JAXB
下一章：JAXB-4 Java 类与 XML 的转换

JAXB-3 JAXB API

3 JAXB API

3.1 JAXBContext 解读

3.1.1 newInstance()

3.1.2 createMarshaller()

3.1.3 createUnmarshaller()

3.1.4 createBinder()

3.2 静态方法提供者 JAXB

3.2.1 JAXB.unmarshal(…)

3.2.2 JAXB.marshal(…)

3.3 JAXBContext Marshaller 的转换参数

3.4 JAXB API 封装

相关阅读

相关文章

相关问答