0001 /*
0002 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
0003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004 *
0005 * This code is free software; you can redistribute it and/or modify it
0006 * under the terms of the GNU General Public License version 2 only, as
0007 * published by the Free Software Foundation. Sun designates this
0008 * particular file as subject to the "Classpath" exception as provided
0009 * by Sun in the LICENSE file that accompanied this code.
0010 *
0011 * This code is distributed in the hope that it will be useful, but WITHOUT
0012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0014 * version 2 for more details (a copy is included in the LICENSE file that
0015 * accompanied this code).
0016 *
0017 * You should have received a copy of the GNU General Public License version
0018 * 2 along with this work; if not, write to the Free Software Foundation,
0019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020 *
0021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022 * CA 95054 USA or visit www.sun.com if you need additional information or
0023 * have any questions.
0024 */
0025
0026 package javax.xml.bind;
0027
0028 import javax.xml.bind.annotation.adapters.XmlAdapter;
0029 import javax.xml.bind.attachment.AttachmentUnmarshaller;
0030 import javax.xml.validation.Schema;
0031 import java.io.Reader;
0032
0033 /**
0034 * The <tt>Unmarshaller</tt> class governs the process of deserializing XML
0035 * data into newly created Java content trees, optionally validating the XML
0036 * data as it is unmarshalled. It provides an overloading of unmarshal methods
0037 * for many different input kinds.
0038 *
0039 * <p>
0040 * Unmarshalling from a File:
0041 * <blockquote>
0042 * <pre>
0043 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
0044 * Unmarshaller u = jc.createUnmarshaller();
0045 * Object o = u.unmarshal( new File( "nosferatu.xml" ) );
0046 * </pre>
0047 * </blockquote>
0048 *
0049 *
0050 * <p>
0051 * Unmarshalling from an InputStream:
0052 * <blockquote>
0053 * <pre>
0054 * InputStream is = new FileInputStream( "nosferatu.xml" );
0055 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
0056 * Unmarshaller u = jc.createUnmarshaller();
0057 * Object o = u.unmarshal( is );
0058 * </pre>
0059 * </blockquote>
0060 *
0061 * <p>
0062 * Unmarshalling from a URL:
0063 * <blockquote>
0064 * <pre>
0065 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
0066 * Unmarshaller u = jc.createUnmarshaller();
0067 * URL url = new URL( "http://beaker.east/nosferatu.xml" );
0068 * Object o = u.unmarshal( url );
0069 * </pre>
0070 * </blockquote>
0071 *
0072 * <p>
0073 * Unmarshalling from a StringBuffer using a
0074 * <tt>javax.xml.transform.stream.StreamSource</tt>:
0075 * <blockquote>
0076 * <pre>
0077 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
0078 * Unmarshaller u = jc.createUnmarshaller();
0079 * StringBuffer xmlStr = new StringBuffer( "<?xml version="1.0"?>..." );
0080 * Object o = u.unmarshal( new StreamSource( new StringReader( xmlStr.toString() ) ) );
0081 * </pre>
0082 * </blockquote>
0083 *
0084 * <p>
0085 * Unmarshalling from a <tt>org.w3c.dom.Node</tt>:
0086 * <blockquote>
0087 * <pre>
0088 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
0089 * Unmarshaller u = jc.createUnmarshaller();
0090 *
0091 * DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
0092 * dbf.setNamespaceAware(true);
0093 * DocumentBuilder db = dbf.newDocumentBuilder();
0094 * Document doc = db.parse(new File( "nosferatu.xml"));
0095
0096 * Object o = u.unmarshal( doc );
0097 * </pre>
0098 * </blockquote>
0099 *
0100 * <p>
0101 * Unmarshalling from a <tt>javax.xml.transform.sax.SAXSource</tt> using a
0102 * client specified validating SAX2.0 parser:
0103 * <blockquote>
0104 * <pre>
0105 * // configure a validating SAX2.0 parser (Xerces2)
0106 * static final String JAXP_SCHEMA_LANGUAGE =
0107 * "http://java.sun.com/xml/jaxp/properties/schemaLanguage";
0108 * static final String JAXP_SCHEMA_LOCATION =
0109 * "http://java.sun.com/xml/jaxp/properties/schemaSource";
0110 * static final String W3C_XML_SCHEMA =
0111 * "http://www.w3.org/2001/XMLSchema";
0112 *
0113 * System.setProperty( "javax.xml.parsers.SAXParserFactory",
0114 * "org.apache.xerces.jaxp.SAXParserFactoryImpl" );
0115 *
0116 * SAXParserFactory spf = SAXParserFactory.newInstance();
0117 * spf.setNamespaceAware(true);
0118 * spf.setValidating(true);
0119 * SAXParser saxParser = spf.newSAXParser();
0120 *
0121 * try {
0122 * saxParser.setProperty(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA);
0123 * saxParser.setProperty(JAXP_SCHEMA_LOCATION, "http://....");
0124 * } catch (SAXNotRecognizedException x) {
0125 * // exception handling omitted
0126 * }
0127 *
0128 * XMLReader xmlReader = saxParser.getXMLReader();
0129 * SAXSource source =
0130 * new SAXSource( xmlReader, new InputSource( "http://..." ) );
0131 *
0132 * // Setup JAXB to unmarshal
0133 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
0134 * Unmarshaller u = jc.createUnmarshaller();
0135 * ValidationEventCollector vec = new ValidationEventCollector();
0136 * u.setEventHandler( vec );
0137 *
0138 * // turn off the JAXB provider's default validation mechanism to
0139 * // avoid duplicate validation
0140 * u.setValidating( false )
0141 *
0142 * // unmarshal
0143 * Object o = u.unmarshal( source );
0144 *
0145 * // check for events
0146 * if( vec.hasEvents() ) {
0147 * // iterate over events
0148 * }
0149 * </pre>
0150 * </blockquote>
0151 *
0152 * <p>
0153 * Unmarshalling from a StAX XMLStreamReader:
0154 * <blockquote>
0155 * <pre>
0156 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
0157 * Unmarshaller u = jc.createUnmarshaller();
0158 *
0159 * javax.xml.stream.XMLStreamReader xmlStreamReader =
0160 * javax.xml.stream.XMLInputFactory().newInstance().createXMLStreamReader( ... );
0161 *
0162 * Object o = u.unmarshal( xmlStreamReader );
0163 * </pre>
0164 * </blockquote>
0165 *
0166 * <p>
0167 * Unmarshalling from a StAX XMLEventReader:
0168 * <blockquote>
0169 * <pre>
0170 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
0171 * Unmarshaller u = jc.createUnmarshaller();
0172 *
0173 * javax.xml.stream.XMLEventReader xmlEventReader =
0174 * javax.xml.stream.XMLInputFactory().newInstance().createXMLEventReader( ... );
0175 *
0176 * Object o = u.unmarshal( xmlEventReader );
0177 * </pre>
0178 * </blockquote>
0179 *
0180 * <p>
0181 * <a name="unmarshalEx"></a>
0182 * <b>Unmarshalling XML Data</b><br>
0183 * <blockquote>
0184 * Unmarshalling can deserialize XML data that represents either an entire XML document
0185 * or a subtree of an XML document. Typically, it is sufficient to use the
0186 * unmarshalling methods described by
0187 * <a href="#unmarshalGlobal">Unmarshal root element that is declared globally</a>.
0188 * These unmarshal methods utilize {@link JAXBContext}'s mapping of global XML element
0189 * declarations and type definitions to JAXB mapped classes to initiate the
0190 * unmarshalling of the root element of XML data. When the {@link JAXBContext}'s
0191 * mappings are not sufficient to unmarshal the root element of XML data,
0192 * the application can assist the unmarshalling process by using the
0193 * <a href="#unmarshalByDeclaredType">unmarshal by declaredType methods</a>.
0194 * These methods are useful for unmarshalling XML data where
0195 * the root element corresponds to a local element declaration in the schema.
0196 * </blockquote>
0197 *
0198 * <blockquote>
0199 * An unmarshal method never returns null. If the unmarshal process is unable to unmarshal
0200 * the root of XML content to a JAXB mapped object, a fatal error is reported that
0201 * terminates processing by throwing JAXBException.
0202 * </blockquote>
0203 *
0204 * <p>
0205 * <a name="unmarshalGlobal"></a>
0206 * <b>Unmarshal a root element that is globally declared</b><br>
0207 * <blockquote>
0208 * The unmarshal methods that do not have an <tt>declaredType</tt> parameter use
0209 * {@link JAXBContext} to unmarshal the root element of an XML data. The {@link JAXBContext}
0210 * instance is the one that was used to create this <tt>Unmarshaller</tt>. The {@link JAXBContext}
0211 * instance maintains a mapping of globally declared XML element and type definition names to
0212 * JAXB mapped classes. The unmarshal method checks if {@link JAXBContext} has a mapping
0213 * from the root element's XML name and/or <tt>@xsi:type</tt> to a JAXB mapped class. If it does, it umarshalls the
0214 * XML data using the appropriate JAXB mapped class. Note that when the root element name is unknown and the root
0215 * element has an <tt>@xsi:type</tt>, the XML data is unmarshalled
0216 * using that JAXB mapped class as the value of a {@link JAXBElement}.
0217 * When the {@link JAXBContext} object does not have a mapping for the root element's name
0218 * nor its <tt>@xsi:type</tt>, if it exists,
0219 * then the unmarshal operation will abort immediately by throwing a {@link UnmarshalException
0220 * UnmarshalException}. This exception scenario can be worked around by using the unmarshal by
0221 * declaredType methods described in the next subsection.
0222 * </blockquote>
0223 *
0224 * <p>
0225 * <a name="unmarshalByDeclaredType"></a>
0226 * <b>Unmarshal by Declared Type</b><br>
0227 * <blockquote>
0228 * The unmarshal methods with a <code>declaredType</code> parameter enable an
0229 * application to deserialize a root element of XML data, even when
0230 * there is no mapping in {@link JAXBContext} of the root element's XML name.
0231 * The unmarshaller unmarshals the root element using the application provided
0232 * mapping specified as the <tt>declaredType</tt> parameter.
0233 * Note that even when the root element's element name is mapped by {@link JAXBContext},
0234 * the <code>declaredType</code> parameter overrides that mapping for
0235 * deserializing the root element when using these unmarshal methods.
0236 * Additionally, when the root element of XML data has an <tt>xsi:type</tt> attribute and
0237 * that attribute's value references a type definition that is mapped
0238 * to a JAXB mapped class by {@link JAXBContext}, that the root
0239 * element's <tt>xsi:type</tt> attribute takes
0240 * precedence over the unmarshal methods <tt>declaredType</tt> parameter.
0241 * These methods always return a <tt>JAXBElement<declaredType></tt>
0242 * instance. The table below shows how the properties of the returned JAXBElement
0243 * instance are set.
0244 *
0245 * <a name="unmarshalDeclaredTypeReturn"></a>
0246 * <p>
0247 * <table border="2" rules="all" cellpadding="4">
0248 * <thead>
0249 * <tr>
0250 * <th align="center" colspan="2">
0251 * Unmarshal By Declared Type returned JAXBElement
0252 * </tr>
0253 * <tr>
0254 * <th>JAXBElement Property</th>
0255 * <th>Value</th>
0256 * </tr>
0257 * </tr>
0258 * <tr>
0259 * <td>name</td>
0260 * <td><code>xml element name</code></td>
0261 * </tr>
0262 * </thead>
0263 * <tbody>
0264 * <tr>
0265 * <td>value</td>
0266 * <td><code>instanceof declaredType</code></td>
0267 * </tr>
0268 * <tr>
0269 * <td>declaredType</td>
0270 * <td>unmarshal method <code>declaredType</code> parameter</td>
0271 * </tr>
0272 * <tr>
0273 * <td>scope</td>
0274 * <td><code>null</code> <i>(actual scope is unknown)</i></td>
0275 * </tr>
0276 * </tbody>
0277 * </table>
0278 * </blockquote>
0279 *
0280 * <p>
0281 * The following is an example of
0282 * <a href="#unmarshalByDeclaredType">unmarshal by declaredType method</a>.
0283 * <p>
0284 * Unmarshal by declaredType from a <tt>org.w3c.dom.Node</tt>:
0285 * <blockquote>
0286 * <pre>
0287 * Schema fragment for example
0288 * <xs:schema>
0289 * <xs:complexType name="FooType">...<\xs:complexType>
0290 * <!-- global element declaration "PurchaseOrder" -->
0291 * <xs:element name="PurchaseOrder">
0292 * <xs:complexType>
0293 * <xs:sequence>
0294 * <!-- local element declaration "foo" -->
0295 * <xs:element name="foo" type="FooType"/>
0296 * ...
0297 * </xs:sequence>
0298 * </xs:complexType>
0299 * </xs:element>
0300 * </xs:schema>
0301 *
0302 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
0303 * Unmarshaller u = jc.createUnmarshaller();
0304 *
0305 * DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
0306 * dbf.setNamespaceAware(true);
0307 * DocumentBuilder db = dbf.newDocumentBuilder();
0308 * Document doc = db.parse(new File( "nosferatu.xml"));
0309 * Element fooSubtree = ...; // traverse DOM till reach xml element foo, constrained by a
0310 * // local element declaration in schema.
0311 *
0312 * // FooType is the JAXB mapping of the type of local element declaration foo.
0313 * JAXBElement<FooType> foo = u.unmarshal( fooSubtree, FooType.class);
0314 * </pre>
0315 * </blockquote>
0316 *
0317 * <p>
0318 * <b>Support for SAX2.0 Compliant Parsers</b><br>
0319 * <blockquote>
0320 * A client application has the ability to select the SAX2.0 compliant parser
0321 * of their choice. If a SAX parser is not selected, then the JAXB Provider's
0322 * default parser will be used. Even though the JAXB Provider's default parser
0323 * is not required to be SAX2.0 compliant, all providers are required to allow
0324 * a client application to specify their own SAX2.0 parser. Some providers may
0325 * require the client application to specify the SAX2.0 parser at schema compile
0326 * time. See {@link #unmarshal(javax.xml.transform.Source) unmarshal(Source)}
0327 * for more detail.
0328 * </blockquote>
0329 *
0330 * <p>
0331 * <b>Validation and Well-Formedness</b><br>
0332 * <blockquote>
0333 * <p>
0334 * A client application can enable or disable JAXP 1.3 validation
0335 * mechanism via the <tt>setSchema(javax.xml.validation.Schema)</tt> API.
0336 * Sophisticated clients can specify their own validating SAX 2.0 compliant
0337 * parser and bypass the JAXP 1.3 validation mechanism using the
0338 * {@link #unmarshal(javax.xml.transform.Source) unmarshal(Source)} API.
0339 *
0340 * <p>
0341 * Since unmarshalling invalid XML content is defined in JAXB 2.0,
0342 * the Unmarshaller default validation event handler was made more lenient
0343 * than in JAXB 1.0. When schema-derived code generated
0344 * by JAXB 1.0 binding compiler is registered with {@link JAXBContext},
0345 * the default unmarshal validation handler is
0346 * {@link javax.xml.bind.helpers.DefaultValidationEventHandler} and it
0347 * terminates the marshal operation after encountering either a fatal error or an error.
0348 * For a JAXB 2.0 client application, there is no explicitly defined default
0349 * validation handler and the default event handling only
0350 * terminates the marshal operation after encountering a fatal error.
0351 *
0352 * </blockquote>
0353 *
0354 * <p>
0355 * <a name="supportedProps"></a>
0356 * <b>Supported Properties</b><br>
0357 * <blockquote>
0358 * <p>
0359 * There currently are not any properties required to be supported by all
0360 * JAXB Providers on Unmarshaller. However, some providers may support
0361 * their own set of provider specific properties.
0362 * </blockquote>
0363 *
0364 * <p>
0365 * <a name="unmarshalEventCallback"></a>
0366 * <b>Unmarshal Event Callbacks</b><br>
0367 * <blockquote>
0368 * The {@link Unmarshaller} provides two styles of callback mechanisms
0369 * that allow application specific processing during key points in the
0370 * unmarshalling process. In 'class defined' event callbacks, application
0371 * specific code placed in JAXB mapped classes is triggered during
0372 * unmarshalling. 'External listeners' allow for centralized processing
0373 * of unmarshal events in one callback method rather than by type event callbacks.
0374 * <p>
0375 * 'Class defined' event callback methods allow any JAXB mapped class to specify
0376 * its own specific callback methods by defining methods with the following method signature:
0377 * <blockquote>
0378 * <pre>
0379 * // This method is called immediately after the object is created and before the unmarshalling of this
0380 * // object begins. The callback provides an opportunity to initialize JavaBean properties prior to unmarshalling.
0381 * void beforeUnmarshal(Unmarshaller, Object parent);
0382 *
0383 * //This method is called after all the properties (except IDREF) are unmarshalled for this object,
0384 * //but before this object is set to the parent object.
0385 * void afterUnmarshal(Unmarshaller, Object parent);
0386 * </pre>
0387 * </blockquote>
0388 * The class defined callback methods should be used when the callback method requires
0389 * access to non-public methods and/or fields of the class.
0390 * <p>
0391 * The external listener callback mechanism enables the registration of a {@link Listener}
0392 * instance with an {@link Unmarshaller#setListener(Listener)}. The external listener receives all callback events,
0393 * allowing for more centralized processing than per class defined callback methods. The external listener
0394 * receives events when unmarshalling proces is marshalling to a JAXB element or to JAXB mapped class.
0395 * <p>
0396 * The 'class defined' and external listener event callback methods are independent of each other,
0397 * both can be called for one event. The invocation ordering when both listener callback methods exist is
0398 * defined in {@link Listener#beforeUnmarshal(Object, Object)} and {@link Listener#afterUnmarshal(Object, Object)}.
0399 * <p>
0400 * An event callback method throwing an exception terminates the current unmarshal process.
0401 *
0402 * </blockquote>
0403 *
0404 * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
0405 * @version $Revision: 1.31 $ $Date: 2005/08/15 20:54:42 $
0406 * @see JAXBContext
0407 * @see Marshaller
0408 * @see Validator
0409 * @since JAXB1.0
0410 */
0411 public interface Unmarshaller {
0412
0413 /**
0414 * Unmarshal XML data from the specified file and return the resulting
0415 * content tree.
0416 *
0417 * <p>
0418 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
0419 *
0420 * @param f the file to unmarshal XML data from
0421 * @return the newly created root object of the java content tree
0422 *
0423 * @throws JAXBException
0424 * If any unexpected errors occur while unmarshalling
0425 * @throws UnmarshalException
0426 * If the {@link ValidationEventHandler ValidationEventHandler}
0427 * returns false from its <tt>handleEvent</tt> method or the
0428 * <tt>Unmarshaller</tt> is unable to perform the XML to Java
0429 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a>
0430 * @throws IllegalArgumentException
0431 * If the file parameter is null
0432 */
0433 public Object unmarshal(java.io.File f) throws JAXBException;
0434
0435 /**
0436 * Unmarshal XML data from the specified InputStream and return the
0437 * resulting content tree. Validation event location information may
0438 * be incomplete when using this form of the unmarshal API.
0439 *
0440 * <p>
0441 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
0442 *
0443 * @param is the InputStream to unmarshal XML data from
0444 * @return the newly created root object of the java content tree
0445 *
0446 * @throws JAXBException
0447 * If any unexpected errors occur while unmarshalling
0448 * @throws UnmarshalException
0449 * If the {@link ValidationEventHandler ValidationEventHandler}
0450 * returns false from its <tt>handleEvent</tt> method or the
0451 * <tt>Unmarshaller</tt> is unable to perform the XML to Java
0452 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a>
0453 * @throws IllegalArgumentException
0454 * If the InputStream parameter is null
0455 */
0456 public Object unmarshal(java.io.InputStream is)
0457 throws JAXBException;
0458
0459 /**
0460 * Unmarshal XML data from the specified Reader and return the
0461 * resulting content tree. Validation event location information may
0462 * be incomplete when using this form of the unmarshal API,
0463 * because a Reader does not provide the system ID.
0464 *
0465 * <p>
0466 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
0467 *
0468 * @param reader the Reader to unmarshal XML data from
0469 * @return the newly created root object of the java content tree
0470 *
0471 * @throws JAXBException
0472 * If any unexpected errors occur while unmarshalling
0473 * @throws UnmarshalException
0474 * If the {@link ValidationEventHandler ValidationEventHandler}
0475 * returns false from its <tt>handleEvent</tt> method or the
0476 * <tt>Unmarshaller</tt> is unable to perform the XML to Java
0477 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a>
0478 * @throws IllegalArgumentException
0479 * If the InputStream parameter is null
0480 * @since JAXB2.0
0481 */
0482 public Object unmarshal(Reader reader) throws JAXBException;
0483
0484 /**
0485 * Unmarshal XML data from the specified URL and return the resulting
0486 * content tree.
0487 *
0488 * <p>
0489 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
0490 *
0491 * @param url the url to unmarshal XML data from
0492 * @return the newly created root object of the java content tree
0493 *
0494 * @throws JAXBException
0495 * If any unexpected errors occur while unmarshalling
0496 * @throws UnmarshalException
0497 * If the {@link ValidationEventHandler ValidationEventHandler}
0498 * returns false from its <tt>handleEvent</tt> method or the
0499 * <tt>Unmarshaller</tt> is unable to perform the XML to Java
0500 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a>
0501 * @throws IllegalArgumentException
0502 * If the URL parameter is null
0503 */
0504 public Object unmarshal(java.net.URL url) throws JAXBException;
0505
0506 /**
0507 * Unmarshal XML data from the specified SAX InputSource and return the
0508 * resulting content tree.
0509 *
0510 * <p>
0511 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
0512 *
0513 * @param source the input source to unmarshal XML data from
0514 * @return the newly created root object of the java content tree
0515 *
0516 * @throws JAXBException
0517 * If any unexpected errors occur while unmarshalling
0518 * @throws UnmarshalException
0519 * If the {@link ValidationEventHandler ValidationEventHandler}
0520 * returns false from its <tt>handleEvent</tt> method or the
0521 * <tt>Unmarshaller</tt> is unable to perform the XML to Java
0522 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a>
0523 * @throws IllegalArgumentException
0524 * If the InputSource parameter is null
0525 */
0526 public Object unmarshal(org.xml.sax.InputSource source)
0527 throws JAXBException;
0528
0529 /**
0530 * Unmarshal global XML data from the specified DOM tree and return the resulting
0531 * content tree.
0532 *
0533 * <p>
0534 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
0535 *
0536 * @param node
0537 * the document/element to unmarshal XML data from.
0538 * The caller must support at least Document and Element.
0539 * @return the newly created root object of the java content tree
0540 *
0541 * @throws JAXBException
0542 * If any unexpected errors occur while unmarshalling
0543 * @throws UnmarshalException
0544 * If the {@link ValidationEventHandler ValidationEventHandler}
0545 * returns false from its <tt>handleEvent</tt> method or the
0546 * <tt>Unmarshaller</tt> is unable to perform the XML to Java
0547 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a>
0548 * @throws IllegalArgumentException
0549 * If the Node parameter is null
0550 * @see #unmarshal(org.w3c.dom.Node, Class)
0551 */
0552 public Object unmarshal(org.w3c.dom.Node node) throws JAXBException;
0553
0554 /**
0555 * Unmarshal XML data by JAXB mapped <tt>declaredType</tt>
0556 * and return the resulting content tree.
0557 *
0558 * <p>
0559 * Implements <a href="#unmarshalByDeclaredType">Unmarshal by Declared Type</a>
0560 *
0561 * @param node
0562 * the document/element to unmarshal XML data from.
0563 * The caller must support at least Document and Element.
0564 * @param declaredType
0565 * appropriate JAXB mapped class to hold <tt>node</tt>'s XML data.
0566 *
0567 * @return <a href="#unmarshalDeclaredTypeReturn">JAXB Element</a> representation of <tt>node</tt>
0568 *
0569 * @throws JAXBException
0570 * If any unexpected errors occur while unmarshalling
0571 * @throws UnmarshalException
0572 * If the {@link ValidationEventHandler ValidationEventHandler}
0573 * returns false from its <tt>handleEvent</tt> method or the
0574 * <tt>Unmarshaller</tt> is unable to perform the XML to Java
0575 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a>
0576 * @throws IllegalArgumentException
0577 * If any parameter is null
0578 * @since JAXB2.0
0579 */
0580 public <T> JAXBElement<T> unmarshal(org.w3c.dom.Node node,
0581 Class<T> declaredType) throws JAXBException;
0582
0583 /**
0584 * Unmarshal XML data from the specified XML Source and return the
0585 * resulting content tree.
0586 *
0587 * <p>
0588 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
0589 *
0590 * <p>
0591 * <a name="saxParserPlugable"></a>
0592 * <b>SAX 2.0 Parser Pluggability</b>
0593 * <p>
0594 * A client application can choose not to use the default parser mechanism
0595 * supplied with their JAXB provider. Any SAX 2.0 compliant parser can be
0596 * substituted for the JAXB provider's default mechanism. To do so, the
0597 * client application must properly configure a <tt>SAXSource</tt> containing
0598 * an <tt>XMLReader</tt> implemented by the SAX 2.0 parser provider. If the
0599 * <tt>XMLReader</tt> has an <tt>org.xml.sax.ErrorHandler</tt> registered
0600 * on it, it will be replaced by the JAXB Provider so that validation errors
0601 * can be reported via the <tt>ValidationEventHandler</tt> mechanism of
0602 * JAXB. If the <tt>SAXSource</tt> does not contain an <tt>XMLReader</tt>,
0603 * then the JAXB provider's default parser mechanism will be used.
0604 * <p>
0605 * This parser replacement mechanism can also be used to replace the JAXB
0606 * provider's unmarshal-time validation engine. The client application
0607 * must properly configure their SAX 2.0 compliant parser to perform
0608 * validation (as shown in the example above). Any <tt>SAXParserExceptions
0609 * </tt> encountered by the parser during the unmarshal operation will be
0610 * processed by the JAXB provider and converted into JAXB
0611 * <tt>ValidationEvent</tt> objects which will be reported back to the
0612 * client via the <tt>ValidationEventHandler</tt> registered with the
0613 * <tt>Unmarshaller</tt>. <i>Note:</i> specifying a substitute validating
0614 * SAX 2.0 parser for unmarshalling does not necessarily replace the
0615 * validation engine used by the JAXB provider for performing on-demand
0616 * validation.
0617 * <p>
0618 * The only way for a client application to specify an alternate parser
0619 * mechanism to be used during unmarshal is via the
0620 * <tt>unmarshal(SAXSource)</tt> API. All other forms of the unmarshal
0621 * method (File, URL, Node, etc) will use the JAXB provider's default
0622 * parser and validator mechanisms.
0623 *
0624 * @param source the XML Source to unmarshal XML data from (providers are
0625 * only required to support SAXSource, DOMSource, and StreamSource)
0626 * @return the newly created root object of the java content tree
0627 *
0628 * @throws JAXBException
0629 * If any unexpected errors occur while unmarshalling
0630 * @throws UnmarshalException
0631 * If the {@link ValidationEventHandler ValidationEventHandler}
0632 * returns false from its <tt>handleEvent</tt> method or the
0633 * <tt>Unmarshaller</tt> is unable to perform the XML to Java
0634 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a>
0635 * @throws IllegalArgumentException
0636 * If the Source parameter is null
0637 * @see #unmarshal(javax.xml.transform.Source, Class)
0638 */
0639 public Object unmarshal(javax.xml.transform.Source source)
0640 throws JAXBException;
0641
0642 /**
0643 * Unmarshal XML data from the specified XML Source by <tt>declaredType</tt> and return the
0644 * resulting content tree.
0645 *
0646 * <p>
0647 * Implements <a href="#unmarshalByDeclaredType">Unmarshal by Declared Type</a>
0648 *
0649 * <p>
0650 * See <a href="#saxParserPlugable">SAX 2.0 Parser Pluggability</a>
0651 *
0652 * @param source the XML Source to unmarshal XML data from (providers are
0653 * only required to support SAXSource, DOMSource, and StreamSource)
0654 * @param declaredType
0655 * appropriate JAXB mapped class to hold <tt>source</tt>'s xml root element
0656 * @return Java content rooted by <a href="#unmarshalDeclaredTypeReturn">JAXB Element</a>
0657 *
0658 * @throws JAXBException
0659 * If any unexpected errors occur while unmarshalling
0660 * @throws UnmarshalException
0661 * If the {@link ValidationEventHandler ValidationEventHandler}
0662 * returns false from its <tt>handleEvent</tt> method or the
0663 * <tt>Unmarshaller</tt> is unable to perform the XML to Java
0664 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a>
0665 * @throws IllegalArgumentException
0666 * If any parameter is null
0667 * @since JAXB2.0
0668 */
0669 public <T> JAXBElement<T> unmarshal(
0670 javax.xml.transform.Source source, Class<T> declaredType)
0671 throws JAXBException;
0672
0673 /**
0674 * Unmarshal XML data from the specified pull parser and return the
0675 * resulting content tree.
0676 *
0677 * <p>
0678 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>.
0679 *
0680 * <p>
0681 * This method assumes that the parser is on a START_DOCUMENT or
0682 * START_ELEMENT event. Unmarshalling will be done from this
0683 * start event to the corresponding end event. If this method
0684 * returns successfully, the <tt>reader</tt> will be pointing at
0685 * the token right after the end event.
0686 *
0687 * @param reader
0688 * The parser to be read.
0689 * @return
0690 * the newly created root object of the java content tree.
0691 *
0692 * @throws JAXBException
0693 * If any unexpected errors occur while unmarshalling
0694 * @throws UnmarshalException
0695 * If the {@link ValidationEventHandler ValidationEventHandler}
0696 * returns false from its <tt>handleEvent</tt> method or the
0697 * <tt>Unmarshaller</tt> is unable to perform the XML to Java
0698 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a>
0699 * @throws IllegalArgumentException
0700 * If the <tt>reader</tt> parameter is null
0701 * @throws IllegalStateException
0702 * If <tt>reader</tt> is not pointing to a START_DOCUMENT or
0703 * START_ELEMENT event.
0704 * @since JAXB2.0
0705 * @see #unmarshal(javax.xml.stream.XMLStreamReader, Class)
0706 */
0707 public Object unmarshal(javax.xml.stream.XMLStreamReader reader)
0708 throws JAXBException;
0709
0710 /**
0711 * Unmarshal root element to JAXB mapped <tt>declaredType</tt>
0712 * and return the resulting content tree.
0713 *
0714 * <p>
0715 * This method implements <a href="#unmarshalByDeclaredType">unmarshal by declaredType</a>.
0716 * <p>
0717 * This method assumes that the parser is on a START_DOCUMENT or
0718 * START_ELEMENT event. Unmarshalling will be done from this
0719 * start event to the corresponding end event. If this method
0720 * returns successfully, the <tt>reader</tt> will be pointing at
0721 * the token right after the end event.
0722 *
0723 * @param reader
0724 * The parser to be read.
0725 * @param declaredType
0726 * appropriate JAXB mapped class to hold <tt>reader</tt>'s START_ELEMENT XML data.
0727 *
0728 * @return content tree rooted by <a href="#unmarshalDeclaredTypeReturn">JAXB Element representation</a>
0729 *
0730 * @throws JAXBException
0731 * If any unexpected errors occur while unmarshalling
0732 * @throws UnmarshalException
0733 * If the {@link ValidationEventHandler ValidationEventHandler}
0734 * returns false from its <tt>handleEvent</tt> method or the
0735 * <tt>Unmarshaller</tt> is unable to perform the XML to Java
0736 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a>
0737 * @throws IllegalArgumentException
0738 * If any parameter is null
0739 * @since JAXB2.0
0740 */
0741 public <T> JAXBElement<T> unmarshal(
0742 javax.xml.stream.XMLStreamReader reader,
0743 Class<T> declaredType) throws JAXBException;
0744
0745 /**
0746 * Unmarshal XML data from the specified pull parser and return the
0747 * resulting content tree.
0748 *
0749 * <p>
0750 * This method is an <a href="#unmarshalGlobal">Unmarshal Global Root method</a>.
0751 *
0752 * <p>
0753 * This method assumes that the parser is on a START_DOCUMENT or
0754 * START_ELEMENT event. Unmarshalling will be done from this
0755 * start event to the corresponding end event. If this method
0756 * returns successfully, the <tt>reader</tt> will be pointing at
0757 * the token right after the end event.
0758 *
0759 * @param reader
0760 * The parser to be read.
0761 * @return
0762 * the newly created root object of the java content tree.
0763 *
0764 * @throws JAXBException
0765 * If any unexpected errors occur while unmarshalling
0766 * @throws UnmarshalException
0767 * If the {@link ValidationEventHandler ValidationEventHandler}
0768 * returns false from its <tt>handleEvent</tt> method or the
0769 * <tt>Unmarshaller</tt> is unable to perform the XML to Java
0770 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a>
0771 * @throws IllegalArgumentException
0772 * If the <tt>reader</tt> parameter is null
0773 * @throws IllegalStateException
0774 * If <tt>reader</tt> is not pointing to a START_DOCUMENT or
0775 * START_ELEMENT event.
0776 * @since JAXB2.0
0777 * @see #unmarshal(javax.xml.stream.XMLEventReader, Class)
0778 */
0779 public Object unmarshal(javax.xml.stream.XMLEventReader reader)
0780 throws JAXBException;
0781
0782 /**
0783 * Unmarshal root element to JAXB mapped <tt>declaredType</tt>
0784 * and return the resulting content tree.
0785 *
0786 * <p>
0787 * This method implements <a href="#unmarshalByDeclaredType">unmarshal by declaredType</a>.
0788 *
0789 * <p>
0790 * This method assumes that the parser is on a START_DOCUMENT or
0791 * START_ELEMENT event. Unmarshalling will be done from this
0792 * start event to the corresponding end event. If this method
0793 * returns successfully, the <tt>reader</tt> will be pointing at
0794 * the token right after the end event.
0795 *
0796 * @param reader
0797 * The parser to be read.
0798 * @param declaredType
0799 * appropriate JAXB mapped class to hold <tt>reader</tt>'s START_ELEMENT XML data.
0800 *
0801 * @return content tree rooted by <a href="#unmarshalDeclaredTypeReturn">JAXB Element representation</a>
0802 *
0803 * @throws JAXBException
0804 * If any unexpected errors occur while unmarshalling
0805 * @throws UnmarshalException
0806 * If the {@link ValidationEventHandler ValidationEventHandler}
0807 * returns false from its <tt>handleEvent</tt> method or the
0808 * <tt>Unmarshaller</tt> is unable to perform the XML to Java
0809 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a>
0810 * @throws IllegalArgumentException
0811 * If any parameter is null
0812 * @since JAXB2.0
0813 */
0814 public <T> JAXBElement<T> unmarshal(
0815 javax.xml.stream.XMLEventReader reader,
0816 Class<T> declaredType) throws JAXBException;
0817
0818 /**
0819 * Get an unmarshaller handler object that can be used as a component in
0820 * an XML pipeline.
0821 *
0822 * <p>
0823 * The JAXB Provider can return the same handler object for multiple
0824 * invocations of this method. In other words, this method does not
0825 * necessarily create a new instance of <tt>UnmarshallerHandler</tt>. If the
0826 * application needs to use more than one <tt>UnmarshallerHandler</tt>, it
0827 * should create more than one <tt>Unmarshaller</tt>.
0828 *
0829 * @return the unmarshaller handler object
0830 * @see UnmarshallerHandler
0831 */
0832 public UnmarshallerHandler getUnmarshallerHandler();
0833
0834 /**
0835 * Specifies whether or not the default validation mechanism of the
0836 * <tt>Unmarshaller</tt> should validate during unmarshal operations.
0837 * By default, the <tt>Unmarshaller</tt> does not validate.
0838 * <p>
0839 * This method may only be invoked before or after calling one of the
0840 * unmarshal methods.
0841 * <p>
0842 * This method only controls the JAXB Provider's default unmarshal-time
0843 * validation mechanism - it has no impact on clients that specify their
0844 * own validating SAX 2.0 compliant parser. Clients that specify their
0845 * own unmarshal-time validation mechanism may wish to turn off the JAXB
0846 * Provider's default validation mechanism via this API to avoid "double
0847 * validation".
0848 * <p>
0849 * This method is deprecated as of JAXB 2.0 - please use the new
0850 * {@link #setSchema(javax.xml.validation.Schema)} API.
0851 *
0852 * @param validating true if the Unmarshaller should validate during
0853 * unmarshal, false otherwise
0854 * @throws JAXBException if an error occurred while enabling or disabling
0855 * validation at unmarshal time
0856 * @throws UnsupportedOperationException could be thrown if this method is
0857 * invoked on an Unmarshaller created from a JAXBContext referencing
0858 * JAXB 2.0 mapped classes
0859 * @deprecated since JAXB2.0, please see {@link #setSchema(javax.xml.validation.Schema)}
0860 */
0861 public void setValidating(boolean validating) throws JAXBException;
0862
0863 /**
0864 * Indicates whether or not the <tt>Unmarshaller</tt> is configured to
0865 * validate during unmarshal operations.
0866 * <p>
0867 * This API returns the state of the JAXB Provider's default unmarshal-time
0868 * validation mechanism.
0869 * <p>
0870 * This method is deprecated as of JAXB 2.0 - please use the new
0871 * {@link #getSchema()} API.
0872 *
0873 * @return true if the Unmarshaller is configured to validate during
0874 * unmarshal operations, false otherwise
0875 * @throws JAXBException if an error occurs while retrieving the validating
0876 * flag
0877 * @throws UnsupportedOperationException could be thrown if this method is
0878 * invoked on an Unmarshaller created from a JAXBContext referencing
0879 * JAXB 2.0 mapped classes
0880 * @deprecated since JAXB2.0, please see {@link #getSchema()}
0881 */
0882 public boolean isValidating() throws JAXBException;
0883
0884 /**
0885 * Allow an application to register a <tt>ValidationEventHandler</tt>.
0886 * <p>
0887 * The <tt>ValidationEventHandler</tt> will be called by the JAXB Provider
0888 * if any validation errors are encountered during calls to any of the
0889 * unmarshal methods. If the client application does not register a
0890 * <tt>ValidationEventHandler</tt> before invoking the unmarshal methods,
0891 * then <tt>ValidationEvents</tt> will be handled by the default event
0892 * handler which will terminate the unmarshal operation after the first
0893 * error or fatal error is encountered.
0894 * <p>
0895 * Calling this method with a null parameter will cause the Unmarshaller
0896 * to revert back to the default event handler.
0897 *
0898 * @param handler the validation event handler
0899 * @throws JAXBException if an error was encountered while setting the
0900 * event handler
0901 */
0902 public void setEventHandler(ValidationEventHandler handler)
0903 throws JAXBException;
0904
0905 /**
0906 * Return the current event handler or the default event handler if one
0907 * hasn't been set.
0908 *
0909 * @return the current ValidationEventHandler or the default event handler
0910 * if it hasn't been set
0911 * @throws JAXBException if an error was encountered while getting the
0912 * current event handler
0913 */
0914 public ValidationEventHandler getEventHandler()
0915 throws JAXBException;
0916
0917 /**
0918 * Set the particular property in the underlying implementation of
0919 * <tt>Unmarshaller</tt>. This method can only be used to set one of
0920 * the standard JAXB defined properties above or a provider specific
0921 * property. Attempting to set an undefined property will result in
0922 * a PropertyException being thrown. See <a href="#supportedProps">
0923 * Supported Properties</a>.
0924 *
0925 * @param name the name of the property to be set. This value can either
0926 * be specified using one of the constant fields or a user
0927 * supplied string.
0928 * @param value the value of the property to be set
0929 *
0930 * @throws PropertyException when there is an error processing the given
0931 * property or value
0932 * @throws IllegalArgumentException
0933 * If the name parameter is null
0934 */
0935 public void setProperty(String name, Object value)
0936 throws PropertyException;
0937
0938 /**
0939 * Get the particular property in the underlying implementation of
0940 * <tt>Unmarshaller</tt>. This method can only be used to get one of
0941 * the standard JAXB defined properties above or a provider specific
0942 * property. Attempting to get an undefined property will result in
0943 * a PropertyException being thrown. See <a href="#supportedProps">
0944 * Supported Properties</a>.
0945 *
0946 * @param name the name of the property to retrieve
0947 * @return the value of the requested property
0948 *
0949 * @throws PropertyException
0950 * when there is an error retrieving the given property or value
0951 * property name
0952 * @throws IllegalArgumentException
0953 * If the name parameter is null
0954 */
0955 public Object getProperty(String name) throws PropertyException;
0956
0957 /**
0958 * Specify the JAXP 1.3 {@link javax.xml.validation.Schema Schema}
0959 * object that should be used to validate subsequent unmarshal operations
0960 * against. Passing null into this method will disable validation.
0961 * <p>
0962 * This method replaces the deprecated {@link #setValidating(boolean) setValidating(boolean)}
0963 * API.
0964 *
0965 * <p>
0966 * Initially this property is set to <tt>null</tt>.
0967 *
0968 * @param schema Schema object to validate unmarshal operations against or null to disable validation
0969 * @throws UnsupportedOperationException could be thrown if this method is
0970 * invoked on an Unmarshaller created from a JAXBContext referencing
0971 * JAXB 1.0 mapped classes
0972 * @since JAXB2.0
0973 */
0974 public void setSchema(javax.xml.validation.Schema schema);
0975
0976 /**
0977 * Get the JAXP 1.3 {@link javax.xml.validation.Schema Schema} object
0978 * being used to perform unmarshal-time validation. If there is no
0979 * Schema set on the unmarshaller, then this method will return null
0980 * indicating that unmarshal-time validation will not be performed.
0981 * <p>
0982 * This method provides replacement functionality for the deprecated
0983 * {@link #isValidating()} API as well as access to the Schema object.
0984 * To determine if the Unmarshaller has validation enabled, simply
0985 * test the return type for null:
0986 * <p>
0987 * <code>
0988 * boolean isValidating = u.getSchema()!=null;
0989 * </code>
0990 *
0991 * @return the Schema object being used to perform unmarshal-time
0992 * validation or null if not present
0993 * @throws UnsupportedOperationException could be thrown if this method is
0994 * invoked on an Unmarshaller created from a JAXBContext referencing
0995 * JAXB 1.0 mapped classes
0996 * @since JAXB2.0
0997 */
0998 public javax.xml.validation.Schema getSchema();
0999
1000 /**
1001 * Associates a configured instance of {@link XmlAdapter} with this unmarshaller.
1002 *
1003 * <p>
1004 * This is a convenience method that invokes <code>setAdapter(adapter.getClass(),adapter);</code>.
1005 *
1006 * @see #setAdapter(Class,XmlAdapter)
1007 * @throws IllegalArgumentException
1008 * if the adapter parameter is null.
1009 * @throws UnsupportedOperationException
1010 * if invoked agains a JAXB 1.0 implementation.
1011 * @since JAXB2.0
1012 */
1013 public void setAdapter(XmlAdapter adapter);
1014
1015 /**
1016 * Associates a configured instance of {@link XmlAdapter} with this unmarshaller.
1017 *
1018 * <p>
1019 * Every unmarshaller internally maintains a
1020 * {@link java.util.Map}<{@link Class},{@link XmlAdapter}>,
1021 * which it uses for unmarshalling classes whose fields/methods are annotated
1022 * with {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}.
1023 *
1024 * <p>
1025 * This method allows applications to use a configured instance of {@link XmlAdapter}.
1026 * When an instance of an adapter is not given, an unmarshaller will create
1027 * one by invoking its default constructor.
1028 *
1029 * @param type
1030 * The type of the adapter. The specified instance will be used when
1031 * {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter#value()}
1032 * refers to this type.
1033 * @param adapter
1034 * The instance of the adapter to be used. If null, it will un-register
1035 * the current adapter set for this type.
1036 * @throws IllegalArgumentException
1037 * if the type parameter is null.
1038 * @throws UnsupportedOperationException
1039 * if invoked agains a JAXB 1.0 implementation.
1040 * @since JAXB2.0
1041 */
1042 public <A extends XmlAdapter> void setAdapter(Class<A> type,
1043 A adapter);
1044
1045 /**
1046 * Gets the adapter associated with the specified type.
1047 *
1048 * This is the reverse operation of the {@link #setAdapter} method.
1049 *
1050 * @throws IllegalArgumentException
1051 * if the type parameter is null.
1052 * @throws UnsupportedOperationException
1053 * if invoked agains a JAXB 1.0 implementation.
1054 * @since JAXB2.0
1055 */
1056 public <A extends XmlAdapter> A getAdapter(Class<A> type);
1057
1058 /**
1059 * <p>Associate a context that resolves cid's, content-id URIs, to
1060 * binary data passed as attachments.</p>
1061 * <p/>
1062 * <p>Unmarshal time validation, enabled via {@link #setSchema(Schema)},
1063 * must be supported even when unmarshaller is performing XOP processing.
1064 * </p>
1065 *
1066 * @throws IllegalStateException if attempt to concurrently call this
1067 * method during a unmarshal operation.
1068 */
1069 void setAttachmentUnmarshaller(AttachmentUnmarshaller au);
1070
1071 AttachmentUnmarshaller getAttachmentUnmarshaller();
1072
1073 /**
1074 * <p/>
1075 * Register an instance of an implementation of this class with {@link Unmarshaller} to externally listen
1076 * for unmarshal events.
1077 * <p/>
1078 * <p/>
1079 * This class enables pre and post processing of an instance of a JAXB mapped class
1080 * as XML data is unmarshalled into it. The event callbacks are called when unmarshalling
1081 * XML content into a JAXBElement instance or a JAXB mapped class that represents a complex type definition.
1082 * The event callbacks are not called when unmarshalling to an instance of a
1083 * Java datatype that represents a simple type definition.
1084 * <p/>
1085 * <p/>
1086 * External listener is one of two different mechanisms for defining unmarshal event callbacks.
1087 * See <a href="Unmarshaller.html#unmarshalEventCallback">Unmarshal Event Callbacks</a> for an overview.
1088 * <p/>
1089 * (@link #setListener(Listener)}
1090 * (@link #getListener()}
1091 *
1092 * @since JAXB2.0
1093 */
1094 public static abstract class Listener {
1095 /**
1096 * <p/>
1097 * Callback method invoked before unmarshalling into <tt>target</tt>.
1098 * <p/>
1099 * <p/>
1100 * This method is invoked immediately after <tt>target</tt> was created and
1101 * before the unmarshalling of this object begins. Note that
1102 * if the class of <tt>target</tt> defines its own <tt>beforeUnmarshal</tt> method,
1103 * the class specific callback method is invoked before this method is invoked.
1104 *
1105 * @param target non-null instance of JAXB mapped class prior to unmarshalling into it.
1106 * @param parent instance of JAXB mapped class that will eventually reference <tt>target</tt>.
1107 * <tt>null</tt> when <tt>target</tt> is root element.
1108 */
1109 public void beforeUnmarshal(Object target, Object parent) {
1110 }
1111
1112 /**
1113 * <p/>
1114 * Callback method invoked after unmarshalling XML data into <tt>target</tt>.
1115 * <p/>
1116 * <p/>
1117 * This method is invoked after all the properties (except IDREF) are unmarshalled into <tt>target</tt>,
1118 * but before <tt>target</tt> is set into its <tt>parent</tt> object.
1119 * Note that if the class of <tt>target</tt> defines its own <tt>afterUnmarshal</tt> method,
1120 * the class specific callback method is invoked before this method is invoked.
1121 *
1122 * @param target non-null instance of JAXB mapped class prior to unmarshalling into it.
1123 * @param parent instance of JAXB mapped class that will reference <tt>target</tt>.
1124 * <tt>null</tt> when <tt>target</tt> is root element.
1125 */
1126 public void afterUnmarshal(Object target, Object parent) {
1127 }
1128 }
1129
1130 /**
1131 * <p>
1132 * Register unmarshal event callback {@link Listener} with this {@link Unmarshaller}.
1133 *
1134 * <p>
1135 * There is only one Listener per Unmarshaller. Setting a Listener replaces the previous set Listener.
1136 * One can unregister current Listener by setting listener to <tt>null</tt>.
1137 *
1138 * @param listener provides unmarshal event callbacks for this {@link Unmarshaller}
1139 * @since JAXB2.0
1140 */
1141 public void setListener(Listener listener);
1142
1143 /**
1144 * <p>Return {@link Listener} registered with this {@link Unmarshaller}.
1145 *
1146 * @return registered {@link Listener} or <code>null</code> if no Listener is registered with this Unmarshaller.
1147 * @since JAXB2.0
1148 */
1149 public Listener getListener();
1150 }
|