Unmarshaller (Java EE 5)

Java EE API

previous page next page
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind Interface Unmarshaller

All Known Implementing Classes:
AbstractUnmarshallerImpl
public interface Unmarshaller

Inner classes: Unmarshaller.Listener
Implemented by: AbstractUnmarshallerImpl

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 数据的根元素时，应用程序可以使用通过声明的类型进行解组的方法帮助解组过程。在 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 方法使应用程序即使在根元素 XML 名称的 JAXBContext 中不存在映射时，也能够反序列化 XML 数据的根元素。该 unmarshaller 使用指定为 declaredType 参数的、应用程序提供的映射来解组根元素。注意，即使根元素的元素名称是通过 JAXBContext 映射的，declaredType 参数也会重写该映射，以便在使用这些 unmarshal 方法时反序列化根元素。此外，当 XML 数据的根元素具有 xsi:type 属性，且该属性的值引用一个通过 JAXBContext 映射到 JAXB 映射类的类型定义时，根元素的 xsi:type 属性将优先于 unmarshal 方法的 declaredType 参数。这些方法总是返回一个 JAXBElement<declaredType> 实例。下表显示了如何设置返回的 JAXBElement 实例的属性。

通过声明的类型进行解组所返回的 JAXBElement
JAXBElement 属性 值
name xml 元素名称
value instanceof declaredType
declaredType unmarshal 方法的 declaredType 参数
范围 null （实际范围未知）

以下是通过声明的类型进行解组的方法的一个示例。

通过 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 绑定解析器所生成的模式派生代码时，默认的解组验证处理程序是 javax.xml.bind.helpers.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);
类定义的回调方法应该在回调方法需要访问类的非公共方法和/或字段时使用。

外部侦听器回调机制允许 Listener 实例使用 setListener(Listener) 注册。外部侦听器接收所有回调事件，从而允许用比逐个类地定义回调方法更集中的方式处理事件。外部侦听器在解组过程将编组到 JAXB 元素或 JAXB 映射类时接收事件。

‘类定义的’侦听器事件回调方法和外部侦听器事件回调方法相互独立，但可以为一个事件同时调用两者。两种侦听器回调方法都存在时，按照 beforeUnmarshal(Object, Object) 和 afterUnmarshal(Object, Object) 中定义的顺序对它们进行调用。

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

version
en
$Revision: 1.32 $ $Date: 2005/08/18 15:18:26 $
sinceJAXB1.0
See also javax.xml.bind.JAXBContext, javax.xml.bind.Marshaller, javax.xml.bind.Validator
英文文档：

The Unmarshaller class governs the process of deserializing XML data into newly created Java content trees, optionally validating the XML data as it is unmarshalled. It provides an overloading of unmarshal methods for many different input kinds.

Unmarshalling from a File: 

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
       Object o = u.unmarshal( new File( "nosferatu.xml" ) );

Unmarshalling from an InputStream: 

       InputStream is = new FileInputStream( "nosferatu.xml" );
       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
       Object o = u.unmarshal( is );

Unmarshalling from a 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 );

Unmarshalling from a StringBuffer using a javax.xml.transform.stream.StreamSource: 

       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() ) ) );

Unmarshalling from a 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 );

Unmarshalling from a javax.xml.transform.sax.SAXSource using a client specified validating SAX2.0 parser: 

       // 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
       }

Unmarshalling from a 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 );

Unmarshalling from a 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 );

Unmarshalling XML Data

Unmarshalling can deserialize XML data that represents either an entire XML document or a subtree of an XML document. Typically, it is sufficient to use the unmarshalling methods described by Unmarshal root element that is declared globally. These unmarshal methods utilize JAXBContext's mapping of global XML element declarations and type definitions to JAXB mapped classes to initiate the unmarshalling of the root element of XML data. When the JAXBContext's mappings are not sufficient to unmarshal the root element of XML data, the application can assist the unmarshalling process by using the unmarshal by declaredType methods. These methods are useful for unmarshalling XML data where the root element corresponds to a local element declaration in the schema.
An unmarshal method never returns null. If the unmarshal process is unable to unmarshal the root of XML content to a JAXB mapped object, a fatal error is reported that terminates processing by throwing JAXBException.

Unmarshal a root element that is globally declared

The unmarshal methods that do not have an declaredType parameter use JAXBContext to unmarshal the root element of an XML data. The JAXBContext instance is the one that was used to create this Unmarshaller. The JAXBContext instance maintains a mapping of globally declared XML element and type definition names to JAXB mapped classes. The unmarshal method checks if JAXBContext has a mapping from the root element's XML name and/or @xsi:type to a JAXB mapped class. If it does, it umarshalls the XML data using the appropriate JAXB mapped class. Note that when the root element name is unknown and the root element has an @xsi:type, the XML data is unmarshalled using that JAXB mapped class as the value of a JAXBElement. When the JAXBContext object does not have a mapping for the root element's name nor its @xsi:type, if it exists, then the unmarshal operation will abort immediately by throwing a UnmarshalException. This exception scenario can be worked around by using the unmarshal by declaredType methods described in the next subsection.

