使用对象-XML 映射器进行 XML 编组

简介

本章描述了 Spring 的对象-XML 映射支持。对象-XML 映射(简称 O-X 映射)是将 XML 文档与对象进行相互转换的行为。这种转换过程也称为 XML 编组(XML Marshalling)或 XML 序列化(XML Serialization)。本章交替使用这些术语。

在 O-X 映射领域,编组器(marshaller)负责将对象(图)序列化为 XML。类似地,解组器(unmarshaller)将 XML 反序列化为对象图。此 XML 可以是 DOM 文档、输入或输出流,或 SAX 处理器。

使用 Spring 进行 O/X 映射的一些优点包括:

易于配置

Spring 的 Bean 工厂使配置编组器变得容易,无需构建 JAXB 上下文、JiBX 绑定工厂等。您可以像配置应用程序上下文中任何其他 Bean 一样配置编组器。此外,对于许多编组器,还提供了基于 XML 命名空间的配置,使配置更加简单。

一致的接口

Spring 的 O-X 映射通过两个全局接口操作:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/oxm/Marshaller.html[Marshaller] 和 Unmarshaller。这些抽象允许您相对轻松地切换 O-X 映射框架,对执行编组的类几乎不需要或无需更改。这种方法还有一个额外的好处,就是可以以非侵入式方式进行混合搭配的 XML 编组(例如,一些编组使用 JAXB 执行,一些使用 XStream 执行),让您可以使用每种技术的优势。

一致的异常层次结构

Spring 提供了一种将底层 O-X 映射工具的异常转换为其自己的异常层次结构的方法,其中 XmlMappingException 作为根异常。这些运行时异常包装了原始异常,因此不会丢失任何信息。

MarshallerUnmarshaller

简介 中所述,编组器将对象序列化为 XML,解组器将 XML 流反序列化为对象。本节描述了用于此目的的两个 Spring 接口。

理解 Marshaller

Spring 将所有编组操作抽象到 org.springframework.oxm.Marshaller 接口之后,其主要方法如下:

public interface Marshaller {

	/**
	 * Marshal the object graph with the given root into the provided Result.
	 */
	void marshal(Object graph, Result result) throws XmlMappingException, IOException;
}

Marshaller 接口有一个主要方法,它将给定对象编组到给定的 javax.xml.transform.Result 中。结果是一个标记接口,它基本上表示一个 XML 输出抽象。具体的实现包装了各种 XML 表示,如下表所示:

Result 实现 包装 XML 表示

DOMResult

org.w3c.dom.Node

SAXResult

org.xml.sax.ContentHandler

StreamResult

java.io.Filejava.io.OutputStreamjava.io.Writer

尽管 marshal() 方法接受一个普通对象作为其第一个参数,但大多数 Marshaller 实现无法处理任意对象。相反,对象类必须在映射文件中映射,用注解标记,在编组器中注册,或者具有一个公共基类。请参阅本章后面的部分,以确定您的 O-X 技术如何管理这一点。

理解 Unmarshaller

Marshaller 类似,我们有 org.springframework.oxm.Unmarshaller 接口,如下所示:

public interface Unmarshaller {

	/**
	 * Unmarshal the given provided Source into an object graph.
	 */
	Object unmarshal(Source source) throws XmlMappingException, IOException;
}

该接口也有一个方法,它从给定的 javax.xml.transform.Source(一个 XML 输入抽象)读取并返回读取的对象。与 Result 一样,Source 是一个标记接口,它有三个具体实现。每个都包装了不同的 XML 表示,如下表所示:

Source 实现 包装 XML 表示

DOMSource

org.w3c.dom.Node

SAXSource

org.xml.sax.InputSourceorg.xml.sax.XMLReader

StreamSource

java.io.Filejava.io.InputStreamjava.io.Reader

尽管有两个独立的编组接口(MarshallerUnmarshaller),但 Spring-WS 中的所有实现都在一个类中实现了这两个接口。这意味着您可以在 applicationContext.xml 中配置一个编组器类,并将其既作为编组器又作为解组器引用。

理解 XmlMappingException

Spring 将底层 O-X 映射工具的异常转换为其自己的异常层次结构,其中 XmlMappingException 作为根异常。这些运行时异常包装了原始异常,因此不会丢失任何信息。

此外,MarshallingFailureExceptionUnmarshallingFailureException 区分了编组和解组操作,即使底层 O-X 映射工具没有这样做。

O-X 映射异常层次结构如下图所示:

oxm exceptions

使用 MarshallerUnmarshaller

您可以将 Spring 的 OXM 用于各种情况。在以下示例中,我们使用它将 Spring 管理的应用程序的设置编组为 XML 文件。在以下示例中,我们使用一个简单的 JavaBean 来表示设置:

  • Java

  • Kotlin

public class Settings {

	private boolean fooEnabled;

	public boolean isFooEnabled() {
		return fooEnabled;
	}

	public void setFooEnabled(boolean fooEnabled) {
		this.fooEnabled = fooEnabled;
	}
}
class Settings {
	var isFooEnabled: Boolean = false
}

