unmarshaller.html

来自「j2ee帮助文档软件设计/软件工程 文件格式」· HTML 代码 · 共 1,146 行 · 第 1/5 页

 <p>
 Unmarshalling from a StAX XMLEventReader:
 <blockquote>
    <pre>
       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 );
    </pre>
 </blockquote>

 <p>
 <a name="unmarshalEx"></a>
 <b>Unmarshalling XML Data</b><br>
 <blockquote>
 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  
 <a href="#unmarshalGlobal">Unmarshal root element that is declared globally</a>.
 These unmarshal methods utilize <A HREF="../../../javax/xml/bind/JAXBContext.html" title="class in javax.xml.bind"><CODE>JAXBContext</CODE></A>'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 <A HREF="../../../javax/xml/bind/JAXBContext.html" title="class in javax.xml.bind"><CODE>JAXBContext</CODE></A>'s 
 mappings are not sufficient to unmarshal the root element of XML data, 
 the application can assist the unmarshalling process by using the 
 <a href="#unmarshalByDeclaredType">unmarshal by declaredType methods</a>.
 These methods are useful for unmarshalling XML data where
 the root element corresponds to a local element declaration in the schema.
 </blockquote>
 
 <blockquote>
 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.
 </blockquote>

 <p>
 <a name="unmarshalGlobal"></a>
 <b>Unmarshal a root element that is globally declared</b><br>
 <blockquote>
 The unmarshal methods that do not have an <tt>declaredType</tt> parameter use 
 <A HREF="../../../javax/xml/bind/JAXBContext.html" title="class in javax.xml.bind"><CODE>JAXBContext</CODE></A> to unmarshal the root element of an XML data. The <A HREF="../../../javax/xml/bind/JAXBContext.html" title="class in javax.xml.bind"><CODE>JAXBContext</CODE></A> 
 instance is the one that was used to create this <tt>Unmarshaller</tt>. The <A HREF="../../../javax/xml/bind/JAXBContext.html" title="class in javax.xml.bind"><CODE>JAXBContext</CODE></A> 
 instance maintains a mapping of globally declared XML element and type definition names to 
 JAXB mapped classes. The unmarshal method checks if <A HREF="../../../javax/xml/bind/JAXBContext.html" title="class in javax.xml.bind"><CODE>JAXBContext</CODE></A> has a mapping
 from the root element's XML name and/or <tt>@xsi:type</tt> 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 <tt>@xsi:type</tt>, the XML data is unmarshalled
 using that JAXB mapped class as the value of a <A HREF="../../../javax/xml/bind/JAXBElement.html" title="class in javax.xml.bind"><CODE>JAXBElement</CODE></A>.
 When the <A HREF="../../../javax/xml/bind/JAXBContext.html" title="class in javax.xml.bind"><CODE>JAXBContext</CODE></A> object does not have a mapping for the root element's name
 nor its <tt>@xsi:type</tt>, if it exists, 
 then the unmarshal operation will abort immediately by throwing a <A HREF="../../../javax/xml/bind/UnmarshalException.html" title="class in javax.xml.bind"><CODE>UnmarshalException</CODE></A>. This exception scenario can be worked around by using the unmarshal by 
 declaredType methods described in the next subsection.
 </blockquote>
 
 <p>
 <a name="unmarshalByDeclaredType"></a>
 <b>Unmarshal by Declared Type</b><br>
 <blockquote>
 The unmarshal methods with a <code>declaredType</code> parameter enable an 
 application to deserialize a root element of XML data, even when
 there is no mapping in <A HREF="../../../javax/xml/bind/JAXBContext.html" title="class in javax.xml.bind"><CODE>JAXBContext</CODE></A> of the root element's XML name.
 The unmarshaller unmarshals the root element using the application provided
 mapping specified as the <tt>declaredType</tt> parameter. 
 Note that even when the root element's element name is mapped by <A HREF="../../../javax/xml/bind/JAXBContext.html" title="class in javax.xml.bind"><CODE>JAXBContext</CODE></A>, 
 the <code>declaredType</code> parameter overrides that mapping for 
 deserializing the root element when using these unmarshal methods. 
 Additionally, when the root element of XML data has an <tt>xsi:type</tt> attribute and 
 that attribute's value references a type definition that is mapped 
 to a JAXB mapped class by <A HREF="../../../javax/xml/bind/JAXBContext.html" title="class in javax.xml.bind"><CODE>JAXBContext</CODE></A>, that the root 
 element's <tt>xsi:type</tt> attribute takes
 precedence over the unmarshal methods <tt>declaredType</tt> parameter. 
 These methods always return a <tt>JAXBElement&lt;declaredType></tt> 
 instance. The table below shows how the properties of the returned JAXBElement 
 instance are set.

 <a name="unmarshalDeclaredTypeReturn"></a>
 <p>
   <table border="2" rules="all" cellpadding="4">
   <thead>
     <tr>
       <th align="center" colspan="2">
       Unmarshal By Declared Type returned JAXBElement 
       </tr>
     <tr>
       <th>JAXBElement Property</th>
       <th>Value</th>
     </tr>
     </tr>
     <tr>
       <td>name</td>
       <td><code>xml element name</code></td>
     </tr>
   </thead>
   <tbody>
     <tr>
       <td>value</td>
       <td><code>instanceof declaredType</code></td>
     </tr>
     <tr>
       <td>declaredType</td>
       <td>unmarshal method <code>declaredType</code> parameter</td>
     </tr>
     <tr>
       <td>scope</td>
       <td><code>null</code> <i>(actual scope is unknown)</td>
     </tr>
   </tbody>
  </table>
 </blockquote>

 <p>
 The following is an example of 
 <a href="#unmarshalByDeclaredType">unmarshal by declaredType method</a>.
 <p>
 Unmarshal by declaredType from a <tt>org.w3c.dom.Node</tt>:
 <blockquote>
    <pre>
       Schema fragment for example
       &lt;xs:schema>
          &lt;xs:complexType name="FooType">...&lt;\xs:complexType>
          &lt;!-- global element declaration "PurchaseOrder" -->
          &lt;xs:element name="PurchaseOrder">
              &lt;xs:complexType>
                 &lt;xs:sequence>
                    &lt;!-- local element declaration "foo" -->
                    &lt;xs:element name="foo" type="FooType"/>
                    ...
                 &lt;/xs:sequence>
              &lt;/xs:complexType>
          &lt;/xs:element>
       &lt;/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&lt;FooType> foo = u.unmarshal( fooSubtree, FooType.class);
    </pre>
 </blockquote>
 
 <p>
 <b>Support for SAX2.0 Compliant Parsers</b><br>
 <blockquote>
 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 <A HREF="../../../javax/xml/bind/Unmarshaller.html#unmarshal(javax.xml.transform.Source)"><CODE>unmarshal(Source)</CODE></A> 
 for more detail.
 </blockquote>

 <p>
 <b>Validation and Well-Formedness</b><br>
 <blockquote>
 <p>
 A client application can enable or disable JAXP 1.3 validation
 mechanism via the <tt>setSchema(javax.xml.validation.Schema)</tt> API.  
 Sophisticated clients can specify their own validating SAX 2.0 compliant 
 parser and bypass the JAXP 1.3 validation mechanism using the 
 <A HREF="../../../javax/xml/bind/Unmarshaller.html#unmarshal(javax.xml.transform.Source)"><CODE>unmarshal(Source)</CODE></A>  API.
 
 <p>
 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 <A HREF="../../../javax/xml/bind/JAXBContext.html" title="class in javax.xml.bind"><CODE>JAXBContext</CODE></A>, 
 the default unmarshal validation handler is 
 <A HREF="../../../javax/xml/bind/helpers/DefaultValidationEventHandler.html" title="class in javax.xml.bind.helpers"><CODE>DefaultValidationEventHandler</CODE></A> 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.
 
 </blockquote>

 <p>
 <a name="supportedProps"></a>
 <b>Supported Properties</b><br>
 <blockquote>
 <p>
 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.
 </blockquote>
 
 <p>
 <a name="unmarshalEventCallback"></a>
 <b>Unmarshal Event Callbacks</b><br>
 <blockquote>
 The <A HREF="../../../javax/xml/bind/Unmarshaller.html" title="interface in javax.xml.bind"><CODE>Unmarshaller</CODE></A> 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.
 <p>
 '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:
 <blockquote>
 <pre>
   // 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);
 </pre>
 </blockquote>
 The class defined callback methods should be used when the callback method requires
 access to non-public methods and/or fields of the class. 
 <p>
 The external listener callback mechanism enables the registration of a <A HREF="../../../javax/xml/bind/Unmarshaller.Listener.html" title="class in javax.xml.bind"><CODE>Unmarshaller.Listener</CODE></A> 
 instance with an <A HREF="../../../javax/xml/bind/Unmarshaller.html#setListener(javax.xml.bind.Unmarshaller.Listener)"><CODE>setListener(Listener)</CODE></A>. 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.
 <p>
 The 'class defined' and external listener event callback methods are independent of each other,