xml/bind/Unmarshaller.java

36  * The {@code Unmarshaller} class governs the process of deserializing XML
46  *       Unmarshaller u = jc.createUnmarshaller();
58  *       Unmarshaller u = jc.createUnmarshaller();
68  *       Unmarshaller u = jc.createUnmarshaller();
80  *       Unmarshaller u = jc.createUnmarshaller();
91  *       Unmarshaller u = jc.createUnmarshaller();
136  *       Unmarshaller u = jc.createUnmarshaller();
159  *       Unmarshaller u = jc.createUnmarshaller();
173  *       Unmarshaller u = jc.createUnmarshaller();
189  * <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal root element that is declared globally</a>.
195  * <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">unmarshal by declaredType methods</a>.
212  * instance is the one that was used to create this {@code Unmarshaller}. The {@link JAXBContext}
279  * <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">unmarshal by declaredType method</a>.
300  *       Unmarshaller u = jc.createUnmarshaller();
339  * the Unmarshaller default validation event handler was made more lenient
357  * JAXB Providers on Unmarshaller.  However, some providers may support
365  * The {@link Unmarshaller} provides two styles of callback mechanisms
378  *   void beforeUnmarshal(Unmarshaller, Object parent);
382  *   void afterUnmarshal(Unmarshaller, Object parent);
389  * instance with an {@link Unmarshaller#setListener(Listener)}. The external listener receives all callback events,
407 public interface Unmarshaller {
414      * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
424      *     {@code Unmarshaller} is unable to perform the XML to Java
425      *     binding.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
437      * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
447      *     {@code Unmarshaller} is unable to perform the XML to Java
448      *     binding.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
461      * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
471      *     {@code Unmarshaller} is unable to perform the XML to Java
472      *     binding.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
484      * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
494      *     {@code Unmarshaller} is unable to perform the XML to Java
495      *     binding.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
506      * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
516      *     {@code Unmarshaller} is unable to perform the XML to Java
517      *     binding.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
528      * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
540      *     {@code Unmarshaller} is unable to perform the XML to Java
541      *     binding.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
553      * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">Unmarshal by Declared Type</a>
561      * @return <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalDeclaredTypeReturn">JAXB Element</a> representation of {@code node}
568      *     {@code Unmarshaller} is unable to perform the XML to Java
569      *     binding.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
581      * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
606      * {@code Unmarshaller}.  <i>Note:</i> specifying a substitute validating
626      *     {@code Unmarshaller} is unable to perform the XML to Java
627      *     binding.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
641      * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">Unmarshal by Declared Type</a>
644      * See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#saxParserPlugable">SAX 2.0 Parser Pluggability</a>
650      * @return Java content rooted by <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalDeclaredTypeReturn">JAXB Element</a>
657      *     {@code Unmarshaller} is unable to perform the XML to Java
658      *     binding.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
671      * Implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root Element</a>.
690      *     {@code Unmarshaller} is unable to perform the XML to Java
691      *     binding.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
708      * This method implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">unmarshal by declaredType</a>.
721      * @return   content tree rooted by <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalDeclaredTypeReturn">JAXB Element representation</a>
728      *     {@code Unmarshaller} is unable to perform the XML to Java
729      *     binding.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
741      * This method is an <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalGlobal">Unmarshal Global Root method</a>.
760      *     {@code Unmarshaller} is unable to perform the XML to Java
761      *     binding.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
778      * This method implements <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalByDeclaredType">unmarshal by declaredType</a>.
792      * @return   content tree rooted by <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalDeclaredTypeReturn">JAXB Element representation</a>
799      *     {@code Unmarshaller} is unable to perform the XML to Java
800      *     binding.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#unmarshalEx">Unmarshalling XML Data</a>
816      * should create more than one {@code Unmarshaller}.
825      * {@code Unmarshaller} should validate during unmarshal operations.
826      * By default, the {@code Unmarshaller} does not validate.
841      * @param validating true if the Unmarshaller should validate during
846      *         invoked on an Unmarshaller created from a JAXBContext referencing
854      * Indicates whether or not the {@code Unmarshaller} is configured to
863      * @return true if the Unmarshaller is configured to validate during
868      *         invoked on an Unmarshaller created from a JAXBContext referencing
886      * Calling this method with a null parameter will cause the Unmarshaller
910      * {@code Unmarshaller}.  This method can only be used to set one of
913      * a PropertyException being thrown.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#supportedProps">
931      * {@code Unmarshaller}.  This method can only be used to get one of
934      * a PropertyException being thrown.  See <a href="{@docRoot}/javax/xml/bind/Unmarshaller.html#supportedProps">
961      *         invoked on an Unmarshaller created from a JAXBContext referencing
975      * To determine if the Unmarshaller has validation enabled, simply
984      *         invoked on an Unmarshaller created from a JAXBContext referencing
1063      * Register an instance of an implementation of this class with {@link Unmarshaller} to externally listen
1075      * See <a href="Unmarshaller.html#unmarshalEventCallback">Unmarshal Event Callbacks</a> for an overview.
1121      * Register unmarshal event callback {@link Listener} with this {@link Unmarshaller}.
1124      * There is only one Listener per Unmarshaller. Setting a Listener replaces the previous set Listener.
1127      * @param listener  provides unmarshal event callbacks for this {@link Unmarshaller}
1133      * <p>Return {@link Listener} registered with this {@link Unmarshaller}.
1136      *         if no Listener is registered with this Unmarshaller.