应用程序类使用此 Bean 来存储其设置。除了一个 main 方法之外,该类还有两个方法:saveSettings() 将设置 Bean 保存到名为 settings.xml 的文件中,loadSettings() 再次加载这些设置。以下 main() 方法构造一个 Spring 应用程序上下文并调用这两个方法:

  • Java

  • Kotlin

import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import javax.xml.transform.stream.StreamResult;
import javax.xml.transform.stream.StreamSource;
import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;
import org.springframework.oxm.Marshaller;
import org.springframework.oxm.Unmarshaller;

public class Application {

	private static final String FILE_NAME = "settings.xml";
	private Settings settings = new Settings();
	private Marshaller marshaller;
	private Unmarshaller unmarshaller;

	public void setMarshaller(Marshaller marshaller) {
		this.marshaller = marshaller;
	}

	public void setUnmarshaller(Unmarshaller unmarshaller) {
		this.unmarshaller = unmarshaller;
	}

	public void saveSettings() throws IOException {
		try (FileOutputStream os = new FileOutputStream(FILE_NAME)) {
			this.marshaller.marshal(settings, new StreamResult(os));
		}
	}

	public void loadSettings() throws IOException {
		try (FileInputStream is = new FileInputStream(FILE_NAME)) {
			this.settings = (Settings) this.unmarshaller.unmarshal(new StreamSource(is));
		}
	}

	public static void main(String[] args) throws IOException {
		ApplicationContext appContext =
				new ClassPathXmlApplicationContext("applicationContext.xml");
		Application application = (Application) appContext.getBean("application");
		application.saveSettings();
		application.loadSettings();
	}
}
class Application {

	lateinit var marshaller: Marshaller

	lateinit var unmarshaller: Unmarshaller

	fun saveSettings() {
		FileOutputStream(FILE_NAME).use { outputStream -> marshaller.marshal(settings, StreamResult(outputStream)) }
	}

	fun loadSettings() {
		FileInputStream(FILE_NAME).use { inputStream -> settings = unmarshaller.unmarshal(StreamSource(inputStream)) as Settings }
	}
}

private const val FILE_NAME = "settings.xml"

fun main(args: Array<String>) {
	val appContext = ClassPathXmlApplicationContext("applicationContext.xml")
	val application = appContext.getBean("application") as Application
	application.saveSettings()
	application.loadSettings()
}

Application 需要设置 marshallerunmarshaller 属性。我们可以使用以下 applicationContext.xml 来实现:

<beans>
	<bean id="application" class="Application">
		<property name="marshaller" ref="xstreamMarshaller" />
		<property name="unmarshaller" ref="xstreamMarshaller" />
	</bean>
	<bean id="xstreamMarshaller" class="org.springframework.oxm.xstream.XStreamMarshaller"/>
</beans>

此应用程序上下文使用 XStream,但我们可以使用本章后面描述的任何其他编组器实例。请注意,默认情况下,XStream 不需要任何进一步的配置,因此 Bean 定义相当简单。另请注意,XStreamMarshaller 实现了 MarshallerUnmarshaller,因此我们可以在应用程序的 marshallerunmarshaller 属性中引用 xstreamMarshaller Bean。

此示例应用程序生成以下 settings.xml 文件:

<?xml version="1.0" encoding="UTF-8"?>
<settings foo-enabled="false"/>

XML 配置命名空间

您可以使用 OXM 命名空间中的标签更简洁地配置编组器。要使这些标签可用,您必须首先在 XML 配置文件的前言中引用适当的模式。以下示例显示了如何执行此操作:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:oxm="http://www.springframework.org/schema/oxm" [id="CO1-1"]1
	xsi:schemaLocation="http://www.springframework.org/schema/beans
		https://www.springframework.org/schema/beans/spring-beans.xsd
		http://www.springframework.org/schema/oxm
		https://www.springframework.org/schema/oxm/spring-oxm.xsd"> [id="CO1-2"]2
<1>  引用 `oxm` 模式。
<1>  指定 `oxm` 模式位置。

该模式提供了以下元素:

每个标签都在其各自的编组器部分中进行解释。例如,JAXB2 编组器的配置可能如下所示:

<oxm:jaxb2-marshaller id="marshaller" contextPath="org.springframework.ws.samples.airline.schema"/>

JAXB

JAXB 绑定编译器将 W3C XML 模式转换为一个或多个 Java 类、一个 jaxb.properties 文件以及可能的一些资源文件。JAXB 还提供了一种从带注解的 Java 类生成模式的方法。

Spring 支持 JAXB 2.0 API 作为 XML 编组策略,遵循 MarshallerUnmarshaller 中描述的 MarshallerUnmarshaller 接口。相应的集成类位于 org.springframework.oxm.jaxb 包中。

使用 Jaxb2Marshaller

