当前页面: 在线文档首页 > JavaTM 2 Platform Standard Edition 6.0 API 规范中文版

Unmarshaller (Java Platform SE 6) - JavaTM 2 Platform Standard Edition 6.0 API 规范中文版

---

概述  软件包   类  使用  树  已过时  索引  帮助		JavaTM Platform Standard Ed. 6
上一个类   下一个类	框架    无框架
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

javax.xml.bind
接口 Unmarshaller

所有已知实现类：

AbstractUnmarshallerImpl

---

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 文档子树的 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) 中定义的顺序对它们进行调用。

抛出异常的事件回调方法会终止当前的解组过程。

从以下版本开始：

JAXB 1.0

另请参见：

JAXBContext, Marshaller, Validator

---

嵌套类摘要
static class	Unmarshaller.Listener            向 Unmarshaller 注册此类的一个实现的实例，以便外部侦听解组事件。

 

方法摘要
<A extends XmlAdapter> A	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()
<A extends XmlAdapter> void	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 数据并返回得到的内容树。
<T> JAXBElement<T>	unmarshal(Node node, Class<T> declaredType)           通过 JAXB 映射的 declaredType 解组 XML 数据并返回得到的内容树。
Object	unmarshal(Reader reader)           从指定的 Reader 解组 XML 数据并返回得到的内容树。
Object	unmarshal(Source source)           从指定的 XML Source 解组 XML 数据并返回得到的内容树。
<T> JAXBElement<T>	unmarshal(Source source, Class<T> declaredType)           从 declaredType 指定的 XML Source 解组 XML 数据并返回得到的内容树。
Object	unmarshal(URL url)           从指定的 URL 解组 XML 数据并返回得到的内容树。
Object	unmarshal(XMLEventReader reader)           从指定的 pull 解析器解组 XML 数据并返回得到的内容树。
<T> JAXBElement<T>	unmarshal(XMLEventReader reader, Class<T> declaredType)           将根元素解组到 JAXB 映射的 declaredType 并返回得到的内容树。
Object	unmarshal(XMLStreamReader reader)           从指定的 pull 解析器解组 XML 数据并返回得到的内容树。
<T> JAXBElement<T>	unmarshal(XMLStreamReader reader, Class<T> declaredType)           将根元素解组到 JAXB 映射的 declaredType 并返回得到的内容树。

 

方法详细信息

unmarshal

Object unmarshal(File f)
                 throws JAXBException

从指定的文件解组 XML 数据并返回得到的内容树。

实现解组全局根元素。

参数：

f - 将从中解组 XML 数据的文件

返回：

新创建的 java 内容树的根对象

抛出：

JAXBException - 如果在解组时发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或着 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据

IllegalArgumentException - 如果 File 参数为 null

---

unmarshal

Object unmarshal(InputStream is)
                 throws JAXBException

从指定的 InputStream 解组 XML 数据并返回得到的内容树。使用这种形式的 unmarshal API 时，验证事件位置信息可能不完整。

实现解组全局根元素。

参数：

is - 将从中解组 XML 数据的 InputStream

返回：

新创建的 java 内容树的根对象

抛出：

JAXBException - 如果在解组时发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据

IllegalArgumentException - 如果 InputStream 参数为 null

---

unmarshal

Object unmarshal(Reader reader)
                 throws JAXBException

从指定的 Reader 解组 XML 数据并返回得到的内容树。使用这种形式的 unmarshal API 时，验证事件位置信息可能不完整，这是因为 Reader 不提供系统 ID。

实现解组全局根元素。

参数：

reader - 将从中解组 XML 数据的 Reader

返回：

新创建的 java 内容树的根对象

抛出：

JAXBException - 如果在解组时发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据

IllegalArgumentException - 如果 InputStream 参数为 null

从以下版本开始：

JAXB 2.0

---

unmarshal

Object unmarshal(URL url)
                 throws JAXBException

从指定的 URL 解组 XML 数据并返回得到的内容树。

实现解组全局根元素。

参数：

url - 将从中解组 XML 数据的 URL

返回：

新创建的 java 内容树的根对象

抛出：

JAXBException - 如果在解组时发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据

IllegalArgumentException - 如果 URL 参数为 null

---

unmarshal

Object unmarshal(InputSource source)
                 throws JAXBException

从指定的 SAX InputSource 解组 XML 数据并返回得到的内容树。

实现解组全局根元素。

参数：

source - 将从中解组 XML 数据的输入源

返回：

新创建的 java 内容树的根对象

抛出：

JAXBException - 如果在解组时发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据

