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