Unmarshal by Declared Type

The unmarshal methods with a declaredType parameter enable an application to deserialize a root element of XML data, even when there is no mapping in JAXBContext of the root element's XML name. The unmarshaller unmarshals the root element using the application provided mapping specified as the declaredType parameter. Note that even when the root element's element name is mapped by JAXBContext, the declaredType parameter overrides that mapping for deserializing the root element when using these unmarshal methods. Additionally, when the root element of XML data has an xsi:type attribute and that attribute's value references a type definition that is mapped to a JAXB mapped class by JAXBContext, that the root element's xsi:type attribute takes precedence over the unmarshal methods declaredType parameter. These methods always return a JAXBElement<declaredType> instance. The table below shows how the properties of the returned JAXBElement instance are set.

Unmarshal By Declared Type returned JAXBElement
JAXBElement Property Value
name xml element name
value instanceof declaredType
declaredType unmarshal method declaredType parameter
scope null (actual scope is unknown)

The following is an example of unmarshal by declaredType method.

Unmarshal by declaredType from a 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);

Support for SAX2.0 Compliant Parsers

A client application has the ability to select the SAX2.0 compliant parser of their choice. If a SAX parser is not selected, then the JAXB Provider's default parser will be used. Even though the JAXB Provider's default parser is not required to be SAX2.0 compliant, all providers are required to allow a client application to specify their own SAX2.0 parser. Some providers may require the client application to specify the SAX2.0 parser at schema compile time. See unmarshal(Source) for more detail.

Validation and Well-Formedness

A client application can enable or disable JAXP 1.3 validation mechanism via the setSchema(javax.xml.validation.Schema) API. Sophisticated clients can specify their own validating SAX 2.0 compliant parser and bypass the JAXP 1.3 validation mechanism using the unmarshal(Source) API.

Since unmarshalling invalid XML content is defined in JAXB 2.0, the Unmarshaller default validation event handler was made more lenient than in JAXB 1.0. When schema-derived code generated by JAXB 1.0 binding compiler is registered with JAXBContext, the default unmarshal validation handler is DefaultValidationEventHandler and it terminates the marshal operation after encountering either a fatal error or an error. For a JAXB 2.0 client application, there is no explicitly defined default validation handler and the default event handling only terminates the marshal operation after encountering a fatal error.

Supported Properties

There currently are not any properties required to be supported by all JAXB Providers on Unmarshaller. However, some providers may support their own set of provider specific properties.

Unmarshal Event Callbacks

The Unmarshaller provides two styles of callback mechanisms that allow application specific processing during key points in the unmarshalling process. In 'class defined' event callbacks, application specific code placed in JAXB mapped classes is triggered during unmarshalling. 'External listeners' allow for centralized processing of unmarshal events in one callback method rather than by type event callbacks.

'Class defined' event callback methods allow any JAXB mapped class to specify its own specific callback methods by defining methods with the following method signature: 

   // 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);
The class defined callback methods should be used when the callback method requires access to non-public methods and/or fields of the class.

The external listener callback mechanism enables the registration of a Unmarshaller.Listener instance with an setListener(Listener). The external listener receives all callback events, allowing for more centralized processing than per class defined callback methods. The external listener receives events when unmarshalling proces is marshalling to a JAXB element or to JAXB mapped class.

The 'class defined' and external listener event callback methods are independent of each other, both can be called for one event. The invocation ordering when both listener callback methods exist is defined in Unmarshaller.Listener.beforeUnmarshal(Object, Object) and Unmarshaller.Listener.afterUnmarshal(Object, Object).

An event callback method throwing an exception terminates the current unmarshal process.

Since:
JAXB1.0
Version:
$Revision: 1.32 $ $Date: 2005/08/18 15:18:26 $
Author:
  • Ryan Shoemaker, Sun Microsystems, Inc.
  • Kohsuke Kawaguchi, Sun Microsystems, Inc.
  • Joe Fialli, Sun Microsystems, Inc.
See Also:
JAXBContext, Marshaller, Validator

Nested Class Summary
static class Unmarshaller.Listener
          

Register an instance of an implementation of this class with Unmarshaller to externally listen for unmarshal events.
 