IllegalArgumentException - 如果 InputSource 参数为 null

---

unmarshal

Object unmarshal(Node node)
                 throws JAXBException

从指定的 DOM 树解组全局 XML 数据并返回得到的内容树。

实现解组全局根元素。

参数：

node - 要从中解组 XML 数据的文档/元素。调用者至少必须支持 Document 和 Element。

返回：

新创建的 java 内容树的根对象

抛出：

JAXBException - 如果在解组时发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据

IllegalArgumentException - 如果 Node 参数为 nul

另请参见：

unmarshal(org.w3c.dom.Node, Class)

---

unmarshal

<T> JAXBElement<T> unmarshal(Node node,
                             Class<T> declaredType)
                         throws JAXBException

通过 JAXB 映射的 declaredType 解组 XML 数据并返回得到的内容树。

实现借助声明的类型进行解组。

参数：

node - 从中解组 XML 数据的文档/元素。调用者至少必须支持 Document 和 Element。

declaredType - 用来保存 node 的 XML 数据的适当 JAXB 映射类。

返回：

node 的 JAXB Element 表示形式

抛出：

JAXBException - 如果在解组时发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据

IllegalArgumentException - 如果任何参数为 null

从以下版本开始：

6.0

---

unmarshal

Object unmarshal(Source source)
                 throws JAXBException

从指定的 XML Source 解组 XML 数据并返回得到的内容树。

实现解组全局根元素。

SAX 2.0 解析器的可插入性

客户端应用程序可以选择不使用随 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）

返回：

新创建的 java 内容树的根对象

抛出：

JAXBException - 如果在解组时发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据

IllegalArgumentException - 如果 Source 参数为 nul

另请参见：

unmarshal(javax.xml.transform.Source, Class)

---

unmarshal

<T> JAXBElement<T> unmarshal(Source source,
                             Class<T> declaredType)
                         throws JAXBException

从 declaredType 指定的 XML Source 解组 XML 数据并返回得到的内容树。

实现借助声明的类型进行解组。

请参阅 SAX 2.0 解析器的可插入性

参数：

source - 将从中解组 XML 数据的 XML Source（提供者只需支持 SAXSource、DOMSource 和 StreamSource）

declaredType - 用来保存 source 的 xml 根元素的适当 JAXB 映射类

返回：

通过 JAXB Element 确定的 Java 内容

抛出：

JAXBException - 如果在解组时发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据

IllegalArgumentException - 如果任何参数为 null

从以下版本开始：

JAXB 2.0

---

unmarshal

Object unmarshal(XMLStreamReader reader)
                 throws JAXBException

从指定的 pull 解析器解组 XML 数据并返回得到的内容树。

实现解组全局根元素。

此方法假定该解析器处于 START_DOCUMENT 或 START_ELEMENT 事件上。解组将从起始事件开始，到相应的终止事件结束。如果此方法成功返回，则 reader 将指向终止事件后面的标记。

参数：

reader - 要读取的解析器。

返回：

新创建的 java 内容树的根对象。

抛出：

JAXBException - 如果在解组时发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据

IllegalArgumentException - 如果 reader 参数为 null

IllegalStateException - 如果 reader 没有指向 START_DOCUMENT 或 START_ELEMENT 事件。

从以下版本开始：

JAXB 2.0

另请参见：

unmarshal(javax.xml.stream.XMLStreamReader, Class)

---

unmarshal

<T> JAXBElement<T> unmarshal(XMLStreamReader reader,
                             Class<T> declaredType)
                         throws JAXBException

将根元素解组到 JAXB 映射的 declaredType 并返回得到的内容树。

此方法实现借助 declaredType 进行解组。

此方法假定该解析器处于 START_DOCUMENT 或 START_ELEMENT 事件上。解组将从起始事件开始，到相应的终止事件结束。如果此方法成功返回，则 reader 将指向终止事件后面的标记。

参数：

reader - 要读取的解析器。

declaredType - 用来保存 reader 的 START_ELEMENT XML 数据的适当 JAXB 映射类。

返回：

通过 JAXB Element 表示形式确定的内容树

抛出：

JAXBException - 如果在解组时发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据

IllegalArgumentException - 如果任何参数为 null

从以下版本开始：

JAXB 2.0

---

unmarshal

Object unmarshal(XMLEventReader reader)
                 throws JAXBException

从指定的 pull 解析器解组 XML 数据并返回得到的内容树。

此方法是一个解组全局根方法。

