public interface Unmarshaller
Unmarshaller 类管理将 XML 数据反序列化为新创建的 Java 内容树的过程,并可在解组时有选择地验证 XML 数据。它针对各种不同的输入种类提供各种重载的 unmarshal 方法。
从 File 解组:
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); Object o = u.unmarshal( new File( "nosferatu.xml" ) );
从 InputStream 解组:
InputStream is = new FileInputStream( "nosferatu.xml" ); JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); Object o = u.unmarshal( is );
从 URL 解组:
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); URL url = new URL( "http://beaker.east/nosferatu.xml" ); Object o = u.unmarshal( url );
使用 javax.xml.transform.stream.StreamSource 从 StringBuffer 解组:
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); StringBuffer xmlStr = new StringBuffer( "<?xml version="1.0"?>..." ); Object o = u.unmarshal( new StreamSource( new StringReader( xmlStr.toString() ) ) );
从 org.w3c.dom.Node 解组:
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); dbf.setNamespaceAware(true); DocumentBuilder db = dbf.newDocumentBuilder(); Document doc = db.parse(new File( "nosferatu.xml")); Object o = u.unmarshal( doc );
使用客户端指定的验证 SAX2.0 解析器从 javax.xml.transform.sax.SAXSource 解组:
// configure a validating SAX2.0 parser (Xerces2) static final String JAXP_SCHEMA_LANGUAGE = "http://java.sun.com/xml/jaxp/properties/schemaLanguage"; static final String JAXP_SCHEMA_LOCATION = "http://java.sun.com/xml/jaxp/properties/schemaSource"; static final String W3C_XML_SCHEMA = "http://www.w3.org/2001/XMLSchema"; System.setProperty( "javax.xml.parsers.SAXParserFactory", "org.apache.xerces.jaxp.SAXParserFactoryImpl" ); SAXParserFactory spf = SAXParserFactory.newInstance(); spf.setNamespaceAware(true); spf.setValidating(true); SAXParser saxParser = spf.newSAXParser(); try { saxParser.setProperty(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA); saxParser.setProperty(JAXP_SCHEMA_LOCATION, "http://...."); } catch (SAXNotRecognizedException x) { // exception handling omitted } XMLReader xmlReader = saxParser.getXMLReader(); SAXSource source = new SAXSource( xmlReader, new InputSource( "http://..." ) ); // Setup JAXB to unmarshal JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); ValidationEventCollector vec = new ValidationEventCollector(); u.setEventHandler( vec ); // turn off the JAXB provider's default validation mechanism to // avoid duplicate validation u.setValidating( false ) // unmarshal Object o = u.unmarshal( source ); // check for events if( vec.hasEvents() ) { // iterate over events }
从 StAX XMLStreamReader 解组:
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); javax.xml.stream.XMLStreamReader xmlStreamReader = javax.xml.stream.XMLInputFactory().newInstance().createXMLStreamReader( ... ); Object o = u.unmarshal( xmlStreamReader );
从 StAX XMLEventReader 解组:
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); javax.xml.stream.XMLEventReader xmlEventReader = javax.xml.stream.XMLInputFactory().newInstance().createXMLEventReader( ... ); Object o = u.unmarshal( xmlEventReader );
解组可以反序列化表示整个 XML 文档或 XML 文档子树的 XML 数据。通常,使用 解组全局声明的根元素所描述的 unmarshal 方法便已足够。通过利用全局元素声明和类型定义到 JAXB 映射类的JAXBContext
映射,这些 unmarshal 方法可以启动对 XML 数据的根元素的解组。当JAXBContext
映射不足以解组 XML 数据的根元素时,应用程序可以使用 借助 declaredType 进行解组的方法帮助解组过程。在 XML 数据的根元素对应于模式中的本地元素声明的情况下,这些方法对于解组很有用。
unmarshal 方法从不返回 null。如果解组过程无法将 XML 内容的根解组到 JAXB 映射对象,则将报告一个致命错误,通过抛出 JAXBException 终止处理过程。
不带 declaredType 参数的 unmarshal 方法使用JAXBContext
来解组 XML 数据的根元素。JAXBContext
实例是用来创建此 Unmarshaller 的实例。JAXBContext
实例维护全局声明的 XML 元素和类型定义名称到 JAXB 映射类的映射。该 unmarshal 方法检查JAXBContext
是否存在根元素的 XML 名称和/或 @xsi:type 到 JAXB 映射类的映射。如果存在这种映射,则使用适当的 JAXB 映射类来解组 XML 数据。注意,当根元素名称未知且根元素具有 @xsi:type 时,将使用该 JAXB 映射类作为JAXBElement
值来解组 XML 数据。当JAXBContext
对象没有根元素名称的映射,也没有其 @xsi:type(如果存在) 的映射时,那么将通过抛出UnmarshalException
立即中止解组操作。通过使用下一节描述的借助 declaredType 的 unmarshal 方法,可以解决这种异常现象。
带declaredType
参数的 unmarshal 方法使应用程序即使在根元素 XML 名称的JAXBContext
中不存在映射时,也能够反序列化 XML 数据的根元素。该 unmarshaller 使用指定为 declaredType 参数的、应用程序提供的映射来解组根元素。注意,即使根元素的元素名称是通过JAXBContext
映射的,declaredType
参数也会重写该映射,以便在使用这些 unmarshal 方法时反序列化根元素。此外,当 XML 数据的根元素具有 xsi:type 属性,且该属性的值引用一个通过JAXBContext
映射到 JAXB 映射类的类型定义时,根元素的 xsi:type 属性将优先于 unmarshal 方法的 declaredType 参数。这些方法总是返回一个 JAXBElement<declaredType> 实例。下表显示了如何设置返回 JAXBElement 实例的属性。
通过声明的类型进行解组所返回的 JAXBElement JAXBElement 属性 值 名称 xml 元素名称
值 declaredType 的实例
declaredType unmarshal 方法的 declaredType
参数作用域 null
(实际作用域未知)
以下是通过 declaredType 进行解组的方法的一个示例。
借助 declaredType 从 org.w3c.dom.Node 解组:
Schema fragment for example <xs:schema> <xs:complexType name="FooType">...<\xs:complexType> <!-- global element declaration "PurchaseOrder" --> <xs:element name="PurchaseOrder"> <xs:complexType> <xs:sequence> <!-- local element declaration "foo" --> <xs:element name="foo" type="FooType"/> ... </xs:sequence> </xs:complexType> </xs:element> </xs:schema> JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); dbf.setNamespaceAware(true); DocumentBuilder db = dbf.newDocumentBuilder(); Document doc = db.parse(new File( "nosferatu.xml")); Element fooSubtree = ...; // traverse DOM till reach xml element foo, constrained by a // local element declaration in schema. // FooType is the JAXB mapping of the type of local element declaration foo. JAXBElement<FooType> foo = u.unmarshal( fooSubtree, FooType.class);
支持兼容 SAX2.0 的解析器
客户端应用程序能够选择自己的兼容 SAX2.0 的解析器。如果没有选择 SAX 解析器,则将使用 JAXB 提供者的默认解析器。尽管 JAXB 提供者的默认解析器不必是与 SAX2.0 兼容的,但所有提供者必须允许客户端应用程序指定它们自己的 SAX2.0 解析器。一些提供者可能要求客户端应用程序在模式编译时指定 SAX2.0 解析器。有关详细信息,请参阅
unmarshal(Source)
。
验证和格式良好性
客户端应用程序可以通过 setSchema(javax.xml.validation.Schema) API 来启用或禁用 JAXP 1.3 验证机制。复杂的客户端可以指定它们自己的兼容 SAX 2.0 的解析器,并使用
unmarshal(Source)
API 来绕开 JAXP 1.3 验证机制。由于要解组的无效 XML 内容是在 JAXB 2.0 中定义的,这使 Unmarshaller 默认的验证事件处理程序比在 JAXB 1.0 中更为宽松。当向
JAXBContext
注册由 JAXB 1.0 绑定解析器所生成的模式派生代码时,默认的解组验证处理程序是DefaultValidationEventHandler
,它将在遇到致命错误(或错误)之后终止编组操作。对于 JAXB 2.0 客户端应用程序,不存在显式定义的默认验证处理程序,默认事件处理只在遇到致命错误时终止编组操作。
当前没有任何需要 Unmarshaller 上的所有 JAXB 提供者都支持的属性。但是,一些提供者可能支持它们自己的特定于提供者的属性集。
Unmarshaller
提供了两种风格的回调机制,这些机制允许在解组过程的关键点上进行特定于应用程序的处理。在“类定义的”事件回调中,解组期间会触发放置在 JAXB 映射类中的特定于应用程序的代码。“外部侦听器”允许用一个回调方法集中处理解组事件,而不是通过各种类型事件回调处理。“类定义”的事件回调方法允许任何 JAXB 映射类通过定义带有以下方法签名的方法指定自己的特定回调方法:
类定义的回调方法应该在回调方法需要访问类的非公共方法和/或字段时使用。// This method is called immediately after the object is created and before the unmarshalling of this // object begins.The callback provides an opportunity to initialize JavaBean properties prior to unmarshalling. void beforeUnmarshal(Unmarshaller, Object parent); //This method is called after all the properties (except IDREF) are unmarshalled for this object, //but before this object is set to the parent object. void afterUnmarshal(Unmarshaller, Object parent);外部侦听器回调机制允许
Unmarshaller.Listener
实例使用setListener(Listener)
注册。外部侦听器接收所有回调事件,从而允许用比逐个类地定义回调方法更为集中的方式处理事件。外部侦听器在解组过程将编组到 JAXB 元素或 JAXB 映射类时接收事件。“类定义的”事件回调方法和外部侦听器事件回调方法相互独立,可以对一个事件同时调用。两种侦听器回调方法都存在时,按照
Unmarshaller.Listener.beforeUnmarshal(Object, Object)
和Unmarshaller.Listener.afterUnmarshal(Object, Object)
中定义的顺序对它们进行调用。抛出异常的事件回调方法会终止当前的解组过程。
JAXBContext
,
Marshaller
,
Validator
嵌套类摘要 | |
---|---|
static class |
Unmarshaller.Listener 向 |
方法摘要 | ||
---|---|---|
|
getAdapter(Class<A> type) 获取与指定类型关联的适配器。 |
|
AttachmentUnmarshaller |
getAttachmentUnmarshaller() |
|
ValidationEventHandler |
getEventHandler() 返回当前的事件处理程序,如果没有设置事件处理程序,则返回默认的事件处理程序。 |
|
Unmarshaller.Listener |
getListener() 返回向此 Unmarshaller 注册的 Unmarshaller.Listener 。 |
|
Object |
getProperty(String name) 获取 Unmarshaller 底层实现中的特定属性。 |
|
Schema |
getSchema() 获取用于执行解组时验证的 JAXP 1.3 Schema 对象。 |
|
UnmarshallerHandler |
getUnmarshallerHandler() 获取可用作 XML 管线中的组件的 unmarshaller 处理程序对象。 |
|
boolean |
isValidating() 已过时。 从 JAXB 2.0 开始,请参阅 getSchema() |
|
|
setAdapter(Class<A> type, A adapter) 将已配置的 XmlAdapter 实例与此 unmarshaller 关联。 |
|
void |
setAdapter(XmlAdapter adapter) 将已配置的 XmlAdapter 实例与此 unmarshaller 关联。 |
|
void |
setAttachmentUnmarshaller(AttachmentUnmarshaller au) 将解析 cid(内容 id URI)的上下文与作为附件传递的二进制数据关联。 |
|
void |
setEventHandler(ValidationEventHandler handler) 允许应用程序注册 ValidationEventHandler。 |
|
void |
setListener(Unmarshaller.Listener listener) 向此 Unmarshaller 注册解组事件回调 Unmarshaller.Listener 。 |
|
void |
setProperty(String name, Object value) 设置 Unmarshaller 底层实现中的特定属性。 |
|
void |
setSchema(Schema schema) 指定应用作验证后续解组操作依据的 JAXP 1.3 Schema 对象。 |
|
void |
setValidating(boolean validating) 已过时。 从 JAXB2.0 开始,请参阅 setSchema(javax.xml.validation.Schema) |
|
Object |
unmarshal(File f) 从指定的文件解组 XML 数据并返回得到的内容树。 |
|
Object |
unmarshal(InputSource source) 从指定的 SAX InputSource 解组 XML 数据并返回得到的内容树。 |
|
Object |
unmarshal(InputStream is) 从指定的 InputStream 解组 XML 数据并返回得到的内容树。 |
|
Object |
unmarshal(Node node) 从指定的 DOM 树解组全局 XML 数据并返回得到的内容树。 |
|
|
unmarshal(Node node, Class<T> declaredType) 通过 JAXB 映射的 declaredType 解组 XML 数据并返回得到的内容树。 |
|
Object |
unmarshal(Reader reader) 从指定的 Reader 解组 XML 数据并返回得到的内容树。 |
|
Object |
unmarshal(Source source) 从指定的 XML Source 解组 XML 数据并返回得到的内容树。 |
|
|
unmarshal(Source source, Class<T> declaredType) 从 declaredType 指定的 XML Source 解组 XML 数据并返回得到的内容树。 |
|
Object |
unmarshal(URL url) 从指定的 URL 解组 XML 数据并返回得到的内容树。 |
|
Object |
unmarshal(XMLEventReader reader) 从指定的 pull 解析器解组 XML 数据并返回得到的内容树。 |
|
|
unmarshal(XMLEventReader reader, Class<T> declaredType) 将根元素解组到 JAXB 映射的 declaredType 并返回得到的内容树。 |
|
Object |
unmarshal(XMLStreamReader reader) 从指定的 pull 解析器解组 XML 数据并返回得到的内容树。 |
|
|
unmarshal(XMLStreamReader reader, Class<T> declaredType) 将根元素解组到 JAXB 映射的 declaredType 并返回得到的内容树。 |
方法详细信息 |
---|
Object unmarshal(File f) throws JAXBException
实现解组全局根元素。
f
- 将从中解组 XML 数据的文件
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果
ValidationEventHandler
从其
handleEvent 方法返回 false 或着
Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅
解组 XML 数据
IllegalArgumentException
- 如果 File 参数为 null
Object unmarshal(InputStream is) throws JAXBException
实现解组全局根元素。
is
- 将从中解组 XML 数据的 InputStream
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果
ValidationEventHandler
从其
handleEvent 方法返回 false 或者
Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅
解组 XML 数据
IllegalArgumentException
- 如果 InputStream 参数为 null
Object unmarshal(Reader reader) throws JAXBException
实现解组全局根元素。
reader
- 将从中解组 XML 数据的 Reader
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果
ValidationEventHandler
从其
handleEvent 方法返回 false 或者
Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅
解组 XML 数据
IllegalArgumentException
- 如果 InputStream 参数为 null
Object unmarshal(URL url) throws JAXBException
实现解组全局根元素。
url
- 将从中解组 XML 数据的 URL
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果
ValidationEventHandler
从其
handleEvent 方法返回 false 或者
Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅
解组 XML 数据
IllegalArgumentException
- 如果 URL 参数为 null
Object unmarshal(InputSource source) throws JAXBException
实现解组全局根元素。
source
- 将从中解组 XML 数据的输入源
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果
ValidationEventHandler
从其
handleEvent 方法返回 false 或者
Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅
解组 XML 数据
IllegalArgumentException
- 如果 InputSource 参数为 null
Object unmarshal(Node node) throws JAXBException
实现解组全局根元素。
node
- 要从中解组 XML 数据的文档/元素。调用者至少必须支持 Document 和 Element。
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果
ValidationEventHandler
从其
handleEvent 方法返回 false 或者
Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅
解组 XML 数据
IllegalArgumentException
- 如果 Node 参数为 nul
unmarshal(org.w3c.dom.Node, Class)
<T> JAXBElement<T> unmarshal(Node node, Class<T> declaredType) throws JAXBException
实现借助声明的类型进行解组。
node
- 从中解组 XML 数据的文档/元素。调用者至少必须支持 Document 和 Element。
declaredType
- 用来保存
node 的 XML 数据的适当 JAXB 映射类。
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果
ValidationEventHandler
从其
handleEvent 方法返回 false 或者
Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅
解组 XML 数据
IllegalArgumentException
- 如果任何参数为 null
Object unmarshal(Source source) throws JAXBException
实现解组全局根元素。
客户端应用程序可以选择不使用随 JAXB 提供者一起提供的默认解析器机制。任何兼容 SAX 2.0 的解析器都可以取代 JAXB 提供者的默认机制。要实现这一点,客户端应用程序必须正确配置一个包含 XMLReader 的 SAXSource,并且该 XMLReader 是由 SAX 2.0 解析器提供者实现的。如果 XMLReader 有一个向它注册的 org.xml.sax.ErrorHandler,则将使用 JAXB 提供者替换它,以便通过 JAXB 的 ValidationEventHandler 机制报告验证错误。如果 SAXSource 不包含 XMLReader,则将使用 JAXB 提供者的默认解析器机制。
也可以使用此解析器替换机制来替换 JAXB 提供者的解组时验证引擎。客户端应用程序必须正确配置其兼容 SAX 2.0 的解析器来执行验证(如上例所示)。解析器在解组操作期间遇到的任何 SAXParserExceptions 都将由 JAXB 提供者处理,并将其转换为 JAXB ValidationEvent 对象,这些对象将通过已经向 Unmarshaller 注册的 ValidationEventHandler 报告给客户端。注: 在为了实现解组而指定一个替换验证 SAX 2.0 解析器时,无需替换 JAXB 提供者使用的验证引擎来执行按需应变的验证。
客户端应用程序指定将在解组期间使用的替换解析器机制的唯一方法是通过 unmarshal(SAXSource) API。所有其他形式的 unmarshal 方法(文件、URL、Node 等等)将使用 JAXB 提供者的默认解析器和验证器机制。
source
- 将从中解组 XML 数据的 XML Source(提供者只需支持 SAXSource、DOMSource 和 StreamSource)
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果
ValidationEventHandler
从其
handleEvent 方法返回 false 或者
Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅
解组 XML 数据
IllegalArgumentException
- 如果 Source 参数为 nul
unmarshal(javax.xml.transform.Source, Class)
<T> JAXBElement<T> unmarshal(Source source, Class<T> declaredType) throws JAXBException
实现借助声明的类型进行解组。
请参阅 SAX 2.0 解析器的可插入性
source
- 将从中解组 XML 数据的 XML Source(提供者只需支持 SAXSource、DOMSource 和 StreamSource)
declaredType
- 用来保存
source 的 xml 根元素的适当 JAXB 映射类
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果
ValidationEventHandler
从其
handleEvent 方法返回 false 或者
Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅
解组 XML 数据
IllegalArgumentException
- 如果任何参数为 null
Object unmarshal(XMLStreamReader reader) throws JAXBException
实现解组全局根元素。
此方法假定该解析器处于 START_DOCUMENT 或 START_ELEMENT 事件上。解组将从起始事件开始,到相应的终止事件结束。如果此方法成功返回,则 reader 将指向终止事件后面的标记。
reader
- 要读取的解析器。
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果
ValidationEventHandler
从其
handleEvent 方法返回 false 或者
Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅
解组 XML 数据
IllegalArgumentException
- 如果
reader 参数为 null
IllegalStateException
- 如果
reader 没有指向 START_DOCUMENT 或 START_ELEMENT 事件。
unmarshal(javax.xml.stream.XMLStreamReader, Class)
<T> JAXBElement<T> unmarshal(XMLStreamReader reader, Class<T> declaredType) throws JAXBException
此方法实现借助 declaredType 进行解组。
此方法假定该解析器处于 START_DOCUMENT 或 START_ELEMENT 事件上。解组将从起始事件开始,到相应的终止事件结束。如果此方法成功返回,则 reader 将指向终止事件后面的标记。
reader
- 要读取的解析器。
declaredType
- 用来保存
reader 的 START_ELEMENT XML 数据的适当 JAXB 映射类。
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果
ValidationEventHandler
从其
handleEvent 方法返回 false 或者
Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅
解组 XML 数据
IllegalArgumentException
- 如果任何参数为 null
Object unmarshal(XMLEventReader reader) throws JAXBException
此方法是一个解组全局根方法。
此方法假定该解析器处于 START_DOCUMENT 或 START_ELEMENT 事件上。解组将