Method Summary
<A extends XmlAdapter>
A
getAdapter(Class<A> type)
          Gets the adapter associated with the specified type.  AttachmentUnmarshaller getAttachmentUnmarshaller()
             ValidationEventHandler getEventHandler()
          Return the current event handler or the default event handler if one hasn't been set.  Unmarshaller.Listener getListener()
          Return Unmarshaller.Listener registered with this Unmarshaller.  Object getProperty(String name)
          Get the particular property in the underlying implementation of Unmarshaller.  Schema getSchema()
          Get the JAXP 1.3 Schema object being used to perform unmarshal-time validation.  UnmarshallerHandler getUnmarshallerHandler()
          Get an unmarshaller handler object that can be used as a component in an XML pipeline.  boolean isValidating()
          Deprecated. since JAXB2.0, please see getSchema()
<A extends XmlAdapter>
void
setAdapter(Class<A> type, A adapter)
          Associates a configured instance of XmlAdapter with this unmarshaller.  void setAdapter(XmlAdapter adapter)
          Associates a configured instance of XmlAdapter with this unmarshaller.  void setAttachmentUnmarshaller(AttachmentUnmarshaller au)
          Associate a context that resolves cid's, content-id URIs, to binary data passed as attachments.  void setEventHandler(ValidationEventHandler handler)
          Allow an application to register a ValidationEventHandler.  void setListener(Unmarshaller.Listener listener)
           Register unmarshal event callback Unmarshaller.Listener with this Unmarshaller.  void setProperty(String name, Object value)
          Set the particular property in the underlying implementation of Unmarshaller.  void setSchema(Schema schema)
          Specify the JAXP 1.3 Schema object that should be used to validate subsequent unmarshal operations against.  void setValidating(boolean validating)
          Deprecated. since JAXB2.0, please see setSchema(javax.xml.validation.Schema)  Object unmarshal(File f)
          Unmarshal XML data from the specified file and return the resulting content tree.  Object unmarshal(InputSource source)
          Unmarshal XML data from the specified SAX InputSource and return the resulting content tree.  Object unmarshal(InputStream is)
          Unmarshal XML data from the specified InputStream and return the resulting content tree.  Object unmarshal(Node node)
          Unmarshal global XML data from the specified DOM tree and return the resulting content tree.
<T> JAXBElement<T>
unmarshal(Node node, Class<T> declaredType)
          Unmarshal XML data by JAXB mapped declaredType and return the resulting content tree.  Object unmarshal(Reader reader)
          Unmarshal XML data from the specified Reader and return the resulting content tree.  Object unmarshal(Source source)
          Unmarshal XML data from the specified XML Source and return the resulting content tree.
<T> JAXBElement<T>
unmarshal(Source source, Class<T> declaredType)
          Unmarshal XML data from the specified XML Source by declaredType and return the resulting content tree.  Object unmarshal(URL url)
          Unmarshal XML data from the specified URL and return the resulting content tree.  Object unmarshal(XMLEventReader reader)
          Unmarshal XML data from the specified pull parser and return the resulting content tree.
<T> JAXBElement<T>
unmarshal(XMLEventReader reader, Class<T> declaredType)
          Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.  Object unmarshal(XMLStreamReader reader)
          Unmarshal XML data from the specified pull parser and return the resulting content tree.
<T> JAXBElement<T>
unmarshal(XMLStreamReader reader, Class<T> declaredType)
          Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.  

Method Detail

public Object unmarshal(java.io.File f) throws JAXBException
从指定的文件解组 XML 数据并返回得到的内容树。

实现解组全局根元素。

f 将从中解组 XML 数据的文件
return 新创建的 java 内容树的根对象
ThrowsJAXBException: 如果进行解组期间发生不可预料的错误
ThrowsUnmarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或着 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据
ThrowsIllegalArgumentException: 如果 File 参数为 null

英文文档：

unmarshal

Object unmarshal(File f)
                 throws JAXBException
Unmarshal XML data from the specified file and return the resulting content tree.

Implements Unmarshal Global Root Element.

Parameters:
f - the file to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the file parameter is null

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

实现解组全局根元素。

is 将从中解组 XML 数据的 InputStream
return 新创建的 java 内容树的根对象
ThrowsJAXBException: 如果进行解组期间发生不可预料的错误
ThrowsUnmarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或着 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据
ThrowsIllegalArgumentException: 如果 InputStream 参数为 null

英文文档：

unmarshal

Object unmarshal(InputStream is)
                 throws JAXBException
Unmarshal XML data from the specified InputStream and return the resulting content tree. Validation event location information may be incomplete when using this form of the unmarshal API.

Implements Unmarshal Global Root Element.

Parameters:
is - the InputStream to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the InputStream parameter is null

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

实现解组全局根元素。