此方法假定该解析器处于 START_DOCUMENT 或 START_ELEMENT 事件上。解组将从起始事件开始，到相应的终止事件结束。如果此方法成功返回，则 reader 将指向终止事件后面的标记。

参数：

reader - 要读取的解析器。

返回：

新创建的 java 内容树的根对象。

抛出：

JAXBException - 如果在解组时发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据

IllegalArgumentException - 如果 reader 参数为 null

IllegalStateException - 如果 reader 没有指向 START_DOCUMENT 或 START_ELEMENT 事件。

从以下版本开始：

JAXB 2.0

另请参见：

unmarshal(javax.xml.stream.XMLEventReader, Class)

---

unmarshal

<T> JAXBElement<T> unmarshal(XMLEventReader reader,
                             Class<T> declaredType)
                         throws JAXBException

将根元素解组到 JAXB 映射的 declaredType 并返回得到的内容树。

此方法实现借助 declaredType 进行解组。

此方法假定该解析器处于 START_DOCUMENT 或 START_ELEMENT 事件上。解组将从起始事件开始，到相应的终止事件结束。如果此方法成功返回，则 reader 将指向终止事件后面的标记。

参数：

reader - 要读取的解析器。

declaredType - 用来保存 reader 的 START_ELEMENT XML 数据的适当 JAXB 映射类。

返回：

通过 JAXB Element 表示形式确定的内容树

抛出：

JAXBException - 如果在解组时发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据

IllegalArgumentException - 如果任何参数为 null

从以下版本开始：

JAXB 2.0

---

getUnmarshallerHandler

UnmarshallerHandler getUnmarshallerHandler()

获取可用作 XML 管线中的组件的 unmarshaller 处理程序对象。

JAXB 提供者可以为此方法的多次调用返回相同的处理程序对象。换句话说，此方法不必创建新的 UnmarshallerHandler 实例。如果应用程序需要使用多个 UnmarshallerHandler，那么它应该创建多个 Unmarshaller。

返回：

返回 unmarshaller 处理程序对象

另请参见：

UnmarshallerHandler

---

setValidating

void setValidating(boolean validating)
                   throws JAXBException

已过时。 从 JAXB2.0 开始，请参阅 setSchema(javax.xml.validation.Schema)

指定 Unmarshaller 的默认验证机制是否应在解组操作期间执行验证。默认情况下，Unmarshaller 不执行验证。

此方法只能在调用某一 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 调用此方法，则抛出该异常

---

isValidating

boolean isValidating()
                     throws JAXBException

已过时。 从 JAXB 2.0 开始，请参阅 getSchema()

指示是否将 Unmarshaller 配置为在解组操作期间执行验证。

此 API 返回 JAXB 提供者的默认解组时验证机制的状态。

此方法从 JAXB 2.0 开始已经废弃，请使用新的 getSchema() API。

返回：

如果将 Unmarshaller 配置为在解组操作期间执行验证，则返回 true；否则返回 false

抛出：

JAXBException - 如果在检索验证标志时发生错误

UnsupportedOperationException - 如果对根据引用 JAXB 映射类的 JAXBContext 而创建的 Unmarshaller 调用此方法，则抛出该异常

---

setEventHandler

void setEventHandler(ValidationEventHandler handler)
                     throws JAXBException

允许应用程序注册 ValidationEventHandler。

如果在调用任何 unmarshal 方法期间遇到任何错误，则 ValidationEventHandler 将由 JAXB 提供者调用。如果客户端应用程序没有在调用 unmarshal 方法之前注册 ValidationEventHandler，则 ValidationEvents 将由默认事件处理程序处理，默认事件处理程序将在遇到第一个错误或致命错误时终止解组操作。

调用带有 null 参数的此方法将导致 Unmarshaller 重新使用默认事件处理程序。

参数：

handler - 验证事件处理程序

抛出：

JAXBException - 如果在设置事件处理程序期间遇到错误

---

getEventHandler

ValidationEventHandler getEventHandler()
                                       throws JAXBException

返回当前的事件处理程序，如果没有设置事件处理程序，则返回默认的事件处理程序。

返回：

当前的 ValidationEventHandler，如果没有设置处理程序，则返回默认的事件处理程序

抛出：

JAXBException - 如果获取当前的事件处理程序时遇到错误

---

setProperty

void setProperty(String name,
                 Object value)
                 throws PropertyException

设置 Unmarshaller 底层实现中的特定属性。此方法只能用于设置上文中标准 JAXB 定义的属性之一或特定于提供者的属性。试图设置未定义的属性将导致抛出 PropertyException。请参阅支持的属性。