Jaxb2Marshaller 类实现了 Spring 的 MarshallerUnmarshaller 接口。它需要一个上下文路径才能运行。您可以通过设置 contextPath 属性来设置上下文路径。上下文路径是一个由冒号分隔的 Java 包名列表,其中包含模式派生类。它还提供了一个 classesToBeBound 属性,允许您设置一个由编组器支持的类数组。模式验证通过为 Bean 指定一个或多个模式资源来执行,如下例所示:

<beans>
	<bean id="jaxb2Marshaller" class="org.springframework.oxm.jaxb.Jaxb2Marshaller">
		<property name="classesToBeBound">
			<list>
				<value>org.springframework.oxm.jaxb.Flight</value>
				<value>org.springframework.oxm.jaxb.Flights</value>
			</list>
		</property>
		<property name="schema" value="classpath:org/springframework/oxm/schema.xsd"/>
	</bean>

	...

</beans>

XML 配置命名空间

jaxb2-marshaller 元素配置一个 org.springframework.oxm.jaxb.Jaxb2Marshaller,如下例所示:

<oxm:jaxb2-marshaller id="marshaller" contextPath="org.springframework.ws.samples.airline.schema"/>

或者,您可以使用 class-to-be-bound 子元素向编组器提供要绑定的类列表:

<oxm:jaxb2-marshaller id="marshaller">
	<oxm:class-to-be-bound name="org.springframework.ws.samples.airline.schema.Airport"/>
	<oxm:class-to-be-bound name="org.springframework.ws.samples.airline.schema.Flight"/>
	...
</oxm:jaxb2-marshaller>

下表描述了可用属性:

属性 描述 必需

id

编组器的 ID

contextPath

JAXB 上下文路径

JiBX

JiBX 框架提供了一个类似于 Hibernate 为 ORM 提供的解决方案:绑定定义定义了 Java 对象如何转换为 XML 或从 XML 转换的规则。在准备绑定和编译类之后,JiBX 绑定编译器增强类文件并添加代码以处理将类的实例从 XML 或转换为 XML。

有关 JiBX 的更多信息,请参阅 JiBX 网站。Spring 集成类位于 org.springframework.oxm.jibx 包中。

使用 JibxMarshaller

JibxMarshaller 类实现了 MarshallerUnmarshaller 接口。要操作,它需要要编组的类的名称,您可以使用 targetClass 属性设置该名称。可选地,您可以通过设置 bindingName 属性来设置绑定名称。在以下示例中,我们绑定 Flights 类:

<beans>
	<bean id="jibxFlightsMarshaller" class="org.springframework.oxm.jibx.JibxMarshaller">
		<property name="targetClass">org.springframework.oxm.jibx.Flights</property>
	</bean>
	...
</beans>

JibxMarshaller 配置用于单个类。如果您想编组多个类,则必须配置多个具有不同 targetClass 属性值的 JibxMarshaller 实例。

XML 配置命名空间

jibx-marshaller 标签配置一个 org.springframework.oxm.jibx.JibxMarshaller,如下例所示:

<oxm:jibx-marshaller id="marshaller" target-class="org.springframework.ws.samples.airline.schema.Flight"/>

下表描述了可用属性:

属性 描述 必需

id

编组器的 ID

target-class

此编组器的目标类

bindingName

此编组器使用的绑定名称

XStream

XStream 是一个简单的库,用于将对象序列化为 XML 并再次反序列化。它不需要任何映射并生成干净的 XML。

有关 XStream 的更多信息,请参阅 XStream 网站。Spring 集成类位于 org.springframework.oxm.xstream 包中。

使用 XStreamMarshaller

XStreamMarshaller 不需要任何配置,可以直接在应用程序上下文中配置。要进一步自定义 XML,您可以设置一个别名映射,该映射由字符串别名映射到类组成,如下例所示:

<beans>
	<bean id="xstreamMarshaller" class="org.springframework.oxm.xstream.XStreamMarshaller">
		<property name="aliases">
			<props>
				<prop key="Flight">org.springframework.oxm.xstream.Flight</prop>
			</props>
		</property>
	</bean>
	...
</beans>

默认情况下,XStream 允许任意类被解组,这可能导致不安全的 Java 序列化效果。因此,我们不建议使用 XStreamMarshaller 从外部源(即 Web)解组 XML,因为这可能导致安全漏洞。如果您选择使用 XStreamMarshaller 从外部源解组 XML,请在 XStreamMarshaller 上设置 supportedClasses 属性,如下例所示:

<bean id="xstreamMarshaller" class="org.springframework.oxm.xstream.XStreamMarshaller">
	<property name="supportedClasses" value="org.springframework.oxm.xstream.Flight"/>
	...
</bean>

这样做可以确保只有注册的类才符合解组条件。此外,您可以注册 自定义转换器 以确保只有您支持的类才能被解组。您可能希望将 CatchAllConverter 作为列表中的最后一个转换器添加,此外还有明确支持应支持的域类的转换器。因此,具有较低优先级和可能安全漏洞的默认 XStream 转换器不会被调用。

请注意,XStream 是一个 XML 序列化库,而不是数据绑定库。因此,它的命名空间支持有限。因此,它不适合在 Web 服务中使用。