reader 将从中解组 XML 数据的 Reader
return 新创建的 java 内容树的根对象
ThrowsJAXBException: 如果进行解组期间发生不可预料的错误
ThrowsUnmarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据
ThrowsIllegalArgumentException: 如果 InputStream 参数为 null
sinceJAXB2.0

英文文档：

unmarshal

Object unmarshal(Reader reader)
                 throws JAXBException
Unmarshal XML data from the specified Reader and return the resulting content tree. Validation event location information may be incomplete when using this form of the unmarshal API, because a Reader does not provide the system ID.

Implements Unmarshal Global Root Element.

Parameters:
reader - the Reader to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the InputStream parameter is null
Since:
JAXB2.0

public Object unmarshal(java.net.URL url) throws JAXBException
从指定的 URL 解组 XML 数据并返回得到的内容树。

实现解组全局根元素。

url 将从中解组 XML 数据的 URL
return 新创建的 java 内容树的根对象
ThrowsJAXBException: 如果进行解组期间发生不可预料的错误
ThrowsUnmarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或着 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据
ThrowsIllegalArgumentException: 如果 URL 参数为 null

英文文档：

unmarshal

Object unmarshal(URL url)
                 throws JAXBException
Unmarshal XML data from the specified URL and return the resulting content tree.

Implements Unmarshal Global Root Element.

Parameters:
url - the url to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the URL parameter is null

public Object unmarshal(org.xml.sax.InputSource source) throws JAXBException
从指定的 SAX InputSource 解组 XML 数据并返回得到的内容树。

实现解组全局根元素。

source 将从中解组 XML 数据的输入源
return 新创建的 java 内容树的根对象
ThrowsJAXBException: 如果进行解组期间发生不可预料的错误
ThrowsUnmarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或着 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据
ThrowsIllegalArgumentException: 如果 InputSource 参数为 null

英文文档：

unmarshal

Object unmarshal(InputSource source)
                 throws JAXBException
Unmarshal XML data from the specified SAX InputSource and return the resulting content tree.

Implements Unmarshal Global Root Element.

Parameters:
source - the input source to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the InputSource parameter is null

public Object unmarshal(org.w3c.dom.Node node) throws JAXBException
从指定的 DOM 树解组全局 XML 数据并返回得到的内容树。

实现解组全局根元素。

node 要从中解组 XML 数据的文档/元素。调用者至少必须支持 Document 和 Element。
return 新创建的 java 内容树的根对象
ThrowsJAXBException: 如果进行解组期间发生不可预料的错误
ThrowsUnmarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或着 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据
ThrowsIllegalArgumentException: 如果 Node 参数为 nul
See also unmarshal(org.w3c.dom.Node, Class)

英文文档：

unmarshal

Object unmarshal(Node node)
                 throws JAXBException
Unmarshal global XML data from the specified DOM tree and return the resulting content tree.

Implements Unmarshal Global Root Element.

Parameters:
node - the document/element to unmarshal XML data from. The caller must support at least Document and Element.
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the Node parameter is null
See Also:
unmarshal(org.w3c.dom.Node, Class)

英文文档：

unmarshal 

<T> JAXBElement<T> unmarshal(Node node,
                             Class<T> declaredType)
                         throws JAXBException
Unmarshal XML data by JAXB mapped declaredType and return the resulting content tree.

Implements Unmarshal by Declared Type

Parameters:
node - the document/element to unmarshal XML data from. The caller must support at least Document and Element.
declaredType - appropriate JAXB mapped class to hold node's XML data.
Returns:
JAXB Element representation of node
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If any parameter is null
Since:
JAXB2.0

