View Javadoc
1   /*
2    * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.xml.bind;
27  
28  import javax.xml.bind.annotation.adapters.XmlAdapter;
29  import javax.xml.bind.attachment.AttachmentUnmarshaller;
30  import javax.xml.validation.Schema;
31  import java.io.Reader;
32  
33  /**
34   * The <tt>Unmarshaller</tt> class governs the process of deserializing XML
35   * data into newly created Java content trees, optionally validating the XML
36   * data as it is unmarshalled.  It provides an overloading of unmarshal methods
37   * for many different input kinds.
38   *
39   * <p>
40   * Unmarshalling from a File:
41   * <blockquote>
42   *    <pre>
43   *       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
44   *       Unmarshaller u = jc.createUnmarshaller();
45   *       Object o = u.unmarshal( new File( "nosferatu.xml" ) );
46   *    </pre>
47   * </blockquote>
48   *
49   *
50   * <p>
51   * Unmarshalling from an InputStream:
52   * <blockquote>
53   *    <pre>
54   *       InputStream is = new FileInputStream( "nosferatu.xml" );
55   *       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
56   *       Unmarshaller u = jc.createUnmarshaller();
57   *       Object o = u.unmarshal( is );
58   *    </pre>
59   * </blockquote>
60   *
61   * <p>
62   * Unmarshalling from a URL:
63   * <blockquote>
64   *    <pre>
65   *       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
66   *       Unmarshaller u = jc.createUnmarshaller();
67   *       URL url = new URL( "http://beaker.east/nosferatu.xml" );
68   *       Object o = u.unmarshal( url );
69   *    </pre>
70   * </blockquote>
71   *
72   * <p>
73   * Unmarshalling from a StringBuffer using a
74   * <tt>javax.xml.transform.stream.StreamSource</tt>:
75   * <blockquote>
76   *    <pre>
77   *       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
78   *       Unmarshaller u = jc.createUnmarshaller();
79   *       StringBuffer xmlStr = new StringBuffer( "&lt;?xml version=&quot;1.0&quot;?&gt;..." );
80   *       Object o = u.unmarshal( new StreamSource( new StringReader( xmlStr.toString() ) ) );
81   *    </pre>
82   * </blockquote>
83   *
84   * <p>
85   * Unmarshalling from a <tt>org.w3c.dom.Node</tt>:
86   * <blockquote>
87   *    <pre>
88   *       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
89   *       Unmarshaller u = jc.createUnmarshaller();
90   *
91   *       DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
92   *       dbf.setNamespaceAware(true);
93   *       DocumentBuilder db = dbf.newDocumentBuilder();
94   *       Document doc = db.parse(new File( "nosferatu.xml"));
95  
96   *       Object o = u.unmarshal( doc );
97   *    </pre>
98   * </blockquote>
99   *
100  * <p>
101  * Unmarshalling from a <tt>javax.xml.transform.sax.SAXSource</tt> using a
102  * client specified validating SAX2.0 parser:
103  * <blockquote>
104  *    <pre>
105  *       // configure a validating SAX2.0 parser (Xerces2)
106  *       static final String JAXP_SCHEMA_LANGUAGE =
107  *           "http://java.sun.com/xml/jaxp/properties/schemaLanguage";
108  *       static final String JAXP_SCHEMA_LOCATION =
109  *           "http://java.sun.com/xml/jaxp/properties/schemaSource";
110  *       static final String W3C_XML_SCHEMA =
111  *           "http://www.w3.org/2001/XMLSchema";
112  *
113  *       System.setProperty( "javax.xml.parsers.SAXParserFactory",
114  *                           "org.apache.xerces.jaxp.SAXParserFactoryImpl" );
115  *
116  *       SAXParserFactory spf = SAXParserFactory.newInstance();
117  *       spf.setNamespaceAware(true);
118  *       spf.setValidating(true);
119  *       SAXParser saxParser = spf.newSAXParser();
120  *
121  *       try {
122  *           saxParser.setProperty(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA);
123  *           saxParser.setProperty(JAXP_SCHEMA_LOCATION, "http://....");
124  *       } catch (SAXNotRecognizedException x) {
125  *           // exception handling omitted
126  *       }
127  *
128  *       XMLReader xmlReader = saxParser.getXMLReader();
129  *       SAXSource source =
130  *           new SAXSource( xmlReader, new InputSource( "http://..." ) );
131  *
132  *       // Setup JAXB to unmarshal
133  *       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
134  *       Unmarshaller u = jc.createUnmarshaller();
135  *       ValidationEventCollector vec = new ValidationEventCollector();
136  *       u.setEventHandler( vec );
137  *
138  *       // turn off the JAXB provider's default validation mechanism to
139  *       // avoid duplicate validation
140  *       u.setValidating( false )
141  *
142  *       // unmarshal
143  *       Object o = u.unmarshal( source );
144  *
145  *       // check for events
146  *       if( vec.hasEvents() ) {
147  *          // iterate over events
148  *       }
149  *    </pre>
150  * </blockquote>
151  *
152  * <p>
153  * Unmarshalling from a StAX XMLStreamReader:
154  * <blockquote>
155  *    <pre>
156  *       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
157  *       Unmarshaller u = jc.createUnmarshaller();
158  *
159  *       javax.xml.stream.XMLStreamReader xmlStreamReader =
160  *           javax.xml.stream.XMLInputFactory().newInstance().createXMLStreamReader( ... );
161  *
162  *       Object o = u.unmarshal( xmlStreamReader );
163  *    </pre>
164  * </blockquote>
165  *
166  * <p>
167  * Unmarshalling from a StAX XMLEventReader:
168  * <blockquote>
169  *    <pre>
170  *       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
171  *       Unmarshaller u = jc.createUnmarshaller();
172  *
173  *       javax.xml.stream.XMLEventReader xmlEventReader =
174  *           javax.xml.stream.XMLInputFactory().newInstance().createXMLEventReader( ... );
175  *
176  *       Object o = u.unmarshal( xmlEventReader );
177  *    </pre>
178  * </blockquote>
179  *
180  * <p>
181  * <a name="unmarshalEx"></a>
182  * <b>Unmarshalling XML Data</b><br>
183  * <blockquote>
184  * Unmarshalling can deserialize XML data that represents either an entire XML document
185  * or a subtree of an XML document. Typically, it is sufficient to use the
186  * unmarshalling methods described by
187  * <a href="#unmarshalGlobal">Unmarshal root element that is declared globally</a>.
188  * These unmarshal methods utilize {@link JAXBContext}'s mapping of global XML element
189  * declarations and type definitions to JAXB mapped classes to initiate the
190  * unmarshalling of the root element of  XML data.  When the {@link JAXBContext}'s
191  * mappings are not sufficient to unmarshal the root element of XML data,
192  * the application can assist the unmarshalling process by using the
193  * <a href="#unmarshalByDeclaredType">unmarshal by declaredType methods</a>.
194  * These methods are useful for unmarshalling XML data where
195  * the root element corresponds to a local element declaration in the schema.
196  * </blockquote>
197  *
198  * <blockquote>
199  * An unmarshal method never returns null. If the unmarshal process is unable to unmarshal
200  * the root of XML content to a JAXB mapped object, a fatal error is reported that
201  * terminates processing by throwing JAXBException.
202  * </blockquote>
203  *
204  * <p>
205  * <a name="unmarshalGlobal"></a>
206  * <b>Unmarshal a root element that is globally declared</b><br>
207  * <blockquote>
208  * The unmarshal methods that do not have an <tt>declaredType</tt> parameter use
209  * {@link JAXBContext} to unmarshal the root element of an XML data. The {@link JAXBContext}
210  * instance is the one that was used to create this <tt>Unmarshaller</tt>. The {@link JAXBContext}
211  * instance maintains a mapping of globally declared XML element and type definition names to
212  * JAXB mapped classes. The unmarshal method checks if {@link JAXBContext} has a mapping
213  * from the root element's XML name and/or <tt>@xsi:type</tt> to a JAXB mapped class.  If it does, it umarshalls the
214  * XML data using the appropriate JAXB mapped class. Note that when the root element name is unknown and the root
215  * element has an <tt>@xsi:type</tt>, the XML data is unmarshalled
216  * using that JAXB mapped class as the value of a {@link JAXBElement}.
217  * When the {@link JAXBContext} object does not have a mapping for the root element's name
218  * nor its <tt>@xsi:type</tt>, if it exists,
219  * then the unmarshal operation will abort immediately by throwing a {@link UnmarshalException
220  * UnmarshalException}. This exception scenario can be worked around by using the unmarshal by
221  * declaredType methods described in the next subsection.
222  * </blockquote>
223  *
224  * <p>
225  * <a name="unmarshalByDeclaredType"></a>
226  * <b>Unmarshal by Declared Type</b><br>
227  * <blockquote>
228  * The unmarshal methods with a <code>declaredType</code> parameter enable an
229  * application to deserialize a root element of XML data, even when
230  * there is no mapping in {@link JAXBContext} of the root element's XML name.
231  * The unmarshaller unmarshals the root element using the application provided
232  * mapping specified as the <tt>declaredType</tt> parameter.
233  * Note that even when the root element's element name is mapped by {@link JAXBContext},
234  * the <code>declaredType</code> parameter overrides that mapping for
235  * deserializing the root element when using these unmarshal methods.
236  * Additionally, when the root element of XML data has an <tt>xsi:type</tt> attribute and
237  * that attribute's value references a type definition that is mapped
238  * to a JAXB mapped class by {@link JAXBContext}, that the root
239  * element's <tt>xsi:type</tt> attribute takes
240  * precedence over the unmarshal methods <tt>declaredType</tt> parameter.
241  * These methods always return a <tt>JAXBElement&lt;declaredType></tt>
242  * instance. The table below shows how the properties of the returned JAXBElement
243  * instance are set.
244  *
245  * <a name="unmarshalDeclaredTypeReturn"></a>
246  * <p>
247  *   <table border="2" rules="all" cellpadding="4">
248  *   <thead>
249  *     <tr>
250  *       <th align="center" colspan="2">
251  *       Unmarshal By Declared Type returned JAXBElement
252  *       </tr>
253  *     <tr>
254  *       <th>JAXBElement Property</th>
255  *       <th>Value</th>
256  *     </tr>
257  *     <tr>
258  *       <td>name</td>
259  *       <td><code>xml element name</code></td>
260  *     </tr>
261  *   </thead>
262  *   <tbody>
263  *     <tr>
264  *       <td>value</td>
265  *       <td><code>instanceof declaredType</code></td>
266  *     </tr>
267  *     <tr>
268  *       <td>declaredType</td>
269  *       <td>unmarshal method <code>declaredType</code> parameter</td>
270  *     </tr>
271  *     <tr>
272  *       <td>scope</td>
273  *       <td><code>null</code> <i>(actual scope is unknown)</i></td>
274  *     </tr>
275  *   </tbody>
276  *  </table>
277  * </blockquote>
278  *
279  * <p>
280  * The following is an example of
281  * <a href="#unmarshalByDeclaredType">unmarshal by declaredType method</a>.
282  * <p>
283  * Unmarshal by declaredType from a <tt>org.w3c.dom.Node</tt>:
284  * <blockquote>
285  *    <pre>
286  *       Schema fragment for example
287  *       &lt;xs:schema>
288  *          &lt;xs:complexType name="FooType">...&lt;\xs:complexType>
289  *          &lt;!-- global element declaration "PurchaseOrder" -->
290  *          &lt;xs:element name="PurchaseOrder">
291  *              &lt;xs:complexType>
292  *                 &lt;xs:sequence>
293  *                    &lt;!-- local element declaration "foo" -->
294  *                    &lt;xs:element name="foo" type="FooType"/>
295  *                    ...
296  *                 &lt;/xs:sequence>
297  *              &lt;/xs:complexType>
298  *          &lt;/xs:element>
299  *       &lt;/xs:schema>
300  *
301  *       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
302  *       Unmarshaller u = jc.createUnmarshaller();
303  *
304  *       DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
305  *       dbf.setNamespaceAware(true);
306  *       DocumentBuilder db = dbf.newDocumentBuilder();
307  *       Document doc = db.parse(new File( "nosferatu.xml"));
308  *       Element  fooSubtree = ...; // traverse DOM till reach xml element foo, constrained by a
309  *                                  // local element declaration in schema.
310  *
311  *       // FooType is the JAXB mapping of the type of local element declaration foo.
312  *       JAXBElement&lt;FooType> foo = u.unmarshal( fooSubtree, FooType.class);
313  *    </pre>
314  * </blockquote>
315  *
316  * <p>
317  * <b>Support for SAX2.0 Compliant Parsers</b><br>
318  * <blockquote>
319  * A client application has the ability to select the SAX2.0 compliant parser
320  * of their choice.  If a SAX parser is not selected, then the JAXB Provider's
321  * default parser will be used.  Even though the JAXB Provider's default parser
322  * is not required to be SAX2.0 compliant, all providers are required to allow
323  * a client application to specify their own SAX2.0 parser.  Some providers may
324  * require the client application to specify the SAX2.0 parser at schema compile
325  * time. See {@link #unmarshal(javax.xml.transform.Source) unmarshal(Source)}
326  * for more detail.
327  * </blockquote>
328  *
329  * <p>
330  * <b>Validation and Well-Formedness</b><br>
331  * <blockquote>
332  * <p>
333  * A client application can enable or disable JAXP 1.3 validation
334  * mechanism via the <tt>setSchema(javax.xml.validation.Schema)</tt> API.
335  * Sophisticated clients can specify their own validating SAX 2.0 compliant
336  * parser and bypass the JAXP 1.3 validation mechanism using the
337  * {@link #unmarshal(javax.xml.transform.Source) unmarshal(Source)}  API.
338  *
339  * <p>
340  * Since unmarshalling invalid XML content is defined in JAXB 2.0,
341  * the Unmarshaller default validation event handler was made more lenient
342  * than in JAXB 1.0.  When schema-derived code generated
343  * by JAXB 1.0 binding compiler is registered with {@link JAXBContext},
344  * the default unmarshal validation handler is
345  * {@link javax.xml.bind.helpers.DefaultValidationEventHandler} and it
346  * terminates the marshal  operation after encountering either a fatal error or an error.
347  * For a JAXB 2.0 client application, there is no explicitly defined default
348  * validation handler and the default event handling only
349  * terminates the unmarshal operation after encountering a fatal error.
350  *
351  * </blockquote>
352  *
353  * <p>
354  * <a name="supportedProps"></a>
355  * <b>Supported Properties</b><br>
356  * <blockquote>
357  * <p>
358  * There currently are not any properties required to be supported by all
359  * JAXB Providers on Unmarshaller.  However, some providers may support
360  * their own set of provider specific properties.
361  * </blockquote>
362  *
363  * <p>
364  * <a name="unmarshalEventCallback"></a>
365  * <b>Unmarshal Event Callbacks</b><br>
366  * <blockquote>
367  * The {@link Unmarshaller} provides two styles of callback mechanisms
368  * that allow application specific processing during key points in the
369  * unmarshalling process.  In 'class defined' event callbacks, application
370  * specific code placed in JAXB mapped classes is triggered during
371  * unmarshalling.  'External listeners' allow for centralized processing
372  * of unmarshal events in one callback method rather than by type event callbacks.
373  * <p>
374  * 'Class defined' event callback methods allow any JAXB mapped class to specify
375  * its own specific callback methods by defining methods with the following method signature:
376  * <blockquote>
377  * <pre>
378  *   // This method is called immediately after the object is created and before the unmarshalling of this
379  *   // object begins. The callback provides an opportunity to initialize JavaBean properties prior to unmarshalling.
380  *   void beforeUnmarshal(Unmarshaller, Object parent);
381  *
382  *   //This method is called after all the properties (except IDREF) are unmarshalled for this object,
383  *   //but before this object is set to the parent object.
384  *   void afterUnmarshal(Unmarshaller, Object parent);
385  * </pre>
386  * </blockquote>
387  * The class defined callback methods should be used when the callback method requires
388  * access to non-public methods and/or fields of the class.
389  * <p>
390  * The external listener callback mechanism enables the registration of a {@link Listener}
391  * instance with an {@link Unmarshaller#setListener(Listener)}. The external listener receives all callback events,
392  * allowing for more centralized processing than per class defined callback methods.  The external listener
393  * receives events when unmarshalling proces is marshalling to a JAXB element or to JAXB mapped class.
394  * <p>
395  * The 'class defined' and external listener event callback methods are independent of each other,
396  * both can be called for one event.  The invocation ordering when both listener callback methods exist is
397  * defined in {@link Listener#beforeUnmarshal(Object, Object)} and {@link Listener#afterUnmarshal(Object, Object)}.
398 * <p>
399  * An event callback method throwing an exception terminates the current unmarshal process.
400  *
401  * </blockquote>
402  *
403  * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
404  * @see JAXBContext
405  * @see Marshaller
406  * @see Validator
407  * @since JAXB1.0
408  */
409 public interface Unmarshaller {
410 
411     /**
412      * Unmarshal XML data from the specified file and return the resulting
413      * content tree.
414      *
415      * <p>
416      * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
417      *
418      * @param f the file to unmarshal XML data from
419      * @return the newly created root object of the java content tree
420      *
421      * @throws JAXBException
422      *     If any unexpected errors occur while unmarshalling
423      * @throws UnmarshalException
424      *     If the {@link ValidationEventHandler ValidationEventHandler}
425      *     returns false from its <tt>handleEvent</tt> method or the
426      *     <tt>Unmarshaller</tt> is unable to perform the XML to Java
427      *     binding.  See <a href="#unmarshalEx">Unmarshalling XML Data</a>
428      * @throws IllegalArgumentException
429      *      If the file parameter is null
430      */
431     public Object unmarshal( java.io.File f ) throws JAXBException;
432 
433     /**
434      * Unmarshal XML data from the specified InputStream and return the
435      * resulting content tree.  Validation event location information may
436      * be incomplete when using this form of the unmarshal API.
437      *
438      * <p>
439      * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
440      *
441      * @param is the InputStream to unmarshal XML data from
442      * @return the newly created root object of the java content tree
443      *
444      * @throws JAXBException
445      *     If any unexpected errors occur while unmarshalling
446      * @throws UnmarshalException
447      *     If the {@link ValidationEventHandler ValidationEventHandler}
448      *     returns false from its <tt>handleEvent</tt> method or the
449      *     <tt>Unmarshaller</tt> is unable to perform the XML to Java
450      *     binding.  See <a href="#unmarshalEx">Unmarshalling XML Data</a>
451      * @throws IllegalArgumentException
452      *      If the InputStream parameter is null
453      */
454     public Object unmarshal( java.io.InputStream is ) throws JAXBException;
455 
456     /**
457      * Unmarshal XML data from the specified Reader and return the
458      * resulting content tree.  Validation event location information may
459      * be incomplete when using this form of the unmarshal API,
460      * because a Reader does not provide the system ID.
461      *
462      * <p>
463      * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
464      *
465      * @param reader the Reader to unmarshal XML data from
466      * @return the newly created root object of the java content tree
467      *
468      * @throws JAXBException
469      *     If any unexpected errors occur while unmarshalling
470      * @throws UnmarshalException
471      *     If the {@link ValidationEventHandler ValidationEventHandler}
472      *     returns false from its <tt>handleEvent</tt> method or the
473      *     <tt>Unmarshaller</tt> is unable to perform the XML to Java
474      *     binding.  See <a href="#unmarshalEx">Unmarshalling XML Data</a>
475      * @throws IllegalArgumentException
476      *      If the InputStream parameter is null
477      * @since JAXB2.0
478      */
479     public Object unmarshal( Reader reader ) throws JAXBException;
480 
481     /**
482      * Unmarshal XML data from the specified URL and return the resulting
483      * content tree.
484      *
485      * <p>
486      * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
487      *
488      * @param url the url to unmarshal XML data from
489      * @return the newly created root object of the java content tree
490      *
491      * @throws JAXBException
492      *     If any unexpected errors occur while unmarshalling
493      * @throws UnmarshalException
494      *     If the {@link ValidationEventHandler ValidationEventHandler}
495      *     returns false from its <tt>handleEvent</tt> method or the
496      *     <tt>Unmarshaller</tt> is unable to perform the XML to Java
497      *     binding.  See <a href="#unmarshalEx">Unmarshalling XML Data</a>
498      * @throws IllegalArgumentException
499      *      If the URL parameter is null
500      */
501     public Object unmarshal( java.net.URL url ) throws JAXBException;
502 
503     /**
504      * Unmarshal XML data from the specified SAX InputSource and return the
505      * resulting content tree.
506      *
507      * <p>
508      * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
509      *
510      * @param source the input source to unmarshal XML data from
511      * @return the newly created root object of the java content tree
512      *
513      * @throws JAXBException
514      *     If any unexpected errors occur while unmarshalling
515      * @throws UnmarshalException
516      *     If the {@link ValidationEventHandler ValidationEventHandler}
517      *     returns false from its <tt>handleEvent</tt> method or the
518      *     <tt>Unmarshaller</tt> is unable to perform the XML to Java
519      *     binding.  See <a href="#unmarshalEx">Unmarshalling XML Data</a>
520      * @throws IllegalArgumentException
521      *      If the InputSource parameter is null
522      */
523     public Object unmarshal( org.xml.sax.InputSource source ) throws JAXBException;
524 
525     /**
526      * Unmarshal global XML data from the specified DOM tree and return the resulting
527      * content tree.
528      *
529      * <p>
530      * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
531      *
532      * @param node
533      *      the document/element to unmarshal XML data from.
534      *      The caller must support at least Document and Element.
535      * @return the newly created root object of the java content tree
536      *
537      * @throws JAXBException
538      *     If any unexpected errors occur while unmarshalling
539      * @throws UnmarshalException
540      *     If the {@link ValidationEventHandler ValidationEventHandler}
541      *     returns false from its <tt>handleEvent</tt> method or the
542      *     <tt>Unmarshaller</tt> is unable to perform the XML to Java
543      *     binding.  See <a href="#unmarshalEx">Unmarshalling XML Data</a>
544      * @throws IllegalArgumentException
545      *      If the Node parameter is null
546      * @see #unmarshal(org.w3c.dom.Node, Class)
547      */
548     public Object unmarshal( org.w3c.dom.Node node ) throws JAXBException;
549 
550     /**
551      * Unmarshal XML data by JAXB mapped <tt>declaredType</tt>
552      * and return the resulting content tree.
553      *
554      * <p>
555      * Implements <a href="#unmarshalByDeclaredType">Unmarshal by Declared Type</a>
556      *
557      * @param node
558      *      the document/element to unmarshal XML data from.
559      *      The caller must support at least Document and Element.
560      * @param declaredType
561      *      appropriate JAXB mapped class to hold <tt>node</tt>'s XML data.
562      *
563      * @return <a href="#unmarshalDeclaredTypeReturn">JAXB Element</a> representation of <tt>node</tt>
564      *
565      * @throws JAXBException
566      *     If any unexpected errors occur while unmarshalling
567      * @throws UnmarshalException
568      *     If the {@link ValidationEventHandler ValidationEventHandler}
569      *     returns false from its <tt>handleEvent</tt> method or the
570      *     <tt>Unmarshaller</tt> is unable to perform the XML to Java
571      *     binding.  See <a href="#unmarshalEx">Unmarshalling XML Data</a>
572      * @throws IllegalArgumentException
573      *      If any parameter is null
574      * @since JAXB2.0
575      */
576     public <T> JAXBElement<T> unmarshal( org.w3c.dom.Node node, Class<T> declaredType ) throws JAXBException;
577 
578     /**
579      * Unmarshal XML data from the specified XML Source and return the
580      * resulting content tree.
581      *
582      * <p>
583      * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
584      *
585      * <p>
586      * <a name="saxParserPlugable"></a>
587      * <b>SAX 2.0 Parser Pluggability</b>
588      * <p>
589      * A client application can choose not to use the default parser mechanism
590      * supplied with their JAXB provider.  Any SAX 2.0 compliant parser can be
591      * substituted for the JAXB provider's default mechanism.  To do so, the
592      * client application must properly configure a <tt>SAXSource</tt> containing
593      * an <tt>XMLReader</tt> implemented by the SAX 2.0 parser provider.  If the
594      * <tt>XMLReader</tt> has an <tt>org.xml.sax.ErrorHandler</tt> registered
595      * on it, it will be replaced by the JAXB Provider so that validation errors
596      * can be reported via the <tt>ValidationEventHandler</tt> mechanism of
597      * JAXB.  If the <tt>SAXSource</tt> does not contain an <tt>XMLReader</tt>,
598      * then the JAXB provider's default parser mechanism will be used.
599      * <p>
600      * This parser replacement mechanism can also be used to replace the JAXB
601      * provider's unmarshal-time validation engine.  The client application
602      * must properly configure their SAX 2.0 compliant parser to perform
603      * validation (as shown in the example above).  Any <tt>SAXParserExceptions
604      * </tt> encountered by the parser during the unmarshal operation will be
605      * processed by the JAXB provider and converted into JAXB
606      * <tt>ValidationEvent</tt> objects which will be reported back to the
607      * client via the <tt>ValidationEventHandler</tt> registered with the
608      * <tt>Unmarshaller</tt>.  <i>Note:</i> specifying a substitute validating
609      * SAX 2.0 parser for unmarshalling does not necessarily replace the
610      * validation engine used by the JAXB provider for performing on-demand
611      * validation.
612      * <p>
613      * The only way for a client application to specify an alternate parser
614      * mechanism to be used during unmarshal is via the
615      * <tt>unmarshal(SAXSource)</tt> API.  All other forms of the unmarshal
616      * method (File, URL, Node, etc) will use the JAXB provider's default
617      * parser and validator mechanisms.
618      *
619      * @param source the XML Source to unmarshal XML data from (providers are
620      *        only required to support SAXSource, DOMSource, and StreamSource)
621      * @return the newly created root object of the java content tree
622      *
623      * @throws JAXBException
624      *     If any unexpected errors occur while unmarshalling
625      * @throws UnmarshalException
626      *     If the {@link ValidationEventHandler ValidationEventHandler}
627      *     returns false from its <tt>handleEvent</tt> method or the
628      *     <tt>Unmarshaller</tt> is unable to perform the XML to Java
629      *     binding.  See <a href="#unmarshalEx">Unmarshalling XML Data</a>
630      * @throws IllegalArgumentException
631      *      If the Source parameter is null
632      * @see #unmarshal(javax.xml.transform.Source, Class)
633      */
634     public Object unmarshal( javax.xml.transform.Source source )
635         throws JAXBException;
636 
637 
638     /**
639      * Unmarshal XML data from the specified XML Source by <tt>declaredType</tt> and return the
640      * resulting content tree.
641      *
642      * <p>
643      * Implements <a href="#unmarshalByDeclaredType">Unmarshal by Declared Type</a>
644      *
645      * <p>
646      * See <a href="#saxParserPlugable">SAX 2.0 Parser Pluggability</a>
647      *
648      * @param source the XML Source to unmarshal XML data from (providers are
649      *        only required to support SAXSource, DOMSource, and StreamSource)
650      * @param declaredType
651      *      appropriate JAXB mapped class to hold <tt>source</tt>'s xml root element
652      * @return Java content rooted by <a href="#unmarshalDeclaredTypeReturn">JAXB Element</a>
653      *
654      * @throws JAXBException
655      *     If any unexpected errors occur while unmarshalling
656      * @throws UnmarshalException
657      *     If the {@link ValidationEventHandler ValidationEventHandler}
658      *     returns false from its <tt>handleEvent</tt> method or the
659      *     <tt>Unmarshaller</tt> is unable to perform the XML to Java
660      *     binding.  See <a href="#unmarshalEx">Unmarshalling XML Data</a>
661      * @throws IllegalArgumentException
662      *      If any parameter is null
663      * @since JAXB2.0
664      */
665     public <T> JAXBElement<T> unmarshal( javax.xml.transform.Source source, Class<T> declaredType )
666         throws JAXBException;
667 
668     /**
669      * Unmarshal XML data from the specified pull parser and return the
670      * resulting content tree.
671      *
672      * <p>
673      * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
674      *
675      * <p>
676      * This method assumes that the parser is on a START_DOCUMENT or
677      * START_ELEMENT event.  Unmarshalling will be done from this
678      * start event to the corresponding end event.  If this method
679      * returns successfully, the <tt>reader</tt> will be pointing at
680      * the token right after the end event.
681      *
682      * @param reader
683      *      The parser to be read.
684      * @return
685      *      the newly created root object of the java content tree.
686      *
687      * @throws JAXBException
688      *     If any unexpected errors occur while unmarshalling
689      * @throws UnmarshalException
690      *     If the {@link ValidationEventHandler ValidationEventHandler}
691      *     returns false from its <tt>handleEvent</tt> method or the
692      *     <tt>Unmarshaller</tt> is unable to perform the XML to Java
693      *     binding.  See <a href="#unmarshalEx">Unmarshalling XML Data</a>
694      * @throws IllegalArgumentException
695      *      If the <tt>reader</tt> parameter is null
696      * @throws IllegalStateException
697      *      If <tt>reader</tt> is not pointing to a START_DOCUMENT or
698      *      START_ELEMENT  event.
699      * @since JAXB2.0
700      * @see #unmarshal(javax.xml.stream.XMLStreamReader, Class)
701      */
702     public Object unmarshal( javax.xml.stream.XMLStreamReader reader )
703         throws JAXBException;
704 
705     /**
706      * Unmarshal root element to JAXB mapped <tt>declaredType</tt>
707      * and return the resulting content tree.
708      *
709      * <p>
710      * This method implements <a href="#unmarshalByDeclaredType">unmarshal by declaredType</a>.
711      * <p>
712      * This method assumes that the parser is on a START_DOCUMENT or
713      * START_ELEMENT event. Unmarshalling will be done from this
714      * start event to the corresponding end event.  If this method
715      * returns successfully, the <tt>reader</tt> will be pointing at
716      * the token right after the end event.
717      *
718      * @param reader
719      *      The parser to be read.
720      * @param declaredType
721      *      appropriate JAXB mapped class to hold <tt>reader</tt>'s START_ELEMENT XML data.
722      *
723      * @return   content tree rooted by <a href="#unmarshalDeclaredTypeReturn">JAXB Element representation</a>
724      *
725      * @throws JAXBException
726      *     If any unexpected errors occur while unmarshalling
727      * @throws UnmarshalException
728      *     If the {@link ValidationEventHandler ValidationEventHandler}
729      *     returns false from its <tt>handleEvent</tt> method or the
730      *     <tt>Unmarshaller</tt> is unable to perform the XML to Java
731      *     binding.  See <a href="#unmarshalEx">Unmarshalling XML Data</a>
732      * @throws IllegalArgumentException
733      *      If any parameter is null
734      * @since JAXB2.0
735      */
736     public <T> JAXBElement<T> unmarshal( javax.xml.stream.XMLStreamReader reader, Class<T> declaredType ) throws JAXBException;
737 
738     /**
739      * Unmarshal XML data from the specified pull parser and return the
740      * resulting content tree.
741      *
742      * <p>
743      * This method is an <a href="#unmarshalGlobal">Unmarshal Global Root method</a>.
744      *
745      * <p>
746      * This method assumes that the parser is on a START_DOCUMENT or
747      * START_ELEMENT event.  Unmarshalling will be done from this
748      * start event to the corresponding end event.  If this method
749      * returns successfully, the <tt>reader</tt> will be pointing at
750      * the token right after the end event.
751      *
752      * @param reader
753      *      The parser to be read.
754      * @return
755      *      the newly created root object of the java content tree.
756      *
757      * @throws JAXBException
758      *     If any unexpected errors occur while unmarshalling
759      * @throws UnmarshalException
760      *     If the {@link ValidationEventHandler ValidationEventHandler}
761      *     returns false from its <tt>handleEvent</tt> method or the
762      *     <tt>Unmarshaller</tt> is unable to perform the XML to Java
763      *     binding.  See <a href="#unmarshalEx">Unmarshalling XML Data</a>
764      * @throws IllegalArgumentException
765      *      If the <tt>reader</tt> parameter is null
766      * @throws IllegalStateException
767      *      If <tt>reader</tt> is not pointing to a START_DOCUMENT or
768      *      START_ELEMENT event.
769      * @since JAXB2.0
770      * @see #unmarshal(javax.xml.stream.XMLEventReader, Class)
771      */
772     public Object unmarshal( javax.xml.stream.XMLEventReader reader )
773         throws JAXBException;
774 
775     /**
776      * Unmarshal root element to JAXB mapped <tt>declaredType</tt>
777      * and return the resulting content tree.
778      *
779      * <p>
780      * This method implements <a href="#unmarshalByDeclaredType">unmarshal by declaredType</a>.
781      *
782      * <p>
783      * This method assumes that the parser is on a START_DOCUMENT or
784      * START_ELEMENT event. Unmarshalling will be done from this
785      * start event to the corresponding end event.  If this method
786      * returns successfully, the <tt>reader</tt> will be pointing at
787      * the token right after the end event.
788      *
789      * @param reader
790      *      The parser to be read.
791      * @param declaredType
792      *      appropriate JAXB mapped class to hold <tt>reader</tt>'s START_ELEMENT XML data.
793      *
794      * @return   content tree rooted by <a href="#unmarshalDeclaredTypeReturn">JAXB Element representation</a>
795      *
796      * @throws JAXBException
797      *     If any unexpected errors occur while unmarshalling
798      * @throws UnmarshalException
799      *     If the {@link ValidationEventHandler ValidationEventHandler}
800      *     returns false from its <tt>handleEvent</tt> method or the
801      *     <tt>Unmarshaller</tt> is unable to perform the XML to Java
802      *     binding.  See <a href="#unmarshalEx">Unmarshalling XML Data</a>
803      * @throws IllegalArgumentException
804      *      If any parameter is null
805      * @since JAXB2.0
806      */
807     public <T> JAXBElement<T> unmarshal( javax.xml.stream.XMLEventReader reader, Class<T> declaredType ) throws JAXBException;
808 
809     /**
810      * Get an unmarshaller handler object that can be used as a component in
811      * an XML pipeline.
812      *
813      * <p>
814      * The JAXB Provider can return the same handler object for multiple
815      * invocations of this method. In other words, this method does not
816      * necessarily create a new instance of <tt>UnmarshallerHandler</tt>. If the
817      * application needs to use more than one <tt>UnmarshallerHandler</tt>, it
818      * should create more than one <tt>Unmarshaller</tt>.
819      *
820      * @return the unmarshaller handler object
821      * @see UnmarshallerHandler
822      */
823     public UnmarshallerHandler getUnmarshallerHandler();
824 
825     /**
826      * Specifies whether or not the default validation mechanism of the
827      * <tt>Unmarshaller</tt> should validate during unmarshal operations.
828      * By default, the <tt>Unmarshaller</tt> does not validate.
829      * <p>
830      * This method may only be invoked before or after calling one of the
831      * unmarshal methods.
832      * <p>
833      * This method only controls the JAXB Provider's default unmarshal-time
834      * validation mechanism - it has no impact on clients that specify their
835      * own validating SAX 2.0 compliant parser.  Clients that specify their
836      * own unmarshal-time validation mechanism may wish to turn off the JAXB
837      * Provider's default validation mechanism via this API to avoid "double
838      * validation".
839      * <p>
840      * This method is deprecated as of JAXB 2.0 - please use the new
841      * {@link #setSchema(javax.xml.validation.Schema)} API.
842      *
843      * @param validating true if the Unmarshaller should validate during
844      *        unmarshal, false otherwise
845      * @throws JAXBException if an error occurred while enabling or disabling
846      *         validation at unmarshal time
847      * @throws UnsupportedOperationException could be thrown if this method is
848      *         invoked on an Unmarshaller created from a JAXBContext referencing
849      *         JAXB 2.0 mapped classes
850      * @deprecated since JAXB2.0, please see {@link #setSchema(javax.xml.validation.Schema)}
851      */
852     public void setValidating( boolean validating )
853         throws JAXBException;
854 
855     /**
856      * Indicates whether or not the <tt>Unmarshaller</tt> is configured to
857      * validate during unmarshal operations.
858      * <p>
859      * This API returns the state of the JAXB Provider's default unmarshal-time
860      * validation mechanism.
861      * <p>
862      * This method is deprecated as of JAXB 2.0 - please use the new
863      * {@link #getSchema()} API.
864      *
865      * @return true if the Unmarshaller is configured to validate during
866      *         unmarshal operations, false otherwise
867      * @throws JAXBException if an error occurs while retrieving the validating
868      *         flag
869      * @throws UnsupportedOperationException could be thrown if this method is
870      *         invoked on an Unmarshaller created from a JAXBContext referencing
871      *         JAXB 2.0 mapped classes
872      * @deprecated since JAXB2.0, please see {@link #getSchema()}
873      */
874     public boolean isValidating()
875         throws JAXBException;
876 
877     /**
878      * Allow an application to register a <tt>ValidationEventHandler</tt>.
879      * <p>
880      * The <tt>ValidationEventHandler</tt> will be called by the JAXB Provider
881      * if any validation errors are encountered during calls to any of the
882      * unmarshal methods.  If the client application does not register a
883      * <tt>ValidationEventHandler</tt> before invoking the unmarshal methods,
884      * then <tt>ValidationEvents</tt> will be handled by the default event
885      * handler which will terminate the unmarshal operation after the first
886      * error or fatal error is encountered.
887      * <p>
888      * Calling this method with a null parameter will cause the Unmarshaller
889      * to revert back to the default event handler.
890      *
891      * @param handler the validation event handler
892      * @throws JAXBException if an error was encountered while setting the
893      *         event handler
894      */
895     public void setEventHandler( ValidationEventHandler handler )
896         throws JAXBException;
897 
898     /**
899      * Return the current event handler or the default event handler if one
900      * hasn't been set.
901      *
902      * @return the current ValidationEventHandler or the default event handler
903      *         if it hasn't been set
904      * @throws JAXBException if an error was encountered while getting the
905      *         current event handler
906      */
907     public ValidationEventHandler getEventHandler()
908         throws JAXBException;
909 
910     /**
911      * Set the particular property in the underlying implementation of
912      * <tt>Unmarshaller</tt>.  This method can only be used to set one of
913      * the standard JAXB defined properties above or a provider specific
914      * property.  Attempting to set an undefined property will result in
915      * a PropertyException being thrown.  See <a href="#supportedProps">
916      * Supported Properties</a>.
917      *
918      * @param name the name of the property to be set. This value can either
919      *              be specified using one of the constant fields or a user
920      *              supplied string.
921      * @param value the value of the property to be set
922      *
923      * @throws PropertyException when there is an error processing the given
924      *                            property or value
925      * @throws IllegalArgumentException
926      *      If the name parameter is null
927      */
928     public void setProperty( String name, Object value )
929         throws PropertyException;
930 
931     /**
932      * Get the particular property in the underlying implementation of
933      * <tt>Unmarshaller</tt>.  This method can only be used to get one of
934      * the standard JAXB defined properties above or a provider specific
935      * property.  Attempting to get an undefined property will result in
936      * a PropertyException being thrown.  See <a href="#supportedProps">
937      * Supported Properties</a>.
938      *
939      * @param name the name of the property to retrieve
940      * @return the value of the requested property
941      *
942      * @throws PropertyException
943      *      when there is an error retrieving the given property or value
944      *      property name
945      * @throws IllegalArgumentException
946      *      If the name parameter is null
947      */
948     public Object getProperty( String name ) throws PropertyException;
949 
950     /**
951      * Specify the JAXP 1.3 {@link javax.xml.validation.Schema Schema}
952      * object that should be used to validate subsequent unmarshal operations
953      * against.  Passing null into this method will disable validation.
954      * <p>
955      * This method replaces the deprecated {@link #setValidating(boolean) setValidating(boolean)}
956      * API.
957      *
958      * <p>
959      * Initially this property is set to <tt>null</tt>.
960      *
961      * @param schema Schema object to validate unmarshal operations against or null to disable validation
962      * @throws UnsupportedOperationException could be thrown if this method is
963      *         invoked on an Unmarshaller created from a JAXBContext referencing
964      *         JAXB 1.0 mapped classes
965      * @since JAXB2.0
966      */
967     public void setSchema( javax.xml.validation.Schema schema );
968 
969     /**
970      * Get the JAXP 1.3 {@link javax.xml.validation.Schema Schema} object
971      * being used to perform unmarshal-time validation.  If there is no
972      * Schema set on the unmarshaller, then this method will return null
973      * indicating that unmarshal-time validation will not be performed.
974      * <p>
975      * This method provides replacement functionality for the deprecated
976      * {@link #isValidating()} API as well as access to the Schema object.
977      * To determine if the Unmarshaller has validation enabled, simply
978      * test the return type for null:
979      * <p>
980      * <code>
981      *   boolean isValidating = u.getSchema()!=null;
982      * </code>
983      *
984      * @return the Schema object being used to perform unmarshal-time
985      *      validation or null if not present
986      * @throws UnsupportedOperationException could be thrown if this method is
987      *         invoked on an Unmarshaller created from a JAXBContext referencing
988      *         JAXB 1.0 mapped classes
989      * @since JAXB2.0
990      */
991     public javax.xml.validation.Schema getSchema();
992 
993     /**
994      * Associates a configured instance of {@link XmlAdapter} with this unmarshaller.
995      *
996      * <p>
997      * This is a convenience method that invokes <code>setAdapter(adapter.getClass(),adapter);</code>.
998      *
999      * @see #setAdapter(Class,XmlAdapter)
1000      * @throws IllegalArgumentException
1001      *      if the adapter parameter is null.
1002      * @throws UnsupportedOperationException
1003      *      if invoked agains a JAXB 1.0 implementation.
1004      * @since JAXB2.0
1005      */
1006     public void setAdapter( XmlAdapter adapter );
1007 
1008     /**
1009      * Associates a configured instance of {@link XmlAdapter} with this unmarshaller.
1010      *
1011      * <p>
1012      * Every unmarshaller internally maintains a
1013      * {@link java.util.Map}&lt;{@link Class},{@link XmlAdapter}>,
1014      * which it uses for unmarshalling classes whose fields/methods are annotated
1015      * with {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}.
1016      *
1017      * <p>
1018      * This method allows applications to use a configured instance of {@link XmlAdapter}.
1019      * When an instance of an adapter is not given, an unmarshaller will create
1020      * one by invoking its default constructor.
1021      *
1022      * @param type
1023      *      The type of the adapter. The specified instance will be used when
1024      *      {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter#value()}
1025      *      refers to this type.
1026      * @param adapter
1027      *      The instance of the adapter to be used. If null, it will un-register
1028      *      the current adapter set for this type.
1029      * @throws IllegalArgumentException
1030      *      if the type parameter is null.
1031      * @throws UnsupportedOperationException
1032      *      if invoked agains a JAXB 1.0 implementation.
1033      * @since JAXB2.0
1034      */
1035     public <A extends XmlAdapter> void setAdapter( Class<A> type, A adapter );
1036 
1037     /**
1038      * Gets the adapter associated with the specified type.
1039      *
1040      * This is the reverse operation of the {@link #setAdapter} method.
1041      *
1042      * @throws IllegalArgumentException
1043      *      if the type parameter is null.
1044      * @throws UnsupportedOperationException
1045      *      if invoked agains a JAXB 1.0 implementation.
1046      * @since JAXB2.0
1047      */
1048     public <A extends XmlAdapter> A getAdapter( Class<A> type );
1049 
1050     /**
1051      * <p>Associate a context that resolves cid's, content-id URIs, to
1052      * binary data passed as attachments.</p>
1053      * <p/>
1054      * <p>Unmarshal time validation, enabled via {@link #setSchema(Schema)},
1055      * must be supported even when unmarshaller is performing XOP processing.
1056      * </p>
1057      *
1058      * @throws IllegalStateException if attempt to concurrently call this
1059      *                               method during a unmarshal operation.
1060      */
1061     void setAttachmentUnmarshaller(AttachmentUnmarshaller au);
1062 
1063     AttachmentUnmarshaller getAttachmentUnmarshaller();
1064 
1065     /**
1066      * <p/>
1067      * Register an instance of an implementation of this class with {@link Unmarshaller} to externally listen
1068      * for unmarshal events.
1069      * <p/>
1070      * <p/>
1071      * This class enables pre and post processing of an instance of a JAXB mapped class
1072      * as XML data is unmarshalled into it. The event callbacks are called when unmarshalling
1073      * XML content into a JAXBElement instance or a JAXB mapped class that represents a complex type definition.
1074      * The event callbacks are not called when unmarshalling to an instance of a
1075      * Java datatype that represents a simple type definition.
1076      * <p/>
1077      * <p/>
1078      * External listener is one of two different mechanisms for defining unmarshal event callbacks.
1079      * See <a href="Unmarshaller.html#unmarshalEventCallback">Unmarshal Event Callbacks</a> for an overview.
1080      * <p/>
1081      * (@link #setListener(Listener)}
1082      * (@link #getListener()}
1083      *
1084      * @since JAXB2.0
1085      */
1086     public static abstract class Listener {
1087         /**
1088          * <p/>
1089          * Callback method invoked before unmarshalling into <tt>target</tt>.
1090          * <p/>
1091          * <p/>
1092          * This method is invoked immediately after <tt>target</tt> was created and
1093          * before the unmarshalling of this object begins. Note that
1094          * if the class of <tt>target</tt> defines its own <tt>beforeUnmarshal</tt> method,
1095          * the class specific callback method is invoked before this method is invoked.
1096          *
1097          * @param target non-null instance of JAXB mapped class prior to unmarshalling into it.
1098          * @param parent instance of JAXB mapped class that will eventually reference <tt>target</tt>.
1099          *               <tt>null</tt> when <tt>target</tt> is root element.
1100          */
1101         public void beforeUnmarshal(Object target, Object parent) {
1102         }
1103 
1104         /**
1105          * <p/>
1106          * Callback method invoked after unmarshalling XML data into <tt>target</tt>.
1107          * <p/>
1108          * <p/>
1109          * This method is invoked after all the properties (except IDREF) are unmarshalled into <tt>target</tt>,
1110          * but before <tt>target</tt> is set into its <tt>parent</tt> object.
1111          * Note that if the class of <tt>target</tt> defines its own <tt>afterUnmarshal</tt> method,
1112          * the class specific callback method is invoked before this method is invoked.
1113          *
1114          * @param target non-null instance of JAXB mapped class prior to unmarshalling into it.
1115          * @param parent instance of JAXB mapped class that will reference <tt>target</tt>.
1116          *               <tt>null</tt> when <tt>target</tt> is root element.
1117          */
1118         public void afterUnmarshal(Object target, Object parent) {
1119         }
1120     }
1121 
1122     /**
1123      * <p>
1124      * Register unmarshal event callback {@link Listener} with this {@link Unmarshaller}.
1125      *
1126      * <p>
1127      * There is only one Listener per Unmarshaller. Setting a Listener replaces the previous set Listener.
1128      * One can unregister current Listener by setting listener to <tt>null</tt>.
1129      *
1130      * @param listener  provides unmarshal event callbacks for this {@link Unmarshaller}
1131      * @since JAXB2.0
1132      */
1133     public void     setListener(Listener listener);
1134 
1135     /**
1136      * <p>Return {@link Listener} registered with this {@link Unmarshaller}.
1137      *
1138      * @return registered {@link Listener} or <code>null</code> if no Listener is registered with this Unmarshaller.
1139      * @since JAXB2.0
1140      */
1141     public Listener getListener();
1142 }