©
This document uses PHP Chinese website manual Release
|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
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
向 Unmarshaller 注册此类的一个实现的实例,以便外部侦听解组事件。 |
方法摘要 | ||
---|---|---|
|
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 参数为 nullObject unmarshal(InputStream is) throws JAXBException
实现解组全局根元素。
is
- 将从中解组 XML 数据的 InputStream
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果 ValidationEventHandler
从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据
IllegalArgumentException
- 如果 InputStream 参数为 nullObject unmarshal(Reader reader) throws JAXBException
实现解组全局根元素。
reader
- 将从中解组 XML 数据的 Reader
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果 ValidationEventHandler
从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据
IllegalArgumentException
- 如果 InputStream 参数为 nullObject unmarshal(URL url) throws JAXBException
实现解组全局根元素。
url
- 将从中解组 XML 数据的 URL
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果 ValidationEventHandler
从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据
IllegalArgumentException
- 如果 URL 参数为 nullObject unmarshal(InputSource source) throws JAXBException
实现解组全局根元素。
source
- 将从中解组 XML 数据的输入源
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果 ValidationEventHandler
从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据
IllegalArgumentException
- 如果 InputSource 参数为 nullObject unmarshal(Node node) throws JAXBException
实现解组全局根元素。
node
- 要从中解组 XML 数据的文档/元素。调用者至少必须支持 Document 和 Element。
JAXBException
- 如果在解组时发生不可预料的错误
UnmarshalException
- 如果 ValidationEventHandler
从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据
IllegalArgumentException
- 如果 Node 参数为 nulunmarshal(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
- 如果任何参数为 nullObject 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 参数为 nulunmarshal(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
- 如果任何参数为 nullObject 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
- 如果任何参数为 nullObject unmarshal(XMLEventReader 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.XMLEventReader, Class)
<T> JAXBElement<T> unmarshal(XMLEventReader 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
- 如果任何参数为 nullUnmarshallerHandler getUnmarshallerHandler()
JAXB 提供者可以为此方法的多次调用返回相同的处理程序对象。换句话说,此方法不必创建新的 UnmarshallerHandler 实例。如果应用程序需要使用多个 UnmarshallerHandler,那么它应该创建多个 Unmarshaller。
UnmarshallerHandler
void setValidating(boolean validating) throws JAXBException
setSchema(javax.xml.validation.Schema)
此方法只能在调用某一 unmarshal 方法之前或之后调用。
此方法只控制 JAXB 提供者的默认解组时验证机制,不会影响指定自己的验证兼容 SAX 2.0 的解析器的客户端。指定自己的解组时验证机制的客户端可能希望通过此 API 关闭 JAXB 提供者的默认验证机制,以避免“双重验证”。
此方法从 JAXB 2.0 开始已经废弃,请使用新的 setSchema(javax.xml.validation.Schema)
API。
validating
- 如果 Unmarshaller 应该在解组期间执行验证,则该参数为 true;否则为 false
JAXBException
- 如果在解组期间启用或禁用验证时发生错误
UnsupportedOperationException
- 如果对根据引用 JAXB 2.0 映射类的 JAXBContext 而创建的 Unmarshaller 调用此方法,则抛出该异常boolean isValidating() throws JAXBException
getSchema()
此 API 返回 JAXB 提供者的默认解组时验证机制的状态。
此方法从 JAXB 2.0 开始已经废弃,请使用新的 getSchema()
API。
JAXBException
- 如果在检索验证标志时发生错误
UnsupportedOperationException
- 如果对根据引用 JAXB 映射类的 JAXBContext 而创建的 Unmarshaller 调用此方法,则抛出该异常void setEventHandler(ValidationEventHandler handler) throws JAXBException
如果在调用任何 unmarshal 方法期间遇到任何错误,则 ValidationEventHandler 将由 JAXB 提供者调用。如果客户端应用程序没有在调用 unmarshal 方法之前注册 ValidationEventHandler,则 ValidationEvents 将由默认事件处理程序处理,默认事件处理程序将在遇到第一个错误或致命错误时终止解组操作。
调用带有 null 参数的此方法将导致 Unmarshaller 重新使用默认事件处理程序。
handler
- 验证事件处理程序
JAXBException
- 如果在设置事件处理程序期间遇到错误ValidationEventHandler getEventHandler() throws JAXBException
JAXBException
- 如果获取当前的事件处理程序时遇到错误void setProperty(String name, Object value) throws PropertyException
name
- 要设置的属性的名称。此值可以使用一个常量字段来指定,也可以是一个用户提供的字符串。value
- 要设置的属性值
PropertyException
- 如果处理给定属性或值时发生错误
IllegalArgumentException
- 如果 name 参数为 nullObject getProperty(String name) throws PropertyException
name
- 要检索的属性的名称
PropertyException
- 如果检索给定属性或值属性名称时发生错误
IllegalArgumentException
- 如果 name 参数为 nullvoid setSchema(Schema schema)
Schema
对象。向此方法传递 null 将禁用验证。
此方法将替换已过时的 setValidating(boolean)
API。
最初,此属性被设置为 null。
schema
- 作为验证解组操作依据的 Schema 对象;为 null 表示禁用验证
UnsupportedOperationException
- 如果对根据引用 JAXB 1.0 映射类的 JAXBContext 而创建的 Unmarshaller 调用此方法,则抛出该异常Schema getSchema()
Schema
对象。如果没有在 unmarshaller 上设置 Schema,则此方法将返回 null,指示不会执行解组时验证。
此方法用于替换已过时的 isValidating()
API,并可访问 Schema 对象。要确定 Unmarshaller 是否启用了验证,只需测试返回类型是否为 null:
boolean isValidating = u.getSchema()!=null;
UnsupportedOperationException
- 如果对根据引用 JAXB 1.0 映射类的 JAXBContext 而创建的 Unmarshaller 调用此方法,则抛出该异常void setAdapter(XmlAdapter adapter)
XmlAdapter
实例与此 unmarshaller 关联。
这是调用 setAdapter(adapter.getClass(),adapter);
的一个便捷方法。
IllegalArgumentException
- 如果 adapter 参数为 null。
UnsupportedOperationException
- 如果基于 JAXB 1.0 实现调用。setAdapter(Class,XmlAdapter)
<A extends XmlAdapter> void setAdapter(Class<A> type, A adapter)
XmlAdapter
实例与此 unmarshaller 关联。
每个 unmarshaller 都可以在内部维护一个 Map
<Class
,XmlAdapter
>,可用来解组使用 XmlJavaTypeAdapter
注释其字段/方法的类。
此方法允许应用程序使用已配置好的 XmlAdapter
实例。如果没有给出适配器实例,则 unmarshaller 将调用其默认构造方法创建一个实例。
type
- 适配器的类型。当 XmlJavaTypeAdapter.value()
引用此类型时,将使用指定的实例。adapter
- 将要使用的适配器实例。如果为 null,则将注销此类型的当前适配器集合。
IllegalArgumentException
- 如果 type 参数为 null。
UnsupportedOperationException
- 如果基于 JAXB 1.0 实现调用。<A extends XmlAdapter> A getAdapter(Class<A> type)
setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter)
方法的反向操作。
IllegalArgumentException
- 如果 type 参数为 null。
UnsupportedOperationException
- 如果基于 JAXB 1.0 实现调用。void setAttachmentUnmarshaller(AttachmentUnmarshaller au)
将解析 cid(内容 id URI)的上下文与作为附件传递的二进制数据关联。
通过 setSchema(Schema)
启用的解组时验证,即使在 unmarshaller 执行 XOP 处理时也必须支持。
IllegalStateException
- 如果试图在解组操作期间同时调用此方法。AttachmentUnmarshaller getAttachmentUnmarshaller()
void setListener(Unmarshaller.Listener listener)
向此 Unmarshaller
注册解组事件回调 Unmarshaller.Listener
。
每个 Unmarshaller 只有一个 Listener。设置 Listener 将替换以前设置的 Listener。通过将 listener 设置为 null 可注销当前的 Listener。
listener
- 为此 Unmarshaller
提供解组事件回调Unmarshaller.Listener getListener()
返回向此 Unmarshaller
注册的 Unmarshaller.Listener
。
Unmarshaller.Listener
;如果未向此 Unmarshaller 注册任何 Listener,则返回 null
。
|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。