public Object unmarshal(javax.xml.transform.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）
return 新创建的 java 内容树的根对象
ThrowsJAXBException: 如果进行解组期间发生不可预料的错误
ThrowsUnmarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或着 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据
ThrowsIllegalArgumentException: 如果 Source 参数为 nul
See also unmarshal(javax.xml.transform.Source, Class)

英文文档：

unmarshal

Object unmarshal(Source source)
                 throws JAXBException
Unmarshal XML data from the specified XML Source and return the resulting content tree.

Implements Unmarshal Global Root Element.

SAX 2.0 Parser Pluggability

A client application can choose not to use the default parser mechanism supplied with their JAXB provider. Any SAX 2.0 compliant parser can be substituted for the JAXB provider's default mechanism. To do so, the client application must properly configure a SAXSource containing an XMLReader implemented by the SAX 2.0 parser provider. If the XMLReader has an org.xml.sax.ErrorHandler registered on it, it will be replaced by the JAXB Provider so that validation errors can be reported via the ValidationEventHandler mechanism of JAXB. If the SAXSource does not contain an XMLReader, then the JAXB provider's default parser mechanism will be used.

This parser replacement mechanism can also be used to replace the JAXB provider's unmarshal-time validation engine. The client application must properly configure their SAX 2.0 compliant parser to perform validation (as shown in the example above). Any SAXParserExceptions encountered by the parser during the unmarshal operation will be processed by the JAXB provider and converted into JAXB ValidationEvent objects which will be reported back to the client via the ValidationEventHandler registered with the Unmarshaller. Note: specifying a substitute validating SAX 2.0 parser for unmarshalling does not necessarily replace the validation engine used by the JAXB provider for performing on-demand validation.

The only way for a client application to specify an alternate parser mechanism to be used during unmarshal is via the unmarshal(SAXSource) API. All other forms of the unmarshal method (File, URL, Node, etc) will use the JAXB provider's default parser and validator mechanisms.

Parameters:
source - the XML Source to unmarshal XML data from (providers are only required to support SAXSource, DOMSource, and StreamSource)
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the Source parameter is null
See Also:
unmarshal(javax.xml.transform.Source, Class)

英文文档：

unmarshal 

<T> JAXBElement<T> unmarshal(Source source,
                             Class<T> declaredType)
                         throws JAXBException
Unmarshal XML data from the specified XML Source by declaredType and return the resulting content tree.

Implements Unmarshal by Declared Type

See SAX 2.0 Parser Pluggability

Parameters:
source - the XML Source to unmarshal XML data from (providers are only required to support SAXSource, DOMSource, and StreamSource)
declaredType - appropriate JAXB mapped class to hold source's xml root element
Returns:
Java content rooted by JAXB Element
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If any parameter is null
Since:
JAXB2.0

public Object unmarshal(XMLStreamReader reader) throws JAXBException
从指定的 pull 解析器解组 XML 数据并返回得到的内容树。

实现解组全局根元素。

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

reader 要读取的解析器。
return 新创建的 java 内容树的根对象。
ThrowsJAXBException: 如果进行解组期间发生不可预料的错误
ThrowsUnmarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或着 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据
ThrowsIllegalArgumentException: 如果 reader 参数为 null
ThrowsIllegalStateException: 如果 reader 没有指向 START_DOCUMENT 或 START_ELEMENT 事件。
sinceJAXB2.0
See also unmarshal(javax.xml.stream.XMLStreamReader, Class)

英文文档：

unmarshal

Object unmarshal(XMLStreamReader reader)
                 throws JAXBException
Unmarshal XML data from the specified pull parser and return the resulting content tree.

Implements Unmarshal Global Root Element.

This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the reader will be pointing at the token right after the end event.

Parameters:
reader - The parser to be read.
Returns:
the newly created root object of the java content tree.
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the reader parameter is null
IllegalStateException - If reader is not pointing to a START_DOCUMENT or START_ELEMENT event.
Since:
JAXB2.0
See Also:
unmarshal(javax.xml.stream.XMLStreamReader, Class)

英文文档：

unmarshal 

<T> JAXBElement<T> unmarshal(XMLStreamReader reader,
                             Class<T> declaredType)
                         throws JAXBException
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.

This method implements unmarshal by declaredType.

This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the reader will be pointing at the token right after the end event.

Parameters:
reader - The parser to be read.
declaredType - appropriate JAXB mapped class to hold reader's START_ELEMENT XML data.
Returns:
content tree rooted by JAXB Element representation
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If any parameter is null
Since:
JAXB2.0

public Object unmarshal(XMLEventReader reader) throws JAXBException
从指定的 pull 解析器解组 XML 数据并返回得到的内容树。

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

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

reader 要读取的解析器。
return 新创建的 java 内容树的根对象。
ThrowsJAXBException: 如果进行解组期间发生不可预料的错误
ThrowsUnmarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或着 Unmarshaller 不能执行 XML 到 Java 的绑定。请参阅解组 XML 数据
ThrowsIllegalArgumentException: 如果 reader 参数为 null
ThrowsIllegalStateException: 如果 reader 没有指向 START_DOCUMENT 或 START_ELEMENT 事件。
sinceJAXB2.0
See also unmarshal(javax.xml.stream.XMLEventReader, Class)

英文文档：

unmarshal

Object unmarshal(XMLEventReader reader)
                 throws JAXBException
Unmarshal XML data from the specified pull parser and return the resulting content tree.

This method is an Unmarshal Global Root method.

This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the reader will be pointing at the token right after the end event.

Parameters:
reader - The parser to be read.
Returns:
the newly created root object of the java content tree.
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the reader parameter is null
IllegalStateException - If reader is not pointing to a START_DOCUMENT or START_ELEMENT event.
Since:
JAXB2.0
See Also:
unmarshal(javax.xml.stream.XMLEventReader, Class)

英文文档：

unmarshal 

<T> JAXBElement<T> unmarshal(XMLEventReader reader,
                             Class<T> declaredType)
                         throws JAXBException
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.

This method implements unmarshal by declaredType.

This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the reader will be pointing at the token right after the end event.

Parameters:
reader - The parser to be read.
declaredType - appropriate JAXB mapped class to hold reader's START_ELEMENT XML data.
Returns:
content tree rooted by JAXB Element representation
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If any parameter is null
Since:
JAXB2.0

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

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

return 返回 unmarshaller 处理程序对象
See also javax.xml.bind.UnmarshallerHandler

英文文档：

getUnmarshallerHandler

UnmarshallerHandler getUnmarshallerHandler()
Get an unmarshaller handler object that can be used as a component in an XML pipeline.

The JAXB Provider can return the same handler object for multiple invocations of this method. In other words, this method does not necessarily create a new instance of UnmarshallerHandler. If the application needs to use more than one UnmarshallerHandler, it should create more than one Unmarshaller.

Returns:
the unmarshaller handler object
See Also:
UnmarshallerHandler

public void setValidating(boolean validating) throws JAXBException
指定 Unmarshaller 的默认验证机制是否应在解组操作期间执行验证。默认情况下，Unmarshaller 不执行验证。

此方法只能在调用某一 unmarshal 方法之前或之后调用。

此方法只控制 JAXB 提供者的默认解组时验证机制，不会影响指定自己的验证兼容 SAX 2.0 的解析器的客户端。指定自己的解组时验证机制的客户端可能希望通过此 API 关闭 JAXB 提供者的默认验证机制，以避免“双重验证”。

此方法从 JAXB 2.0 开始已经废弃，请使用新的 #setSchema(javax.xml.validation.Schema) API。

validating 如果 Unmarshaller 应该在解组期间执行验证，则该参数为 true；否则为 false
ThrowsJAXBException: 如果在解组期间启用或禁用验证时发生错误
ThrowsUnsupportedOperationException: 如果对根据引用 JAXB 2.0 映射类的 JAXBContext 而创建的 Unmarshaller 调用此方法，则抛出该异常
deprecated 从 JAXB2.0 开始，请参阅 #setSchema(javax.xml.validation.Schema)

英文文档：

setValidating

void setValidating(boolean validating)
                   throws JAXBException
Deprecated. since JAXB2.0, please see setSchema(javax.xml.validation.Schema)

Specifies whether or not the default validation mechanism of the Unmarshaller should validate during unmarshal operations. By default, the Unmarshaller does not validate.

This method may only be invoked before or after calling one of the unmarshal methods.

This method only controls the JAXB Provider's default unmarshal-time validation mechanism - it has no impact on clients that specify their own validating SAX 2.0 compliant parser. Clients that specify their own unmarshal-time validation mechanism may wish to turn off the JAXB Provider's default validation mechanism via this API to avoid "double validation".

This method is deprecated as of JAXB 2.0 - please use the new setSchema(javax.xml.validation.Schema) API.

Parameters:
validating - true if the Unmarshaller should validate during unmarshal, false otherwise
Throws:
JAXBException - if an error occurred while enabling or disabling validation at unmarshal time
UnsupportedOperationException - could be thrown if this method is invoked on an Unmarshaller created from a JAXBContext referencing JAXB 2.0 mapped classes

public boolean isValidating() throws JAXBException
指示是否将 Unmarshaller 配置为在解组操作期间执行验证。

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

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

return 如果将 Unmarshaller 配置为在解组操作期间执行验证，则返回 true；否则返回 false
ThrowsJAXBException: 如果在检索验证标志时发生错误
ThrowsUnsupportedOperationException: 如果对根据引用 JAXB 2.0 映射类的 JAXBContext 而创建的 Unmarshaller 调用此方法，则抛出该异常
deprecated 从 JAXB 2.0 开始，请参阅 #getSchema()

英文文档：

isValidating

boolean isValidating()
                     throws JAXBException
Deprecated. since JAXB2.0, please see getSchema()

Indicates whether or not the Unmarshaller is configured to validate during unmarshal operations.

This API returns the state of the JAXB Provider's default unmarshal-time validation mechanism.

This method is deprecated as of JAXB 2.0 - please use the new getSchema() API.

Returns:
true if the Unmarshaller is configured to validate during unmarshal operations, false otherwise
Throws:
JAXBException - if an error occurs while retrieving the validating flag
UnsupportedOperationException - could be thrown if this method is invoked on an Unmarshaller created from a JAXBContext referencing JAXB 2.0 mapped classes

public void setEventHandler(ValidationEventHandler handler) throws JAXBException
允许应用程序注册 ValidationEventHandler。

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

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

handler 验证事件处理程序
ThrowsJAXBException: 如果在设置事件处理程序时发生错误

英文文档：

setEventHandler

void setEventHandler(ValidationEventHandler handler)
                     throws JAXBException
Allow an application to register a ValidationEventHandler.

The ValidationEventHandler will be called by the JAXB Provider if any validation errors are encountered during calls to any of the unmarshal methods. If the client application does not register a ValidationEventHandler before invoking the unmarshal methods, then ValidationEvents will be handled by the default event handler which will terminate the unmarshal operation after the first error or fatal error is encountered.

Calling this method with a null parameter will cause the Unmarshaller to revert back to the default event handler.

Parameters:
handler - the validation event handler
Throws:
JAXBException - if an error was encountered while setting the event handler

public ValidationEventHandler getEventHandler() throws JAXBException
当前的事件处理程序；如果没有设置，则返回默认事件处理程序。
return 当前的 ValidationEventHandler；如果没有设置，则返回默认的事件处理程序
ThrowsJAXBException: 如果获取当前的事件处理程序时遇到错误
英文文档：

getEventHandler

ValidationEventHandler getEventHandler()
                                       throws JAXBException
Return the current event handler or the default event handler if one hasn't been set.

Returns:
the current ValidationEventHandler or the default event handler if it hasn't been set
Throws:
JAXBException - if an error was encountered while getting the current event handler

public void setProperty(String name, Object value) throws PropertyException
设置 Unmarshaller 底层实现中的特定属性。此方法只能用于设置上文中标准 JAXB 定义的属性之一或特定于提供者的属性。试图设置未定义的属性将导致抛出 PropertyException。请参阅支持的属性。
name 要设置的属性的名称。此值可以使用一个常量字段来指定，也可以是用户提供的字符串。
value 要设置的属性值
ThrowsPropertyException: 如果处理给定属性或值时发生错误
ThrowsIllegalArgumentException: 如果 name 参数为 null
英文文档：

setProperty

void setProperty(String name,
                 Object value)
                 throws PropertyException
Set the particular property in the underlying implementation of Unmarshaller. This method can only be used to set one of the standard JAXB defined properties above or a provider specific property. Attempting to set an undefined property will result in a PropertyException being thrown. See Supported Properties.

Parameters:
name - the name of the property to be set. This value can either be specified using one of the constant fields or a user supplied string.
value - the value of the property to be set
Throws:
PropertyException - when there is an error processing the given property or value
IllegalArgumentException - If the name parameter is null

public Object getProperty(String name) throws PropertyException
获取 Unmarshaller 底层实现中的特定属性。此方法只能用于获取上文中标准 JAXB 定义的属性之一或特定于提供者的属性。试图获取未定义的属性将导致抛出 PropertyException。请参阅支持的属性。
name 将检索的属性名称
return 所请求属性的值
ThrowsPropertyException: 如果检索给定属性或值属性名称时发生错误
ThrowsIllegalArgumentException: 如果 name 参数为 null
英文文档：

getProperty

Object getProperty(String name)
                   throws PropertyException
Get the particular property in the underlying implementation of Unmarshaller. This method can only be used to get one of the standard JAXB defined properties above or a provider specific property. Attempting to get an undefined property will result in a PropertyException being thrown. See Supported Properties.

Parameters:
name - the name of the property to retrieve
Returns:
the value of the requested property
Throws:
PropertyException - when there is an error retrieving the given property or value property name
IllegalArgumentException - If the name parameter is null

public void setSchema(javax.xml.validation.Schema schema)
指定应用作验证后续解组操作依据的 JAXP 1.3 Schema 对象。向此方法传递 null 将禁用验证。

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

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

schema 作为验证解组操作依据的 Schema 对象；为 null 表示禁用验证
ThrowsUnsupportedOperationException: 如果对根据引用 JAXB 1.0 映射类的 JAXBContext 而创建的 Unmarshaller 调用此方法，则抛出该异常
sinceJAXB2.0

英文文档：

setSchema

void setSchema(Schema schema)
Specify the JAXP 1.3 Schema object that should be used to validate subsequent unmarshal operations against. Passing null into this method will disable validation.

This method replaces the deprecated setValidating(boolean) API.

Initially this property is set to null.

Parameters:
schema - Schema object to validate unmarshal operations against or null to disable validation
Throws:
UnsupportedOperationException - could be thrown if this method is invoked on an Unmarshaller created from a JAXBContext referencing JAXB 1.0 mapped classes
Since:
JAXB2.0

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

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

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

return 返回用于执行解组时验证的 Schema 对象；如果该对象不存在，则返回 null
ThrowsUnsupportedOperationException: 如果对根据引用 JAXB 1.0 映射类的 JAXBContext 而创建的 Unmarshaller 调用此方法，则抛出该异常
sinceJAXB2.0

英文文档：

getSchema

Schema getSchema()
Get the JAXP 1.3 Schema object being used to perform unmarshal-time validation. If there is no Schema set on the unmarshaller, then this method will return null indicating that unmarshal-time validation will not be performed.

This method provides replacement functionality for the deprecated isValidating() API as well as access to the Schema object. To determine if the Unmarshaller has validation enabled, simply test the return type for null:

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

Returns:
the Schema object being used to perform unmarshal-time validation or null if not present
Throws:
UnsupportedOperationException - could be thrown if this method is invoked on an Unmarshaller created from a JAXBContext referencing JAXB 1.0 mapped classes
Since:
JAXB2.0

public void setAdapter(">XmlAdapter adapter)
将已配置的 XmlAdapter 实例与此 unmarshaller 关联。

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

ThrowsIllegalArgumentException: 如果 adapter 参数为 null。
ThrowsUnsupportedOperationException: 如果基于 JAXB 1.0 实现调用。
sinceJAXB2.0
See also setAdapter(Class,XmlAdapter)

英文文档：

setAdapter

void setAdapter(XmlAdapter adapter)
Associates a configured instance of XmlAdapter with this unmarshaller.

This is a convenience method that invokes setAdapter(adapter.getClass(),adapter);.

Throws:
IllegalArgumentException - if the adapter parameter is null.
UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.
Since:
JAXB2.0
See Also:
setAdapter(Class,XmlAdapter)

英文文档：

setAdapter 

<A extends XmlAdapter> void setAdapter(Class<A> type,
                                       A adapter)
Associates a configured instance of XmlAdapter with this unmarshaller.

Every unmarshaller internally maintains a Map<Class,XmlAdapter>, which it uses for unmarshalling classes whose fields/methods are annotated with XmlJavaTypeAdapter.

This method allows applications to use a configured instance of XmlAdapter. When an instance of an adapter is not given, an unmarshaller will create one by invoking its default constructor.

Parameters:
type - The type of the adapter. The specified instance will be used when XmlJavaTypeAdapter.value() refers to this type.
adapter - The instance of the adapter to be used. If null, it will un-register the current adapter set for this type.
Throws:
IllegalArgumentException - if the type parameter is null.
UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.
Since:
JAXB2.0

英文文档：

getAdapter 

<A extends XmlAdapter> A getAdapter(Class<A> type)
Gets the adapter associated with the specified type. This is the reverse operation of the setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter) method.

Throws:
IllegalArgumentException - if the type parameter is null.
UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.
Since:
JAXB2.0

public void setAttachmentUnmarshaller(AttachmentUnmarshaller au)

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

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

ThrowsIllegalStateException: 如果试图在解组操作期间同时调用此方法。
英文文档：

setAttachmentUnmarshaller

void setAttachmentUnmarshaller(AttachmentUnmarshaller au)

Associate a context that resolves cid's, content-id URIs, to binary data passed as attachments.

Unmarshal time validation, enabled via setSchema(Schema), must be supported even when unmarshaller is performing XOP processing.

Throws:
IllegalStateException - if attempt to concurrently call this method during a unmarshal operation.

public AttachmentUnmarshaller getAttachmentUnmarshaller()
英文文档：

getAttachmentUnmarshaller

AttachmentUnmarshaller getAttachmentUnmarshaller()

public void setListener(Unmarshaller.Listener listener)

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

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

listener 为此 Unmarshaller 提供解组事件回调
sinceJAXB2.0

英文文档：

setListener

void setListener(Unmarshaller.Listener listener)

Register unmarshal event callback Unmarshaller.Listener with this Unmarshaller.

There is only one Listener per Unmarshaller. Setting a Listener replaces the previous set Listener. One can unregister current Listener by setting listener to null.

Parameters:
listener - provides unmarshal event callbacks for this Unmarshaller
Since:
JAXB2.0

public Unmarshaller.Listener getListener()

返回向此 Unmarshaller 注册的 Listener。

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

英文文档：

getListener

Unmarshaller.Listener getListener()

Return Unmarshaller.Listener registered with this Unmarshaller.

Returns:
registered Unmarshaller.Listener or null if no Listener is registered with this Unmarshaller.
Since:
JAXB2.0
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.

一看就知道只有菜鸟才干这么无知的事啦。

PS : 未经我党受权你也可自由散发此文档。 如有任何错误请自行修正；若因此而造成任何损失请直接找人民主席，请勿与本人联系。谢谢！

previous page start next page