Java > Open Source Codes > javax > xml > bind > Unmarshaller


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

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags