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