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="#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="#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 summary="" border="2" rules="all" cellpadding="4"> 249 * <thead> 250 * <tr> 251 * <th align="center" colspan="2"> 252 * Unmarshal By Declared Type returned JAXBElement 253 * </tr> 254 * <tr> 255 * <th>JAXBElement Property</th> 256 * <th>Value</th> 257 * </tr> 258 * <tr> 259 * <td>name</td> 260 * <td>{@code xml element name}</td> 261 * </tr> 262 * </thead> 263 * <tbody> 264 * <tr> 265 * <td>value</td> 266 * <td>{@code instanceof declaredType}</td> 267 * </tr> 268 * <tr> 269 * <td>declaredType</td> 270 * <td>unmarshal method {@code declaredType} parameter</td> 271 * </tr> 272 * <tr> 273 * <td>scope</td> 274 * <td>{@code null} <i>(actual scope is unknown)</i></td> 275 * </tr> 276 * </tbody> 277 * </table> 278 * </blockquote> 279 * 280 * <p> 281 * The following is an example of 282 * <a href="#unmarshalByDeclaredType">unmarshal by declaredType method</a>. 283 * <p> 284 * Unmarshal by declaredType from a {@code org.w3c.dom.Node}: 285 * <blockquote> 286 * <pre>{@code 287 * Schema fragment for example 288 * <xs:schema> 289 * <xs:complexType name="FooType">...<\xs:complexType> 290 * <!-- global element declaration "PurchaseOrder" --> 291 * <xs:element name="PurchaseOrder"> 292 * <xs:complexType> 293 * <xs:sequence> 294 * <!-- local element declaration "foo" --> 295 * <xs:element name="foo" type="FooType"/> 296 * ... 297 * </xs:sequence> 298 * </xs:complexType> 299 * </xs:element> 300 * </xs:schema> 301 * 302 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 303 * Unmarshaller u = jc.createUnmarshaller(); 304 * 305 * DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); 306 * dbf.setNamespaceAware(true); 307 * DocumentBuilder db = dbf.newDocumentBuilder(); 308 * Document doc = db.parse(new File( "nosferatu.xml")); 309 * Element fooSubtree = ...; // traverse DOM till reach xml element foo, constrained by a 310 * // local element declaration in schema. 311 * 312 * // FooType is the JAXB mapping of the type of local element declaration foo. 313 * JAXBElement<FooType> foo = u.unmarshal( fooSubtree, FooType.class); 314 * }</pre> 315 * </blockquote> 316 * 317 * <p> 318 * <b>Support for SAX2.0 Compliant Parsers</b><br> 319 * <blockquote> 320 * A client application has the ability to select the SAX2.0 compliant parser 321 * of their choice. If a SAX parser is not selected, then the JAXB Provider's 322 * default parser will be used. Even though the JAXB Provider's default parser 323 * is not required to be SAX2.0 compliant, all providers are required to allow 324 * a client application to specify their own SAX2.0 parser. Some providers may 325 * require the client application to specify the SAX2.0 parser at schema compile 326 * time. See {@link #unmarshal(javax.xml.transform.Source) unmarshal(Source)} 327 * for more detail. 328 * </blockquote> 329 * 330 * <p> 331 * <b>Validation and Well-Formedness</b><br> 332 * <blockquote> 333 * <p> 334 * A client application can enable or disable JAXP 1.3 validation 335 * mechanism via the {@code setSchema(javax.xml.validation.Schema)} API. 336 * Sophisticated clients can specify their own validating SAX 2.0 compliant 337 * parser and bypass the JAXP 1.3 validation mechanism using the 338 * {@link #unmarshal(javax.xml.transform.Source) unmarshal(Source)} API. 339 * 340 * <p> 341 * Since unmarshalling invalid XML content is defined in JAXB 2.0, 342 * the Unmarshaller default validation event handler was made more lenient 343 * than in JAXB 1.0. When schema-derived code generated 344 * by JAXB 1.0 binding compiler is registered with {@link JAXBContext}, 345 * the default unmarshal validation handler is 346 * {@link javax.xml.bind.helpers.DefaultValidationEventHandler} and it 347 * terminates the marshal operation after encountering either a fatal error or an error. 348 * For a JAXB 2.0 client application, there is no explicitly defined default 349 * validation handler and the default event handling only 350 * terminates the unmarshal operation after encountering a fatal error. 351 * 352 * </blockquote> 353 * 354 * <p> 355 * <a name="supportedProps"></a> 356 * <b>Supported Properties</b><br> 357 * <blockquote> 358 * <p> 359 * There currently are not any properties required to be supported by all 360 * JAXB Providers on Unmarshaller. However, some providers may support 361 * their own set of provider specific properties. 362 * </blockquote> 363 * 364 * <p> 365 * <a name="unmarshalEventCallback"></a> 366 * <b>Unmarshal Event Callbacks</b><br> 367 * <blockquote> 368 * The {@link Unmarshaller} provides two styles of callback mechanisms 369 * that allow application specific processing during key points in the 370 * unmarshalling process. In 'class defined' event callbacks, application 371 * specific code placed in JAXB mapped classes is triggered during 372 * unmarshalling. 'External listeners' allow for centralized processing 373 * of unmarshal events in one callback method rather than by type event callbacks. 374 * <p> 375 * 'Class defined' event callback methods allow any JAXB mapped class to specify 376 * its own specific callback methods by defining methods with the following method signature: 377 * <blockquote> 378 * <pre> 379 * // This method is called immediately after the object is created and before the unmarshalling of this 380 * // object begins. The callback provides an opportunity to initialize JavaBean properties prior to unmarshalling. 381 * void beforeUnmarshal(Unmarshaller, Object parent); 382 * 383 * //This method is called after all the properties (except IDREF) are unmarshalled for this object, 384 * //but before this object is set to the parent object. 385 * void afterUnmarshal(Unmarshaller, Object parent); 386 * </pre> 387 * </blockquote> 388 * The class defined callback methods should be used when the callback method requires 389 * access to non-public methods and/or fields of the class. 390 * <p> 391 * The external listener callback mechanism enables the registration of a {@link Listener} 392 * instance with an {@link Unmarshaller#setListener(Listener)}. The external listener receives all callback events, 393 * allowing for more centralized processing than per class defined callback methods. The external listener 394 * receives events when unmarshalling process is marshalling to a JAXB element or to JAXB mapped class. 395 * <p> 396 * The 'class defined' and external listener event callback methods are independent of each other, 397 * both can be called for one event. The invocation ordering when both listener callback methods exist is 398 * defined in {@link Listener#beforeUnmarshal(Object, Object)} and {@link Listener#afterUnmarshal(Object, Object)}. 399 * <p> 400 * An event callback method throwing an exception terminates the current unmarshal process. 401 * 402 * </blockquote> 403 * 404 * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul> 405 * @see JAXBContext 406 * @see Marshaller 407 * @see Validator 408 * @since 1.6, JAXB 1.0 409 */ 410 public interface Unmarshaller { 411 412 /** 413 * Unmarshal XML data from the specified file and return the resulting 414 * content tree. 415 * 416 * <p> 417 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 418 * 419 * @param f the file to unmarshal XML data from 420 * @return the newly created root object of the java content tree 421 * 422 * @throws JAXBException 423 * If any unexpected errors occur while unmarshalling 424 * @throws UnmarshalException 425 * If the {@link ValidationEventHandler ValidationEventHandler} 426 * returns false from its {@code handleEvent} method or the 427 * {@code Unmarshaller} is unable to perform the XML to Java 428 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 429 * @throws IllegalArgumentException 430 * If the file parameter is null 431 */ 432 public Object unmarshal( java.io.File f ) throws JAXBException; 433 434 /** 435 * Unmarshal XML data from the specified InputStream and return the 436 * resulting content tree. Validation event location information may 437 * be incomplete when using this form of the unmarshal API. 438 * 439 * <p> 440 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 441 * 442 * @param is the InputStream to unmarshal XML data from 443 * @return the newly created root object of the java content tree 444 * 445 * @throws JAXBException 446 * If any unexpected errors occur while unmarshalling 447 * @throws UnmarshalException 448 * If the {@link ValidationEventHandler ValidationEventHandler} 449 * returns false from its {@code handleEvent} method or the 450 * {@code Unmarshaller} is unable to perform the XML to Java 451 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 452 * @throws IllegalArgumentException 453 * If the InputStream parameter is null 454 */ 455 public Object unmarshal( java.io.InputStream is ) throws JAXBException; 456 457 /** 458 * Unmarshal XML data from the specified Reader and return the 459 * resulting content tree. Validation event location information may 460 * be incomplete when using this form of the unmarshal API, 461 * because a Reader does not provide the system ID. 462 * 463 * <p> 464 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 465 * 466 * @param reader the Reader to unmarshal XML data from 467 * @return the newly created root object of the java content tree 468 * 469 * @throws JAXBException 470 * If any unexpected errors occur while unmarshalling 471 * @throws UnmarshalException 472 * If the {@link ValidationEventHandler ValidationEventHandler} 473 * returns false from its {@code handleEvent} method or the 474 * {@code Unmarshaller} is unable to perform the XML to Java 475 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 476 * @throws IllegalArgumentException 477 * If the InputStream parameter is null 478 * @since 1.6, JAXB 2.0 479 */ 480 public Object unmarshal( Reader reader ) throws JAXBException; 481 482 /** 483 * Unmarshal XML data from the specified URL and return the resulting 484 * content tree. 485 * 486 * <p> 487 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 488 * 489 * @param url the url to unmarshal XML data from 490 * @return the newly created root object of the java content tree 491 * 492 * @throws JAXBException 493 * If any unexpected errors occur while unmarshalling 494 * @throws UnmarshalException 495 * If the {@link ValidationEventHandler ValidationEventHandler} 496 * returns false from its {@code handleEvent} method or the 497 * {@code Unmarshaller} is unable to perform the XML to Java 498 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 499 * @throws IllegalArgumentException 500 * If the URL parameter is null 501 */ 502 public Object unmarshal( java.net.URL url ) throws JAXBException; 503 504 /** 505 * Unmarshal XML data from the specified SAX InputSource and return the 506 * resulting content tree. 507 * 508 * <p> 509 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 510 * 511 * @param source the input source to unmarshal XML data from 512 * @return the newly created root object of the java content tree 513 * 514 * @throws JAXBException 515 * If any unexpected errors occur while unmarshalling 516 * @throws UnmarshalException 517 * If the {@link ValidationEventHandler ValidationEventHandler} 518 * returns false from its {@code handleEvent} method or the 519 * {@code Unmarshaller} is unable to perform the XML to Java 520 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 521 * @throws IllegalArgumentException 522 * If the InputSource parameter is null 523 */ 524 public Object unmarshal( org.xml.sax.InputSource source ) throws JAXBException; 525 526 /** 527 * Unmarshal global XML data from the specified DOM tree and return the resulting 528 * content tree. 529 * 530 * <p> 531 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 532 * 533 * @param node 534 * the document/element to unmarshal XML data from. 535 * The caller must support at least Document and Element. 536 * @return the newly created root object of the java content tree 537 * 538 * @throws JAXBException 539 * If any unexpected errors occur while unmarshalling 540 * @throws UnmarshalException 541 * If the {@link ValidationEventHandler ValidationEventHandler} 542 * returns false from its {@code handleEvent} method or the 543 * {@code Unmarshaller} is unable to perform the XML to Java 544 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 545 * @throws IllegalArgumentException 546 * If the Node parameter is null 547 * @see #unmarshal(org.w3c.dom.Node, Class) 548 */ 549 public Object unmarshal( org.w3c.dom.Node node ) throws JAXBException; 550 551 /** 552 * Unmarshal XML data by JAXB mapped {@code declaredType} 553 * and return the resulting content tree. 554 * 555 * <p> 556 * Implements <a href="#unmarshalByDeclaredType">Unmarshal by Declared Type</a> 557 * 558 * @param node 559 * the document/element to unmarshal XML data from. 560 * The caller must support at least Document and Element. 561 * @param declaredType 562 * appropriate JAXB mapped class to hold {@code node}'s XML data. 563 * 564 * @return <a href="#unmarshalDeclaredTypeReturn">JAXB Element</a> representation of {@code node} 565 * 566 * @throws JAXBException 567 * If any unexpected errors occur while unmarshalling 568 * @throws UnmarshalException 569 * If the {@link ValidationEventHandler ValidationEventHandler} 570 * returns false from its {@code handleEvent} method or the 571 * {@code Unmarshaller} is unable to perform the XML to Java 572 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 573 * @throws IllegalArgumentException 574 * If any parameter is null 575 * @since 1.6, JAXB 2.0 576 */ 577 public <T> JAXBElement<T> unmarshal( org.w3c.dom.Node node, Class<T> declaredType ) throws JAXBException; 578 579 /** 580 * Unmarshal XML data from the specified XML Source and return the 581 * resulting content tree. 582 * 583 * <p> 584 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 585 * 586 * <p> 587 * <a name="saxParserPlugable"></a> 588 * <b>SAX 2.0 Parser Pluggability</b> 589 * <p> 590 * A client application can choose not to use the default parser mechanism 591 * supplied with their JAXB provider. Any SAX 2.0 compliant parser can be 592 * substituted for the JAXB provider's default mechanism. To do so, the 593 * client application must properly configure a {@code SAXSource} containing 594 * an {@code XMLReader} implemented by the SAX 2.0 parser provider. If the 595 * {@code XMLReader} has an {@code org.xml.sax.ErrorHandler} registered 596 * on it, it will be replaced by the JAXB Provider so that validation errors 597 * can be reported via the {@code ValidationEventHandler} mechanism of 598 * JAXB. If the {@code SAXSource} does not contain an {@code XMLReader}, 599 * then the JAXB provider's default parser mechanism will be used. 600 * <p> 601 * This parser replacement mechanism can also be used to replace the JAXB 602 * provider's unmarshal-time validation engine. The client application 603 * must properly configure their SAX 2.0 compliant parser to perform 604 * validation (as shown in the example above). Any {@code SAXParserExceptions} 605 * encountered by the parser during the unmarshal operation will be 606 * processed by the JAXB provider and converted into JAXB 607 * {@code ValidationEvent} objects which will be reported back to the 608 * client via the {@code ValidationEventHandler} registered with the 609 * {@code Unmarshaller}. <i>Note:</i> specifying a substitute validating 610 * SAX 2.0 parser for unmarshalling does not necessarily replace the 611 * validation engine used by the JAXB provider for performing on-demand 612 * validation. 613 * <p> 614 * The only way for a client application to specify an alternate parser 615 * mechanism to be used during unmarshal is via the 616 * {@code unmarshal(SAXSource)} API. All other forms of the unmarshal 617 * method (File, URL, Node, etc) will use the JAXB provider's default 618 * parser and validator mechanisms. 619 * 620 * @param source the XML Source to unmarshal XML data from (providers are 621 * only required to support SAXSource, DOMSource, and StreamSource) 622 * @return the newly created root object of the java content tree 623 * 624 * @throws JAXBException 625 * If any unexpected errors occur while unmarshalling 626 * @throws UnmarshalException 627 * If the {@link ValidationEventHandler ValidationEventHandler} 628 * returns false from its {@code handleEvent} method or the 629 * {@code Unmarshaller} is unable to perform the XML to Java 630 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 631 * @throws IllegalArgumentException 632 * If the Source parameter is null 633 * @see #unmarshal(javax.xml.transform.Source, Class) 634 */ 635 public Object unmarshal( javax.xml.transform.Source source ) 636 throws JAXBException; 637 638 639 /** 640 * Unmarshal XML data from the specified XML Source by {@code declaredType} and return the 641 * resulting content tree. 642 * 643 * <p> 644 * Implements <a href="#unmarshalByDeclaredType">Unmarshal by Declared Type</a> 645 * 646 * <p> 647 * See <a href="#saxParserPlugable">SAX 2.0 Parser Pluggability</a> 648 * 649 * @param source the XML Source to unmarshal XML data from (providers are 650 * only required to support SAXSource, DOMSource, and StreamSource) 651 * @param declaredType 652 * appropriate JAXB mapped class to hold {@code source}'s xml root element 653 * @return Java content rooted by <a href="#unmarshalDeclaredTypeReturn">JAXB Element</a> 654 * 655 * @throws JAXBException 656 * If any unexpected errors occur while unmarshalling 657 * @throws UnmarshalException 658 * If the {@link ValidationEventHandler ValidationEventHandler} 659 * returns false from its {@code handleEvent} method or the 660 * {@code Unmarshaller} is unable to perform the XML to Java 661 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 662 * @throws IllegalArgumentException 663 * If any parameter is null 664 * @since 1.6, JAXB 2.0 665 */ 666 public <T> JAXBElement<T> unmarshal( javax.xml.transform.Source source, Class<T> declaredType ) 667 throws JAXBException; 668 669 /** 670 * Unmarshal XML data from the specified pull parser and return the 671 * resulting content tree. 672 * 673 * <p> 674 * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 675 * 676 * <p> 677 * This method assumes that the parser is on a START_DOCUMENT or 678 * START_ELEMENT event. Unmarshalling will be done from this 679 * start event to the corresponding end event. If this method 680 * returns successfully, the {@code reader} will be pointing at 681 * the token right after the end event. 682 * 683 * @param reader 684 * The parser to be read. 685 * @return 686 * the newly created root object of the java content tree. 687 * 688 * @throws JAXBException 689 * If any unexpected errors occur while unmarshalling 690 * @throws UnmarshalException 691 * If the {@link ValidationEventHandler ValidationEventHandler} 692 * returns false from its {@code handleEvent} method or the 693 * {@code Unmarshaller} is unable to perform the XML to Java 694 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 695 * @throws IllegalArgumentException 696 * If the {@code reader} parameter is null 697 * @throws IllegalStateException 698 * If {@code reader} is not pointing to a START_DOCUMENT or 699 * START_ELEMENT event. 700 * @since 1.6, JAXB 2.0 701 * @see #unmarshal(javax.xml.stream.XMLStreamReader, Class) 702 */ 703 public Object unmarshal( javax.xml.stream.XMLStreamReader reader ) 704 throws JAXBException; 705 706 /** 707 * Unmarshal root element to JAXB mapped {@code declaredType} 708 * and return the resulting content tree. 709 * 710 * <p> 711 * This method implements <a href="#unmarshalByDeclaredType">unmarshal by declaredType</a>. 712 * <p> 713 * This method assumes that the parser is on a START_DOCUMENT or 714 * START_ELEMENT event. Unmarshalling will be done from this 715 * start event to the corresponding end event. If this method 716 * returns successfully, the {@code reader} will be pointing at 717 * the token right after the end event. 718 * 719 * @param reader 720 * The parser to be read. 721 * @param declaredType 722 * appropriate JAXB mapped class to hold {@code reader}'s START_ELEMENT XML data. 723 * 724 * @return content tree rooted by <a href="#unmarshalDeclaredTypeReturn">JAXB Element representation</a> 725 * 726 * @throws JAXBException 727 * If any unexpected errors occur while unmarshalling 728 * @throws UnmarshalException 729 * If the {@link ValidationEventHandler ValidationEventHandler} 730 * returns false from its {@code handleEvent} method or the 731 * {@code Unmarshaller} is unable to perform the XML to Java 732 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 733 * @throws IllegalArgumentException 734 * If any parameter is null 735 * @since 1.6, JAXB 2.0 736 */ 737 public <T> JAXBElement<T> unmarshal( javax.xml.stream.XMLStreamReader reader, Class<T> declaredType ) throws JAXBException; 738 739 /** 740 * Unmarshal XML data from the specified pull parser and return the 741 * resulting content tree. 742 * 743 * <p> 744 * This method is an <a href="#unmarshalGlobal">Unmarshal Global Root method</a>. 745 * 746 * <p> 747 * This method assumes that the parser is on a START_DOCUMENT or 748 * START_ELEMENT event. Unmarshalling will be done from this 749 * start event to the corresponding end event. If this method 750 * returns successfully, the {@code reader} will be pointing at 751 * the token right after the end event. 752 * 753 * @param reader 754 * The parser to be read. 755 * @return 756 * the newly created root object of the java content tree. 757 * 758 * @throws JAXBException 759 * If any unexpected errors occur while unmarshalling 760 * @throws UnmarshalException 761 * If the {@link ValidationEventHandler ValidationEventHandler} 762 * returns false from its {@code handleEvent} method or the 763 * {@code Unmarshaller} is unable to perform the XML to Java 764 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 765 * @throws IllegalArgumentException 766 * If the {@code reader} parameter is null 767 * @throws IllegalStateException 768 * If {@code reader} is not pointing to a START_DOCUMENT or 769 * START_ELEMENT event. 770 * @since 1.6, JAXB 2.0 771 * @see #unmarshal(javax.xml.stream.XMLEventReader, Class) 772 */ 773 public Object unmarshal( javax.xml.stream.XMLEventReader reader ) 774 throws JAXBException; 775 776 /** 777 * Unmarshal root element to JAXB mapped {@code declaredType} 778 * and return the resulting content tree. 779 * 780 * <p> 781 * This method implements <a href="#unmarshalByDeclaredType">unmarshal by declaredType</a>. 782 * 783 * <p> 784 * This method assumes that the parser is on a START_DOCUMENT or 785 * START_ELEMENT event. Unmarshalling will be done from this 786 * start event to the corresponding end event. If this method 787 * returns successfully, the {@code reader} will be pointing at 788 * the token right after the end event. 789 * 790 * @param reader 791 * The parser to be read. 792 * @param declaredType 793 * appropriate JAXB mapped class to hold {@code reader}'s START_ELEMENT XML data. 794 * 795 * @return content tree rooted by <a href="#unmarshalDeclaredTypeReturn">JAXB Element representation</a> 796 * 797 * @throws JAXBException 798 * If any unexpected errors occur while unmarshalling 799 * @throws UnmarshalException 800 * If the {@link ValidationEventHandler ValidationEventHandler} 801 * returns false from its {@code handleEvent} method or the 802 * {@code Unmarshaller} is unable to perform the XML to Java 803 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 804 * @throws IllegalArgumentException 805 * If any parameter is null 806 * @since 1.6, JAXB 2.0 807 */ 808 public <T> JAXBElement<T> unmarshal( javax.xml.stream.XMLEventReader reader, Class<T> declaredType ) throws JAXBException; 809 810 /** 811 * Get an unmarshaller handler object that can be used as a component in 812 * an XML pipeline. 813 * 814 * <p> 815 * The JAXB Provider can return the same handler object for multiple 816 * invocations of this method. In other words, this method does not 817 * necessarily create a new instance of {@code UnmarshallerHandler}. If the 818 * application needs to use more than one {@code UnmarshallerHandler}, it 819 * should create more than one {@code Unmarshaller}. 820 * 821 * @return the unmarshaller handler object 822 * @see UnmarshallerHandler 823 */ 824 public UnmarshallerHandler getUnmarshallerHandler(); 825 826 /** 827 * Specifies whether or not the default validation mechanism of the 828 * {@code Unmarshaller} should validate during unmarshal operations. 829 * By default, the {@code Unmarshaller} does not validate. 830 * <p> 831 * This method may only be invoked before or after calling one of the 832 * unmarshal methods. 833 * <p> 834 * This method only controls the JAXB Provider's default unmarshal-time 835 * validation mechanism - it has no impact on clients that specify their 836 * own validating SAX 2.0 compliant parser. Clients that specify their 837 * own unmarshal-time validation mechanism may wish to turn off the JAXB 838 * Provider's default validation mechanism via this API to avoid "double 839 * validation". 840 * <p> 841 * This method is deprecated as of JAXB 2.0 - please use the new 842 * {@link #setSchema(javax.xml.validation.Schema)} API. 843 * 844 * @param validating true if the Unmarshaller should validate during 845 * unmarshal, false otherwise 846 * @throws JAXBException if an error occurred while enabling or disabling 847 * validation at unmarshal time 848 * @throws UnsupportedOperationException could be thrown if this method is 849 * invoked on an Unmarshaller created from a JAXBContext referencing 850 * JAXB 2.0 mapped classes 851 * @deprecated since JAXB2.0, please see {@link #setSchema(javax.xml.validation.Schema)} 852 */ 853 public void setValidating( boolean validating ) 854 throws JAXBException; 855 856 /** 857 * Indicates whether or not the {@code Unmarshaller} is configured to 858 * validate during unmarshal operations. 859 * <p> 860 * This API returns the state of the JAXB Provider's default unmarshal-time 861 * validation mechanism. 862 * <p> 863 * This method is deprecated as of JAXB 2.0 - please use the new 864 * {@link #getSchema()} API. 865 * 866 * @return true if the Unmarshaller is configured to validate during 867 * unmarshal operations, false otherwise 868 * @throws JAXBException if an error occurs while retrieving the validating 869 * flag 870 * @throws UnsupportedOperationException could be thrown if this method is 871 * invoked on an Unmarshaller created from a JAXBContext referencing 872 * JAXB 2.0 mapped classes 873 * @deprecated since JAXB2.0, please see {@link #getSchema()} 874 */ 875 public boolean isValidating() 876 throws JAXBException; 877 878 /** 879 * Allow an application to register a {@code ValidationEventHandler}. 880 * <p> 881 * The {@code ValidationEventHandler} will be called by the JAXB Provider 882 * if any validation errors are encountered during calls to any of the 883 * unmarshal methods. If the client application does not register a 884 * {@code ValidationEventHandler} before invoking the unmarshal methods, 885 * then {@code ValidationEvents} will be handled by the default event 886 * handler which will terminate the unmarshal operation after the first 887 * error or fatal error is encountered. 888 * <p> 889 * Calling this method with a null parameter will cause the Unmarshaller 890 * to revert back to the default event handler. 891 * 892 * @param handler the validation event handler 893 * @throws JAXBException if an error was encountered while setting the 894 * event handler 895 */ 896 public void setEventHandler( ValidationEventHandler handler ) 897 throws JAXBException; 898 899 /** 900 * Return the current event handler or the default event handler if one 901 * hasn't been set. 902 * 903 * @return the current ValidationEventHandler or the default event handler 904 * if it hasn't been set 905 * @throws JAXBException if an error was encountered while getting the 906 * current event handler 907 */ 908 public ValidationEventHandler getEventHandler() 909 throws JAXBException; 910 911 /** 912 * Set the particular property in the underlying implementation of 913 * {@code Unmarshaller}. This method can only be used to set one of 914 * the standard JAXB defined properties above or a provider specific 915 * property. Attempting to set an undefined property will result in 916 * a PropertyException being thrown. See <a href="#supportedProps"> 917 * Supported Properties</a>. 918 * 919 * @param name the name of the property to be set. This value can either 920 * be specified using one of the constant fields or a user 921 * supplied string. 922 * @param value the value of the property to be set 923 * 924 * @throws PropertyException when there is an error processing the given 925 * property or value 926 * @throws IllegalArgumentException 927 * If the name parameter is null 928 */ 929 public void setProperty( String name, Object value ) 930 throws PropertyException; 931 932 /** 933 * Get the particular property in the underlying implementation of 934 * {@code Unmarshaller}. This method can only be used to get one of 935 * the standard JAXB defined properties above or a provider specific 936 * property. Attempting to get an undefined property will result in 937 * a PropertyException being thrown. See <a href="#supportedProps"> 938 * Supported Properties</a>. 939 * 940 * @param name the name of the property to retrieve 941 * @return the value of the requested property 942 * 943 * @throws PropertyException 944 * when there is an error retrieving the given property or value 945 * property name 946 * @throws IllegalArgumentException 947 * If the name parameter is null 948 */ 949 public Object getProperty( String name ) throws PropertyException; 950 951 /** 952 * Specify the JAXP 1.3 {@link javax.xml.validation.Schema Schema} 953 * object that should be used to validate subsequent unmarshal operations 954 * against. Passing null into this method will disable validation. 955 * <p> 956 * This method replaces the deprecated {@link #setValidating(boolean) setValidating(boolean)} 957 * API. 958 * 959 * <p> 960 * Initially this property is set to {@code null}. 961 * 962 * @param schema Schema object to validate unmarshal operations against or null to disable validation 963 * @throws UnsupportedOperationException could be thrown if this method is 964 * invoked on an Unmarshaller created from a JAXBContext referencing 965 * JAXB 1.0 mapped classes 966 * @since 1.6, JAXB 2.0 967 */ 968 public void setSchema( javax.xml.validation.Schema schema ); 969 970 /** 971 * Get the JAXP 1.3 {@link javax.xml.validation.Schema Schema} object 972 * being used to perform unmarshal-time validation. If there is no 973 * Schema set on the unmarshaller, then this method will return null 974 * indicating that unmarshal-time validation will not be performed. 975 * <p> 976 * This method provides replacement functionality for the deprecated 977 * {@link #isValidating()} API as well as access to the Schema object. 978 * To determine if the Unmarshaller has validation enabled, simply 979 * test the return type for null: 980 * <pre>{@code 981 * boolean isValidating = u.getSchema()!=null; 982 * }</pre> 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);}. 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>Unmarshal time validation, enabled via {@link #setSchema(Schema)}, 1054 * must be supported even when unmarshaller is performing XOP processing. 1055 * </p> 1056 * 1057 * @throws IllegalStateException if attempt to concurrently call this 1058 * method during a unmarshal operation. 1059 */ 1060 void setAttachmentUnmarshaller(AttachmentUnmarshaller au); 1061 1062 AttachmentUnmarshaller getAttachmentUnmarshaller(); 1063 1064 /** 1065 * <p> 1066 * Register an instance of an implementation of this class with {@link Unmarshaller} to externally listen 1067 * for unmarshal events. 1068 * </p> 1069 * <p> 1070 * This class enables pre and post processing of an instance of a JAXB mapped class 1071 * as XML data is unmarshalled into it. The event callbacks are called when unmarshalling 1072 * XML content into a JAXBElement instance or a JAXB mapped class that represents a complex type definition. 1073 * The event callbacks are not called when unmarshalling to an instance of a 1074 * Java datatype that represents a simple type definition. 1075 * </p> 1076 * <p> 1077 * External listener is one of two different mechanisms for defining unmarshal event callbacks. 1078 * See <a href="Unmarshaller.html#unmarshalEventCallback">Unmarshal Event Callbacks</a> for an overview. 1079 * </p> 1080 * (@link #setListener(Listener)} 1081 * (@link #getListener()} 1082 * 1083 * @since 1.6, JAXB 2.0 1084 */ 1085 public static abstract class Listener { 1086 /** 1087 * <p> 1088 * Callback method invoked before unmarshalling into {@code target}. 1089 * </p> 1090 * <p> 1091 * This method is invoked immediately after {@code target} was created and 1092 * before the unmarshalling of this object begins. Note that 1093 * if the class of {@code target} defines its own {@code beforeUnmarshal} method, 1094 * the class specific callback method is invoked before this method is invoked. 1095 * 1096 * @param target non-null instance of JAXB mapped class prior to unmarshalling into it. 1097 * @param parent instance of JAXB mapped class that will eventually reference {@code target}. 1098 * {@code null} when {@code target} is root element. 1099 */ 1100 public void beforeUnmarshal(Object target, Object parent) { 1101 } 1102 1103 /** 1104 * <p> 1105 * Callback method invoked after unmarshalling XML data into {@code target}. 1106 * </p> 1107 * <p> 1108 * This method is invoked after all the properties (except IDREF) 1109 * are unmarshalled into {@code target}, 1110 * but before {@code target} is set into its {@code parent} object. 1111 * Note that if the class of {@code target} defines its own {@code afterUnmarshal} 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 {@code target}. 1116 * {@code null} when {@code target} 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 {@code null}. 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} 1139 * if no Listener is registered with this Unmarshaller. 1140 * @since 1.6, JAXB 2.0 1141 */ 1142 public Listener getListener(); 1143 }