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