参数：

name - 要设置的属性的名称。此值可以使用一个常量字段来指定，也可以是一个用户提供的字符串。

value - 要设置的属性值

抛出：

PropertyException - 如果处理给定属性或值时发生错误

IllegalArgumentException - 如果 name 参数为 null

---

getProperty

Object getProperty(String name)
                   throws PropertyException

获取 Unmarshaller 底层实现中的特定属性。此方法只能用于获取上文中标准 JAXB 定义的属性之一或特定于提供者的属性。试图获取未定义的属性将导致抛出 PropertyException。请参阅支持的属性。

参数：

name - 要检索的属性的名称

返回：

所请求属性的值

抛出：

PropertyException - 如果检索给定属性或值属性名称时发生错误

IllegalArgumentException - 如果 name 参数为 null

---

setSchema

void setSchema(Schema schema)

指定应用作验证后续解组操作依据的 JAXP 1.3 Schema 对象。向此方法传递 null 将禁用验证。

此方法将替换已过时的 setValidating(boolean) API。

最初，此属性被设置为 null。

参数：

schema - 作为验证解组操作依据的 Schema 对象；为 null 表示禁用验证

抛出：

UnsupportedOperationException - 如果对根据引用 JAXB 1.0 映射类的 JAXBContext 而创建的 Unmarshaller 调用此方法，则抛出该异常

从以下版本开始：

JAXB 2.0

---

getSchema

Schema getSchema()

获取用于执行解组时验证的 JAXP 1.3 Schema 对象。如果没有在 unmarshaller 上设置 Schema，则此方法将返回 null，指示不会执行解组时验证。

此方法用于替换已过时的 isValidating() API，并可访问 Schema 对象。要确定 Unmarshaller 是否启用了验证，只需测试返回类型是否为 null：

boolean isValidating = u.getSchema()!=null;

返回：

返回用于执行解组时验证的 Schema 对象；如果该对象不存在，则返回 null

抛出：

UnsupportedOperationException - 如果对根据引用 JAXB 1.0 映射类的 JAXBContext 而创建的 Unmarshaller 调用此方法，则抛出该异常

从以下版本开始：

JAXB 2.0

---

setAdapter

void setAdapter(XmlAdapter adapter)

将已配置的 XmlAdapter 实例与此 unmarshaller 关联。

这是调用 setAdapter(adapter.getClass(),adapter); 的一个便捷方法。

抛出：

IllegalArgumentException - 如果 adapter 参数为 null。

UnsupportedOperationException - 如果基于 JAXB 1.0 实现调用。

从以下版本开始：

JAXB 2.0

另请参见：

setAdapter(Class,XmlAdapter)

---

setAdapter

<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 实现调用。

从以下版本开始：

JAXB 2.0

---

getAdapter

<A extends XmlAdapter> A getAdapter(Class<A> type)

获取与指定类型关联的适配器。 这是 setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter) 方法的反向操作。

抛出：

IllegalArgumentException - 如果 type 参数为 null。

UnsupportedOperationException - 如果基于 JAXB 1.0 实现调用。

从以下版本开始：

JAXB 2.0

---

setAttachmentUnmarshaller

void setAttachmentUnmarshaller(AttachmentUnmarshaller au)

将解析 cid（内容 id URI）的上下文与作为附件传递的二进制数据关联。

通过 setSchema(Schema) 启用的解组时验证，即使在 unmarshaller 执行 XOP 处理时也必须支持。

抛出：

IllegalStateException - 如果试图在解组操作期间同时调用此方法。

---

getAttachmentUnmarshaller

AttachmentUnmarshaller getAttachmentUnmarshaller()

---

setListener

void setListener(Unmarshaller.Listener listener)

向此 Unmarshaller 注册解组事件回调 Unmarshaller.Listener。

每个 Unmarshaller 只有一个 Listener。设置 Listener 将替换以前设置的 Listener。通过将 listener 设置为 null 可注销当前的 Listener。

参数：

listener - 为此 Unmarshaller 提供解组事件回调

从以下版本开始：

JAXB 2.0

---

getListener

Unmarshaller.Listener getListener()

返回向此 Unmarshaller 注册的 Unmarshaller.Listener。

返回：

注册的 Unmarshaller.Listener；如果未向此 Unmarshaller 注册任何 Listener，则返回 null。

从以下版本开始：

JAXB 2.0

---

概述  软件包   类  使用  树  已过时  索引  帮助		JavaTM Platform Standard Ed. 6
上一个类   下一个类	框架    无框架
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。