1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/src/share/jaxws_classes/javax/xml/bind/Unmarshaller.java Tue Mar 06 16:09:35 2012 -0800 1.3 @@ -0,0 +1,1142 @@ 1.4 +/* 1.5 + * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved. 1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 1.7 + * 1.8 + * This code is free software; you can redistribute it and/or modify it 1.9 + * under the terms of the GNU General Public License version 2 only, as 1.10 + * published by the Free Software Foundation. Oracle designates this 1.11 + * particular file as subject to the "Classpath" exception as provided 1.12 + * by Oracle in the LICENSE file that accompanied this code. 1.13 + * 1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT 1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1.17 + * version 2 for more details (a copy is included in the LICENSE file that 1.18 + * accompanied this code). 1.19 + * 1.20 + * You should have received a copy of the GNU General Public License version 1.21 + * 2 along with this work; if not, write to the Free Software Foundation, 1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1.23 + * 1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 1.25 + * or visit www.oracle.com if you need additional information or have any 1.26 + * questions. 1.27 + */ 1.28 + 1.29 +package javax.xml.bind; 1.30 + 1.31 +import javax.xml.bind.annotation.adapters.XmlAdapter; 1.32 +import javax.xml.bind.attachment.AttachmentUnmarshaller; 1.33 +import javax.xml.validation.Schema; 1.34 +import java.io.Reader; 1.35 + 1.36 +/** 1.37 + * The <tt>Unmarshaller</tt> class governs the process of deserializing XML 1.38 + * data into newly created Java content trees, optionally validating the XML 1.39 + * data as it is unmarshalled. It provides an overloading of unmarshal methods 1.40 + * for many different input kinds. 1.41 + * 1.42 + * <p> 1.43 + * Unmarshalling from a File: 1.44 + * <blockquote> 1.45 + * <pre> 1.46 + * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 1.47 + * Unmarshaller u = jc.createUnmarshaller(); 1.48 + * Object o = u.unmarshal( new File( "nosferatu.xml" ) ); 1.49 + * </pre> 1.50 + * </blockquote> 1.51 + * 1.52 + * 1.53 + * <p> 1.54 + * Unmarshalling from an InputStream: 1.55 + * <blockquote> 1.56 + * <pre> 1.57 + * InputStream is = new FileInputStream( "nosferatu.xml" ); 1.58 + * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 1.59 + * Unmarshaller u = jc.createUnmarshaller(); 1.60 + * Object o = u.unmarshal( is ); 1.61 + * </pre> 1.62 + * </blockquote> 1.63 + * 1.64 + * <p> 1.65 + * Unmarshalling from a URL: 1.66 + * <blockquote> 1.67 + * <pre> 1.68 + * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 1.69 + * Unmarshaller u = jc.createUnmarshaller(); 1.70 + * URL url = new URL( "http://beaker.east/nosferatu.xml" ); 1.71 + * Object o = u.unmarshal( url ); 1.72 + * </pre> 1.73 + * </blockquote> 1.74 + * 1.75 + * <p> 1.76 + * Unmarshalling from a StringBuffer using a 1.77 + * <tt>javax.xml.transform.stream.StreamSource</tt>: 1.78 + * <blockquote> 1.79 + * <pre> 1.80 + * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 1.81 + * Unmarshaller u = jc.createUnmarshaller(); 1.82 + * StringBuffer xmlStr = new StringBuffer( "<?xml version="1.0"?>..." ); 1.83 + * Object o = u.unmarshal( new StreamSource( new StringReader( xmlStr.toString() ) ) ); 1.84 + * </pre> 1.85 + * </blockquote> 1.86 + * 1.87 + * <p> 1.88 + * Unmarshalling from a <tt>org.w3c.dom.Node</tt>: 1.89 + * <blockquote> 1.90 + * <pre> 1.91 + * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 1.92 + * Unmarshaller u = jc.createUnmarshaller(); 1.93 + * 1.94 + * DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); 1.95 + * dbf.setNamespaceAware(true); 1.96 + * DocumentBuilder db = dbf.newDocumentBuilder(); 1.97 + * Document doc = db.parse(new File( "nosferatu.xml")); 1.98 + 1.99 + * Object o = u.unmarshal( doc ); 1.100 + * </pre> 1.101 + * </blockquote> 1.102 + * 1.103 + * <p> 1.104 + * Unmarshalling from a <tt>javax.xml.transform.sax.SAXSource</tt> using a 1.105 + * client specified validating SAX2.0 parser: 1.106 + * <blockquote> 1.107 + * <pre> 1.108 + * // configure a validating SAX2.0 parser (Xerces2) 1.109 + * static final String JAXP_SCHEMA_LANGUAGE = 1.110 + * "http://java.sun.com/xml/jaxp/properties/schemaLanguage"; 1.111 + * static final String JAXP_SCHEMA_LOCATION = 1.112 + * "http://java.sun.com/xml/jaxp/properties/schemaSource"; 1.113 + * static final String W3C_XML_SCHEMA = 1.114 + * "http://www.w3.org/2001/XMLSchema"; 1.115 + * 1.116 + * System.setProperty( "javax.xml.parsers.SAXParserFactory", 1.117 + * "org.apache.xerces.jaxp.SAXParserFactoryImpl" ); 1.118 + * 1.119 + * SAXParserFactory spf = SAXParserFactory.newInstance(); 1.120 + * spf.setNamespaceAware(true); 1.121 + * spf.setValidating(true); 1.122 + * SAXParser saxParser = spf.newSAXParser(); 1.123 + * 1.124 + * try { 1.125 + * saxParser.setProperty(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA); 1.126 + * saxParser.setProperty(JAXP_SCHEMA_LOCATION, "http://...."); 1.127 + * } catch (SAXNotRecognizedException x) { 1.128 + * // exception handling omitted 1.129 + * } 1.130 + * 1.131 + * XMLReader xmlReader = saxParser.getXMLReader(); 1.132 + * SAXSource source = 1.133 + * new SAXSource( xmlReader, new InputSource( "http://..." ) ); 1.134 + * 1.135 + * // Setup JAXB to unmarshal 1.136 + * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 1.137 + * Unmarshaller u = jc.createUnmarshaller(); 1.138 + * ValidationEventCollector vec = new ValidationEventCollector(); 1.139 + * u.setEventHandler( vec ); 1.140 + * 1.141 + * // turn off the JAXB provider's default validation mechanism to 1.142 + * // avoid duplicate validation 1.143 + * u.setValidating( false ) 1.144 + * 1.145 + * // unmarshal 1.146 + * Object o = u.unmarshal( source ); 1.147 + * 1.148 + * // check for events 1.149 + * if( vec.hasEvents() ) { 1.150 + * // iterate over events 1.151 + * } 1.152 + * </pre> 1.153 + * </blockquote> 1.154 + * 1.155 + * <p> 1.156 + * Unmarshalling from a StAX XMLStreamReader: 1.157 + * <blockquote> 1.158 + * <pre> 1.159 + * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 1.160 + * Unmarshaller u = jc.createUnmarshaller(); 1.161 + * 1.162 + * javax.xml.stream.XMLStreamReader xmlStreamReader = 1.163 + * javax.xml.stream.XMLInputFactory().newInstance().createXMLStreamReader( ... ); 1.164 + * 1.165 + * Object o = u.unmarshal( xmlStreamReader ); 1.166 + * </pre> 1.167 + * </blockquote> 1.168 + * 1.169 + * <p> 1.170 + * Unmarshalling from a StAX XMLEventReader: 1.171 + * <blockquote> 1.172 + * <pre> 1.173 + * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 1.174 + * Unmarshaller u = jc.createUnmarshaller(); 1.175 + * 1.176 + * javax.xml.stream.XMLEventReader xmlEventReader = 1.177 + * javax.xml.stream.XMLInputFactory().newInstance().createXMLEventReader( ... ); 1.178 + * 1.179 + * Object o = u.unmarshal( xmlEventReader ); 1.180 + * </pre> 1.181 + * </blockquote> 1.182 + * 1.183 + * <p> 1.184 + * <a name="unmarshalEx"></a> 1.185 + * <b>Unmarshalling XML Data</b><br> 1.186 + * <blockquote> 1.187 + * Unmarshalling can deserialize XML data that represents either an entire XML document 1.188 + * or a subtree of an XML document. Typically, it is sufficient to use the 1.189 + * unmarshalling methods described by 1.190 + * <a href="#unmarshalGlobal">Unmarshal root element that is declared globally</a>. 1.191 + * These unmarshal methods utilize {@link JAXBContext}'s mapping of global XML element 1.192 + * declarations and type definitions to JAXB mapped classes to initiate the 1.193 + * unmarshalling of the root element of XML data. When the {@link JAXBContext}'s 1.194 + * mappings are not sufficient to unmarshal the root element of XML data, 1.195 + * the application can assist the unmarshalling process by using the 1.196 + * <a href="#unmarshalByDeclaredType">unmarshal by declaredType methods</a>. 1.197 + * These methods are useful for unmarshalling XML data where 1.198 + * the root element corresponds to a local element declaration in the schema. 1.199 + * </blockquote> 1.200 + * 1.201 + * <blockquote> 1.202 + * An unmarshal method never returns null. If the unmarshal process is unable to unmarshal 1.203 + * the root of XML content to a JAXB mapped object, a fatal error is reported that 1.204 + * terminates processing by throwing JAXBException. 1.205 + * </blockquote> 1.206 + * 1.207 + * <p> 1.208 + * <a name="unmarshalGlobal"></a> 1.209 + * <b>Unmarshal a root element that is globally declared</b><br> 1.210 + * <blockquote> 1.211 + * The unmarshal methods that do not have an <tt>declaredType</tt> parameter use 1.212 + * {@link JAXBContext} to unmarshal the root element of an XML data. The {@link JAXBContext} 1.213 + * instance is the one that was used to create this <tt>Unmarshaller</tt>. The {@link JAXBContext} 1.214 + * instance maintains a mapping of globally declared XML element and type definition names to 1.215 + * JAXB mapped classes. The unmarshal method checks if {@link JAXBContext} has a mapping 1.216 + * from the root element's XML name and/or <tt>@xsi:type</tt> to a JAXB mapped class. If it does, it umarshalls the 1.217 + * XML data using the appropriate JAXB mapped class. Note that when the root element name is unknown and the root 1.218 + * element has an <tt>@xsi:type</tt>, the XML data is unmarshalled 1.219 + * using that JAXB mapped class as the value of a {@link JAXBElement}. 1.220 + * When the {@link JAXBContext} object does not have a mapping for the root element's name 1.221 + * nor its <tt>@xsi:type</tt>, if it exists, 1.222 + * then the unmarshal operation will abort immediately by throwing a {@link UnmarshalException 1.223 + * UnmarshalException}. This exception scenario can be worked around by using the unmarshal by 1.224 + * declaredType methods described in the next subsection. 1.225 + * </blockquote> 1.226 + * 1.227 + * <p> 1.228 + * <a name="unmarshalByDeclaredType"></a> 1.229 + * <b>Unmarshal by Declared Type</b><br> 1.230 + * <blockquote> 1.231 + * The unmarshal methods with a <code>declaredType</code> parameter enable an 1.232 + * application to deserialize a root element of XML data, even when 1.233 + * there is no mapping in {@link JAXBContext} of the root element's XML name. 1.234 + * The unmarshaller unmarshals the root element using the application provided 1.235 + * mapping specified as the <tt>declaredType</tt> parameter. 1.236 + * Note that even when the root element's element name is mapped by {@link JAXBContext}, 1.237 + * the <code>declaredType</code> parameter overrides that mapping for 1.238 + * deserializing the root element when using these unmarshal methods. 1.239 + * Additionally, when the root element of XML data has an <tt>xsi:type</tt> attribute and 1.240 + * that attribute's value references a type definition that is mapped 1.241 + * to a JAXB mapped class by {@link JAXBContext}, that the root 1.242 + * element's <tt>xsi:type</tt> attribute takes 1.243 + * precedence over the unmarshal methods <tt>declaredType</tt> parameter. 1.244 + * These methods always return a <tt>JAXBElement<declaredType></tt> 1.245 + * instance. The table below shows how the properties of the returned JAXBElement 1.246 + * instance are set. 1.247 + * 1.248 + * <a name="unmarshalDeclaredTypeReturn"></a> 1.249 + * <p> 1.250 + * <table border="2" rules="all" cellpadding="4"> 1.251 + * <thead> 1.252 + * <tr> 1.253 + * <th align="center" colspan="2"> 1.254 + * Unmarshal By Declared Type returned JAXBElement 1.255 + * </tr> 1.256 + * <tr> 1.257 + * <th>JAXBElement Property</th> 1.258 + * <th>Value</th> 1.259 + * </tr> 1.260 + * <tr> 1.261 + * <td>name</td> 1.262 + * <td><code>xml element name</code></td> 1.263 + * </tr> 1.264 + * </thead> 1.265 + * <tbody> 1.266 + * <tr> 1.267 + * <td>value</td> 1.268 + * <td><code>instanceof declaredType</code></td> 1.269 + * </tr> 1.270 + * <tr> 1.271 + * <td>declaredType</td> 1.272 + * <td>unmarshal method <code>declaredType</code> parameter</td> 1.273 + * </tr> 1.274 + * <tr> 1.275 + * <td>scope</td> 1.276 + * <td><code>null</code> <i>(actual scope is unknown)</i></td> 1.277 + * </tr> 1.278 + * </tbody> 1.279 + * </table> 1.280 + * </blockquote> 1.281 + * 1.282 + * <p> 1.283 + * The following is an example of 1.284 + * <a href="#unmarshalByDeclaredType">unmarshal by declaredType method</a>. 1.285 + * <p> 1.286 + * Unmarshal by declaredType from a <tt>org.w3c.dom.Node</tt>: 1.287 + * <blockquote> 1.288 + * <pre> 1.289 + * Schema fragment for example 1.290 + * <xs:schema> 1.291 + * <xs:complexType name="FooType">...<\xs:complexType> 1.292 + * <!-- global element declaration "PurchaseOrder" --> 1.293 + * <xs:element name="PurchaseOrder"> 1.294 + * <xs:complexType> 1.295 + * <xs:sequence> 1.296 + * <!-- local element declaration "foo" --> 1.297 + * <xs:element name="foo" type="FooType"/> 1.298 + * ... 1.299 + * </xs:sequence> 1.300 + * </xs:complexType> 1.301 + * </xs:element> 1.302 + * </xs:schema> 1.303 + * 1.304 + * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 1.305 + * Unmarshaller u = jc.createUnmarshaller(); 1.306 + * 1.307 + * DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); 1.308 + * dbf.setNamespaceAware(true); 1.309 + * DocumentBuilder db = dbf.newDocumentBuilder(); 1.310 + * Document doc = db.parse(new File( "nosferatu.xml")); 1.311 + * Element fooSubtree = ...; // traverse DOM till reach xml element foo, constrained by a 1.312 + * // local element declaration in schema. 1.313 + * 1.314 + * // FooType is the JAXB mapping of the type of local element declaration foo. 1.315 + * JAXBElement<FooType> foo = u.unmarshal( fooSubtree, FooType.class); 1.316 + * </pre> 1.317 + * </blockquote> 1.318 + * 1.319 + * <p> 1.320 + * <b>Support for SAX2.0 Compliant Parsers</b><br> 1.321 + * <blockquote> 1.322 + * A client application has the ability to select the SAX2.0 compliant parser 1.323 + * of their choice. If a SAX parser is not selected, then the JAXB Provider's 1.324 + * default parser will be used. Even though the JAXB Provider's default parser 1.325 + * is not required to be SAX2.0 compliant, all providers are required to allow 1.326 + * a client application to specify their own SAX2.0 parser. Some providers may 1.327 + * require the client application to specify the SAX2.0 parser at schema compile 1.328 + * time. See {@link #unmarshal(javax.xml.transform.Source) unmarshal(Source)} 1.329 + * for more detail. 1.330 + * </blockquote> 1.331 + * 1.332 + * <p> 1.333 + * <b>Validation and Well-Formedness</b><br> 1.334 + * <blockquote> 1.335 + * <p> 1.336 + * A client application can enable or disable JAXP 1.3 validation 1.337 + * mechanism via the <tt>setSchema(javax.xml.validation.Schema)</tt> API. 1.338 + * Sophisticated clients can specify their own validating SAX 2.0 compliant 1.339 + * parser and bypass the JAXP 1.3 validation mechanism using the 1.340 + * {@link #unmarshal(javax.xml.transform.Source) unmarshal(Source)} API. 1.341 + * 1.342 + * <p> 1.343 + * Since unmarshalling invalid XML content is defined in JAXB 2.0, 1.344 + * the Unmarshaller default validation event handler was made more lenient 1.345 + * than in JAXB 1.0. When schema-derived code generated 1.346 + * by JAXB 1.0 binding compiler is registered with {@link JAXBContext}, 1.347 + * the default unmarshal validation handler is 1.348 + * {@link javax.xml.bind.helpers.DefaultValidationEventHandler} and it 1.349 + * terminates the marshal operation after encountering either a fatal error or an error. 1.350 + * For a JAXB 2.0 client application, there is no explicitly defined default 1.351 + * validation handler and the default event handling only 1.352 + * terminates the marshal operation after encountering a fatal error. 1.353 + * 1.354 + * </blockquote> 1.355 + * 1.356 + * <p> 1.357 + * <a name="supportedProps"></a> 1.358 + * <b>Supported Properties</b><br> 1.359 + * <blockquote> 1.360 + * <p> 1.361 + * There currently are not any properties required to be supported by all 1.362 + * JAXB Providers on Unmarshaller. However, some providers may support 1.363 + * their own set of provider specific properties. 1.364 + * </blockquote> 1.365 + * 1.366 + * <p> 1.367 + * <a name="unmarshalEventCallback"></a> 1.368 + * <b>Unmarshal Event Callbacks</b><br> 1.369 + * <blockquote> 1.370 + * The {@link Unmarshaller} provides two styles of callback mechanisms 1.371 + * that allow application specific processing during key points in the 1.372 + * unmarshalling process. In 'class defined' event callbacks, application 1.373 + * specific code placed in JAXB mapped classes is triggered during 1.374 + * unmarshalling. 'External listeners' allow for centralized processing 1.375 + * of unmarshal events in one callback method rather than by type event callbacks. 1.376 + * <p> 1.377 + * 'Class defined' event callback methods allow any JAXB mapped class to specify 1.378 + * its own specific callback methods by defining methods with the following method signature: 1.379 + * <blockquote> 1.380 + * <pre> 1.381 + * // This method is called immediately after the object is created and before the unmarshalling of this 1.382 + * // object begins. The callback provides an opportunity to initialize JavaBean properties prior to unmarshalling. 1.383 + * void beforeUnmarshal(Unmarshaller, Object parent); 1.384 + * 1.385 + * //This method is called after all the properties (except IDREF) are unmarshalled for this object, 1.386 + * //but before this object is set to the parent object. 1.387 + * void afterUnmarshal(Unmarshaller, Object parent); 1.388 + * </pre> 1.389 + * </blockquote> 1.390 + * The class defined callback methods should be used when the callback method requires 1.391 + * access to non-public methods and/or fields of the class. 1.392 + * <p> 1.393 + * The external listener callback mechanism enables the registration of a {@link Listener} 1.394 + * instance with an {@link Unmarshaller#setListener(Listener)}. The external listener receives all callback events, 1.395 + * allowing for more centralized processing than per class defined callback methods. The external listener 1.396 + * receives events when unmarshalling proces is marshalling to a JAXB element or to JAXB mapped class. 1.397 + * <p> 1.398 + * The 'class defined' and external listener event callback methods are independent of each other, 1.399 + * both can be called for one event. The invocation ordering when both listener callback methods exist is 1.400 + * defined in {@link Listener#beforeUnmarshal(Object, Object)} and {@link Listener#afterUnmarshal(Object, Object)}. 1.401 +* <p> 1.402 + * An event callback method throwing an exception terminates the current unmarshal process. 1.403 + * 1.404 + * </blockquote> 1.405 + * 1.406 + * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul> 1.407 + * @see JAXBContext 1.408 + * @see Marshaller 1.409 + * @see Validator 1.410 + * @since JAXB1.0 1.411 + */ 1.412 +public interface Unmarshaller { 1.413 + 1.414 + /** 1.415 + * Unmarshal XML data from the specified file and return the resulting 1.416 + * content tree. 1.417 + * 1.418 + * <p> 1.419 + * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 1.420 + * 1.421 + * @param f the file to unmarshal XML data from 1.422 + * @return the newly created root object of the java content tree 1.423 + * 1.424 + * @throws JAXBException 1.425 + * If any unexpected errors occur while unmarshalling 1.426 + * @throws UnmarshalException 1.427 + * If the {@link ValidationEventHandler ValidationEventHandler} 1.428 + * returns false from its <tt>handleEvent</tt> method or the 1.429 + * <tt>Unmarshaller</tt> is unable to perform the XML to Java 1.430 + * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 1.431 + * @throws IllegalArgumentException 1.432 + * If the file parameter is null 1.433 + */ 1.434 + public Object unmarshal( java.io.File f ) throws JAXBException; 1.435 + 1.436 + /** 1.437 + * Unmarshal XML data from the specified InputStream and return the 1.438 + * resulting content tree. Validation event location information may 1.439 + * be incomplete when using this form of the unmarshal API. 1.440 + * 1.441 + * <p> 1.442 + * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 1.443 + * 1.444 + * @param is the InputStream to unmarshal XML data from 1.445 + * @return the newly created root object of the java content tree 1.446 + * 1.447 + * @throws JAXBException 1.448 + * If any unexpected errors occur while unmarshalling 1.449 + * @throws UnmarshalException 1.450 + * If the {@link ValidationEventHandler ValidationEventHandler} 1.451 + * returns false from its <tt>handleEvent</tt> method or the 1.452 + * <tt>Unmarshaller</tt> is unable to perform the XML to Java 1.453 + * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 1.454 + * @throws IllegalArgumentException 1.455 + * If the InputStream parameter is null 1.456 + */ 1.457 + public Object unmarshal( java.io.InputStream is ) throws JAXBException; 1.458 + 1.459 + /** 1.460 + * Unmarshal XML data from the specified Reader and return the 1.461 + * resulting content tree. Validation event location information may 1.462 + * be incomplete when using this form of the unmarshal API, 1.463 + * because a Reader does not provide the system ID. 1.464 + * 1.465 + * <p> 1.466 + * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 1.467 + * 1.468 + * @param reader the Reader to unmarshal XML data from 1.469 + * @return the newly created root object of the java content tree 1.470 + * 1.471 + * @throws JAXBException 1.472 + * If any unexpected errors occur while unmarshalling 1.473 + * @throws UnmarshalException 1.474 + * If the {@link ValidationEventHandler ValidationEventHandler} 1.475 + * returns false from its <tt>handleEvent</tt> method or the 1.476 + * <tt>Unmarshaller</tt> is unable to perform the XML to Java 1.477 + * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 1.478 + * @throws IllegalArgumentException 1.479 + * If the InputStream parameter is null 1.480 + * @since JAXB2.0 1.481 + */ 1.482 + public Object unmarshal( Reader reader ) throws JAXBException; 1.483 + 1.484 + /** 1.485 + * Unmarshal XML data from the specified URL and return the resulting 1.486 + * content tree. 1.487 + * 1.488 + * <p> 1.489 + * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 1.490 + * 1.491 + * @param url the url to unmarshal XML data from 1.492 + * @return the newly created root object of the java content tree 1.493 + * 1.494 + * @throws JAXBException 1.495 + * If any unexpected errors occur while unmarshalling 1.496 + * @throws UnmarshalException 1.497 + * If the {@link ValidationEventHandler ValidationEventHandler} 1.498 + * returns false from its <tt>handleEvent</tt> method or the 1.499 + * <tt>Unmarshaller</tt> is unable to perform the XML to Java 1.500 + * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 1.501 + * @throws IllegalArgumentException 1.502 + * If the URL parameter is null 1.503 + */ 1.504 + public Object unmarshal( java.net.URL url ) throws JAXBException; 1.505 + 1.506 + /** 1.507 + * Unmarshal XML data from the specified SAX InputSource and return the 1.508 + * resulting content tree. 1.509 + * 1.510 + * <p> 1.511 + * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 1.512 + * 1.513 + * @param source the input source to unmarshal XML data from 1.514 + * @return the newly created root object of the java content tree 1.515 + * 1.516 + * @throws JAXBException 1.517 + * If any unexpected errors occur while unmarshalling 1.518 + * @throws UnmarshalException 1.519 + * If the {@link ValidationEventHandler ValidationEventHandler} 1.520 + * returns false from its <tt>handleEvent</tt> method or the 1.521 + * <tt>Unmarshaller</tt> is unable to perform the XML to Java 1.522 + * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 1.523 + * @throws IllegalArgumentException 1.524 + * If the InputSource parameter is null 1.525 + */ 1.526 + public Object unmarshal( org.xml.sax.InputSource source ) throws JAXBException; 1.527 + 1.528 + /** 1.529 + * Unmarshal global XML data from the specified DOM tree and return the resulting 1.530 + * content tree. 1.531 + * 1.532 + * <p> 1.533 + * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 1.534 + * 1.535 + * @param node 1.536 + * the document/element to unmarshal XML data from. 1.537 + * The caller must support at least Document and Element. 1.538 + * @return the newly created root object of the java content tree 1.539 + * 1.540 + * @throws JAXBException 1.541 + * If any unexpected errors occur while unmarshalling 1.542 + * @throws UnmarshalException 1.543 + * If the {@link ValidationEventHandler ValidationEventHandler} 1.544 + * returns false from its <tt>handleEvent</tt> method or the 1.545 + * <tt>Unmarshaller</tt> is unable to perform the XML to Java 1.546 + * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 1.547 + * @throws IllegalArgumentException 1.548 + * If the Node parameter is null 1.549 + * @see #unmarshal(org.w3c.dom.Node, Class) 1.550 + */ 1.551 + public Object unmarshal( org.w3c.dom.Node node ) throws JAXBException; 1.552 + 1.553 + /** 1.554 + * Unmarshal XML data by JAXB mapped <tt>declaredType</tt> 1.555 + * and return the resulting content tree. 1.556 + * 1.557 + * <p> 1.558 + * Implements <a href="#unmarshalByDeclaredType">Unmarshal by Declared Type</a> 1.559 + * 1.560 + * @param node 1.561 + * the document/element to unmarshal XML data from. 1.562 + * The caller must support at least Document and Element. 1.563 + * @param declaredType 1.564 + * appropriate JAXB mapped class to hold <tt>node</tt>'s XML data. 1.565 + * 1.566 + * @return <a href="#unmarshalDeclaredTypeReturn">JAXB Element</a> representation of <tt>node</tt> 1.567 + * 1.568 + * @throws JAXBException 1.569 + * If any unexpected errors occur while unmarshalling 1.570 + * @throws UnmarshalException 1.571 + * If the {@link ValidationEventHandler ValidationEventHandler} 1.572 + * returns false from its <tt>handleEvent</tt> method or the 1.573 + * <tt>Unmarshaller</tt> is unable to perform the XML to Java 1.574 + * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 1.575 + * @throws IllegalArgumentException 1.576 + * If any parameter is null 1.577 + * @since JAXB2.0 1.578 + */ 1.579 + public <T> JAXBElement<T> unmarshal( org.w3c.dom.Node node, Class<T> declaredType ) throws JAXBException; 1.580 + 1.581 + /** 1.582 + * Unmarshal XML data from the specified XML Source and return the 1.583 + * resulting content tree. 1.584 + * 1.585 + * <p> 1.586 + * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 1.587 + * 1.588 + * <p> 1.589 + * <a name="saxParserPlugable"></a> 1.590 + * <b>SAX 2.0 Parser Pluggability</b> 1.591 + * <p> 1.592 + * A client application can choose not to use the default parser mechanism 1.593 + * supplied with their JAXB provider. Any SAX 2.0 compliant parser can be 1.594 + * substituted for the JAXB provider's default mechanism. To do so, the 1.595 + * client application must properly configure a <tt>SAXSource</tt> containing 1.596 + * an <tt>XMLReader</tt> implemented by the SAX 2.0 parser provider. If the 1.597 + * <tt>XMLReader</tt> has an <tt>org.xml.sax.ErrorHandler</tt> registered 1.598 + * on it, it will be replaced by the JAXB Provider so that validation errors 1.599 + * can be reported via the <tt>ValidationEventHandler</tt> mechanism of 1.600 + * JAXB. If the <tt>SAXSource</tt> does not contain an <tt>XMLReader</tt>, 1.601 + * then the JAXB provider's default parser mechanism will be used. 1.602 + * <p> 1.603 + * This parser replacement mechanism can also be used to replace the JAXB 1.604 + * provider's unmarshal-time validation engine. The client application 1.605 + * must properly configure their SAX 2.0 compliant parser to perform 1.606 + * validation (as shown in the example above). Any <tt>SAXParserExceptions 1.607 + * </tt> encountered by the parser during the unmarshal operation will be 1.608 + * processed by the JAXB provider and converted into JAXB 1.609 + * <tt>ValidationEvent</tt> objects which will be reported back to the 1.610 + * client via the <tt>ValidationEventHandler</tt> registered with the 1.611 + * <tt>Unmarshaller</tt>. <i>Note:</i> specifying a substitute validating 1.612 + * SAX 2.0 parser for unmarshalling does not necessarily replace the 1.613 + * validation engine used by the JAXB provider for performing on-demand 1.614 + * validation. 1.615 + * <p> 1.616 + * The only way for a client application to specify an alternate parser 1.617 + * mechanism to be used during unmarshal is via the 1.618 + * <tt>unmarshal(SAXSource)</tt> API. All other forms of the unmarshal 1.619 + * method (File, URL, Node, etc) will use the JAXB provider's default 1.620 + * parser and validator mechanisms. 1.621 + * 1.622 + * @param source the XML Source to unmarshal XML data from (providers are 1.623 + * only required to support SAXSource, DOMSource, and StreamSource) 1.624 + * @return the newly created root object of the java content tree 1.625 + * 1.626 + * @throws JAXBException 1.627 + * If any unexpected errors occur while unmarshalling 1.628 + * @throws UnmarshalException 1.629 + * If the {@link ValidationEventHandler ValidationEventHandler} 1.630 + * returns false from its <tt>handleEvent</tt> method or the 1.631 + * <tt>Unmarshaller</tt> is unable to perform the XML to Java 1.632 + * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 1.633 + * @throws IllegalArgumentException 1.634 + * If the Source parameter is null 1.635 + * @see #unmarshal(javax.xml.transform.Source, Class) 1.636 + */ 1.637 + public Object unmarshal( javax.xml.transform.Source source ) 1.638 + throws JAXBException; 1.639 + 1.640 + 1.641 + /** 1.642 + * Unmarshal XML data from the specified XML Source by <tt>declaredType</tt> and return the 1.643 + * resulting content tree. 1.644 + * 1.645 + * <p> 1.646 + * Implements <a href="#unmarshalByDeclaredType">Unmarshal by Declared Type</a> 1.647 + * 1.648 + * <p> 1.649 + * See <a href="#saxParserPlugable">SAX 2.0 Parser Pluggability</a> 1.650 + * 1.651 + * @param source the XML Source to unmarshal XML data from (providers are 1.652 + * only required to support SAXSource, DOMSource, and StreamSource) 1.653 + * @param declaredType 1.654 + * appropriate JAXB mapped class to hold <tt>source</tt>'s xml root element 1.655 + * @return Java content rooted by <a href="#unmarshalDeclaredTypeReturn">JAXB Element</a> 1.656 + * 1.657 + * @throws JAXBException 1.658 + * If any unexpected errors occur while unmarshalling 1.659 + * @throws UnmarshalException 1.660 + * If the {@link ValidationEventHandler ValidationEventHandler} 1.661 + * returns false from its <tt>handleEvent</tt> method or the 1.662 + * <tt>Unmarshaller</tt> is unable to perform the XML to Java 1.663 + * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 1.664 + * @throws IllegalArgumentException 1.665 + * If any parameter is null 1.666 + * @since JAXB2.0 1.667 + */ 1.668 + public <T> JAXBElement<T> unmarshal( javax.xml.transform.Source source, Class<T> declaredType ) 1.669 + throws JAXBException; 1.670 + 1.671 + /** 1.672 + * Unmarshal XML data from the specified pull parser and return the 1.673 + * resulting content tree. 1.674 + * 1.675 + * <p> 1.676 + * Implements <a href="#unmarshalGlobal">Unmarshal Global Root Element</a>. 1.677 + * 1.678 + * <p> 1.679 + * This method assumes that the parser is on a START_DOCUMENT or 1.680 + * START_ELEMENT event. Unmarshalling will be done from this 1.681 + * start event to the corresponding end event. If this method 1.682 + * returns successfully, the <tt>reader</tt> will be pointing at 1.683 + * the token right after the end event. 1.684 + * 1.685 + * @param reader 1.686 + * The parser to be read. 1.687 + * @return 1.688 + * the newly created root object of the java content tree. 1.689 + * 1.690 + * @throws JAXBException 1.691 + * If any unexpected errors occur while unmarshalling 1.692 + * @throws UnmarshalException 1.693 + * If the {@link ValidationEventHandler ValidationEventHandler} 1.694 + * returns false from its <tt>handleEvent</tt> method or the 1.695 + * <tt>Unmarshaller</tt> is unable to perform the XML to Java 1.696 + * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 1.697 + * @throws IllegalArgumentException 1.698 + * If the <tt>reader</tt> parameter is null 1.699 + * @throws IllegalStateException 1.700 + * If <tt>reader</tt> is not pointing to a START_DOCUMENT or 1.701 + * START_ELEMENT event. 1.702 + * @since JAXB2.0 1.703 + * @see #unmarshal(javax.xml.stream.XMLStreamReader, Class) 1.704 + */ 1.705 + public Object unmarshal( javax.xml.stream.XMLStreamReader reader ) 1.706 + throws JAXBException; 1.707 + 1.708 + /** 1.709 + * Unmarshal root element to JAXB mapped <tt>declaredType</tt> 1.710 + * and return the resulting content tree. 1.711 + * 1.712 + * <p> 1.713 + * This method implements <a href="#unmarshalByDeclaredType">unmarshal by declaredType</a>. 1.714 + * <p> 1.715 + * This method assumes that the parser is on a START_DOCUMENT or 1.716 + * START_ELEMENT event. Unmarshalling will be done from this 1.717 + * start event to the corresponding end event. If this method 1.718 + * returns successfully, the <tt>reader</tt> will be pointing at 1.719 + * the token right after the end event. 1.720 + * 1.721 + * @param reader 1.722 + * The parser to be read. 1.723 + * @param declaredType 1.724 + * appropriate JAXB mapped class to hold <tt>reader</tt>'s START_ELEMENT XML data. 1.725 + * 1.726 + * @return content tree rooted by <a href="#unmarshalDeclaredTypeReturn">JAXB Element representation</a> 1.727 + * 1.728 + * @throws JAXBException 1.729 + * If any unexpected errors occur while unmarshalling 1.730 + * @throws UnmarshalException 1.731 + * If the {@link ValidationEventHandler ValidationEventHandler} 1.732 + * returns false from its <tt>handleEvent</tt> method or the 1.733 + * <tt>Unmarshaller</tt> is unable to perform the XML to Java 1.734 + * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 1.735 + * @throws IllegalArgumentException 1.736 + * If any parameter is null 1.737 + * @since JAXB2.0 1.738 + */ 1.739 + public <T> JAXBElement<T> unmarshal( javax.xml.stream.XMLStreamReader reader, Class<T> declaredType ) throws JAXBException; 1.740 + 1.741 + /** 1.742 + * Unmarshal XML data from the specified pull parser and return the 1.743 + * resulting content tree. 1.744 + * 1.745 + * <p> 1.746 + * This method is an <a href="#unmarshalGlobal">Unmarshal Global Root method</a>. 1.747 + * 1.748 + * <p> 1.749 + * This method assumes that the parser is on a START_DOCUMENT or 1.750 + * START_ELEMENT event. Unmarshalling will be done from this 1.751 + * start event to the corresponding end event. If this method 1.752 + * returns successfully, the <tt>reader</tt> will be pointing at 1.753 + * the token right after the end event. 1.754 + * 1.755 + * @param reader 1.756 + * The parser to be read. 1.757 + * @return 1.758 + * the newly created root object of the java content tree. 1.759 + * 1.760 + * @throws JAXBException 1.761 + * If any unexpected errors occur while unmarshalling 1.762 + * @throws UnmarshalException 1.763 + * If the {@link ValidationEventHandler ValidationEventHandler} 1.764 + * returns false from its <tt>handleEvent</tt> method or the 1.765 + * <tt>Unmarshaller</tt> is unable to perform the XML to Java 1.766 + * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 1.767 + * @throws IllegalArgumentException 1.768 + * If the <tt>reader</tt> parameter is null 1.769 + * @throws IllegalStateException 1.770 + * If <tt>reader</tt> is not pointing to a START_DOCUMENT or 1.771 + * START_ELEMENT event. 1.772 + * @since JAXB2.0 1.773 + * @see #unmarshal(javax.xml.stream.XMLEventReader, Class) 1.774 + */ 1.775 + public Object unmarshal( javax.xml.stream.XMLEventReader reader ) 1.776 + throws JAXBException; 1.777 + 1.778 + /** 1.779 + * Unmarshal root element to JAXB mapped <tt>declaredType</tt> 1.780 + * and return the resulting content tree. 1.781 + * 1.782 + * <p> 1.783 + * This method implements <a href="#unmarshalByDeclaredType">unmarshal by declaredType</a>. 1.784 + * 1.785 + * <p> 1.786 + * This method assumes that the parser is on a START_DOCUMENT or 1.787 + * START_ELEMENT event. Unmarshalling will be done from this 1.788 + * start event to the corresponding end event. If this method 1.789 + * returns successfully, the <tt>reader</tt> will be pointing at 1.790 + * the token right after the end event. 1.791 + * 1.792 + * @param reader 1.793 + * The parser to be read. 1.794 + * @param declaredType 1.795 + * appropriate JAXB mapped class to hold <tt>reader</tt>'s START_ELEMENT XML data. 1.796 + * 1.797 + * @return content tree rooted by <a href="#unmarshalDeclaredTypeReturn">JAXB Element representation</a> 1.798 + * 1.799 + * @throws JAXBException 1.800 + * If any unexpected errors occur while unmarshalling 1.801 + * @throws UnmarshalException 1.802 + * If the {@link ValidationEventHandler ValidationEventHandler} 1.803 + * returns false from its <tt>handleEvent</tt> method or the 1.804 + * <tt>Unmarshaller</tt> is unable to perform the XML to Java 1.805 + * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 1.806 + * @throws IllegalArgumentException 1.807 + * If any parameter is null 1.808 + * @since JAXB2.0 1.809 + */ 1.810 + public <T> JAXBElement<T> unmarshal( javax.xml.stream.XMLEventReader reader, Class<T> declaredType ) throws JAXBException; 1.811 + 1.812 + /** 1.813 + * Get an unmarshaller handler object that can be used as a component in 1.814 + * an XML pipeline. 1.815 + * 1.816 + * <p> 1.817 + * The JAXB Provider can return the same handler object for multiple 1.818 + * invocations of this method. In other words, this method does not 1.819 + * necessarily create a new instance of <tt>UnmarshallerHandler</tt>. If the 1.820 + * application needs to use more than one <tt>UnmarshallerHandler</tt>, it 1.821 + * should create more than one <tt>Unmarshaller</tt>. 1.822 + * 1.823 + * @return the unmarshaller handler object 1.824 + * @see UnmarshallerHandler 1.825 + */ 1.826 + public UnmarshallerHandler getUnmarshallerHandler(); 1.827 + 1.828 + /** 1.829 + * Specifies whether or not the default validation mechanism of the 1.830 + * <tt>Unmarshaller</tt> should validate during unmarshal operations. 1.831 + * By default, the <tt>Unmarshaller</tt> does not validate. 1.832 + * <p> 1.833 + * This method may only be invoked before or after calling one of the 1.834 + * unmarshal methods. 1.835 + * <p> 1.836 + * This method only controls the JAXB Provider's default unmarshal-time 1.837 + * validation mechanism - it has no impact on clients that specify their 1.838 + * own validating SAX 2.0 compliant parser. Clients that specify their 1.839 + * own unmarshal-time validation mechanism may wish to turn off the JAXB 1.840 + * Provider's default validation mechanism via this API to avoid "double 1.841 + * validation". 1.842 + * <p> 1.843 + * This method is deprecated as of JAXB 2.0 - please use the new 1.844 + * {@link #setSchema(javax.xml.validation.Schema)} API. 1.845 + * 1.846 + * @param validating true if the Unmarshaller should validate during 1.847 + * unmarshal, false otherwise 1.848 + * @throws JAXBException if an error occurred while enabling or disabling 1.849 + * validation at unmarshal time 1.850 + * @throws UnsupportedOperationException could be thrown if this method is 1.851 + * invoked on an Unmarshaller created from a JAXBContext referencing 1.852 + * JAXB 2.0 mapped classes 1.853 + * @deprecated since JAXB2.0, please see {@link #setSchema(javax.xml.validation.Schema)} 1.854 + */ 1.855 + public void setValidating( boolean validating ) 1.856 + throws JAXBException; 1.857 + 1.858 + /** 1.859 + * Indicates whether or not the <tt>Unmarshaller</tt> is configured to 1.860 + * validate during unmarshal operations. 1.861 + * <p> 1.862 + * This API returns the state of the JAXB Provider's default unmarshal-time 1.863 + * validation mechanism. 1.864 + * <p> 1.865 + * This method is deprecated as of JAXB 2.0 - please use the new 1.866 + * {@link #getSchema()} API. 1.867 + * 1.868 + * @return true if the Unmarshaller is configured to validate during 1.869 + * unmarshal operations, false otherwise 1.870 + * @throws JAXBException if an error occurs while retrieving the validating 1.871 + * flag 1.872 + * @throws UnsupportedOperationException could be thrown if this method is 1.873 + * invoked on an Unmarshaller created from a JAXBContext referencing 1.874 + * JAXB 2.0 mapped classes 1.875 + * @deprecated since JAXB2.0, please see {@link #getSchema()} 1.876 + */ 1.877 + public boolean isValidating() 1.878 + throws JAXBException; 1.879 + 1.880 + /** 1.881 + * Allow an application to register a <tt>ValidationEventHandler</tt>. 1.882 + * <p> 1.883 + * The <tt>ValidationEventHandler</tt> will be called by the JAXB Provider 1.884 + * if any validation errors are encountered during calls to any of the 1.885 + * unmarshal methods. If the client application does not register a 1.886 + * <tt>ValidationEventHandler</tt> before invoking the unmarshal methods, 1.887 + * then <tt>ValidationEvents</tt> will be handled by the default event 1.888 + * handler which will terminate the unmarshal operation after the first 1.889 + * error or fatal error is encountered. 1.890 + * <p> 1.891 + * Calling this method with a null parameter will cause the Unmarshaller 1.892 + * to revert back to the default event handler. 1.893 + * 1.894 + * @param handler the validation event handler 1.895 + * @throws JAXBException if an error was encountered while setting the 1.896 + * event handler 1.897 + */ 1.898 + public void setEventHandler( ValidationEventHandler handler ) 1.899 + throws JAXBException; 1.900 + 1.901 + /** 1.902 + * Return the current event handler or the default event handler if one 1.903 + * hasn't been set. 1.904 + * 1.905 + * @return the current ValidationEventHandler or the default event handler 1.906 + * if it hasn't been set 1.907 + * @throws JAXBException if an error was encountered while getting the 1.908 + * current event handler 1.909 + */ 1.910 + public ValidationEventHandler getEventHandler() 1.911 + throws JAXBException; 1.912 + 1.913 + /** 1.914 + * Set the particular property in the underlying implementation of 1.915 + * <tt>Unmarshaller</tt>. This method can only be used to set one of 1.916 + * the standard JAXB defined properties above or a provider specific 1.917 + * property. Attempting to set an undefined property will result in 1.918 + * a PropertyException being thrown. See <a href="#supportedProps"> 1.919 + * Supported Properties</a>. 1.920 + * 1.921 + * @param name the name of the property to be set. This value can either 1.922 + * be specified using one of the constant fields or a user 1.923 + * supplied string. 1.924 + * @param value the value of the property to be set 1.925 + * 1.926 + * @throws PropertyException when there is an error processing the given 1.927 + * property or value 1.928 + * @throws IllegalArgumentException 1.929 + * If the name parameter is null 1.930 + */ 1.931 + public void setProperty( String name, Object value ) 1.932 + throws PropertyException; 1.933 + 1.934 + /** 1.935 + * Get the particular property in the underlying implementation of 1.936 + * <tt>Unmarshaller</tt>. This method can only be used to get one of 1.937 + * the standard JAXB defined properties above or a provider specific 1.938 + * property. Attempting to get an undefined property will result in 1.939 + * a PropertyException being thrown. See <a href="#supportedProps"> 1.940 + * Supported Properties</a>. 1.941 + * 1.942 + * @param name the name of the property to retrieve 1.943 + * @return the value of the requested property 1.944 + * 1.945 + * @throws PropertyException 1.946 + * when there is an error retrieving the given property or value 1.947 + * property name 1.948 + * @throws IllegalArgumentException 1.949 + * If the name parameter is null 1.950 + */ 1.951 + public Object getProperty( String name ) throws PropertyException; 1.952 + 1.953 + /** 1.954 + * Specify the JAXP 1.3 {@link javax.xml.validation.Schema Schema} 1.955 + * object that should be used to validate subsequent unmarshal operations 1.956 + * against. Passing null into this method will disable validation. 1.957 + * <p> 1.958 + * This method replaces the deprecated {@link #setValidating(boolean) setValidating(boolean)} 1.959 + * API. 1.960 + * 1.961 + * <p> 1.962 + * Initially this property is set to <tt>null</tt>. 1.963 + * 1.964 + * @param schema Schema object to validate unmarshal operations against or null to disable validation 1.965 + * @throws UnsupportedOperationException could be thrown if this method is 1.966 + * invoked on an Unmarshaller created from a JAXBContext referencing 1.967 + * JAXB 1.0 mapped classes 1.968 + * @since JAXB2.0 1.969 + */ 1.970 + public void setSchema( javax.xml.validation.Schema schema ); 1.971 + 1.972 + /** 1.973 + * Get the JAXP 1.3 {@link javax.xml.validation.Schema Schema} object 1.974 + * being used to perform unmarshal-time validation. If there is no 1.975 + * Schema set on the unmarshaller, then this method will return null 1.976 + * indicating that unmarshal-time validation will not be performed. 1.977 + * <p> 1.978 + * This method provides replacement functionality for the deprecated 1.979 + * {@link #isValidating()} API as well as access to the Schema object. 1.980 + * To determine if the Unmarshaller has validation enabled, simply 1.981 + * test the return type for null: 1.982 + * <p> 1.983 + * <code> 1.984 + * boolean isValidating = u.getSchema()!=null; 1.985 + * </code> 1.986 + * 1.987 + * @return the Schema object being used to perform unmarshal-time 1.988 + * validation or null if not present 1.989 + * @throws UnsupportedOperationException could be thrown if this method is 1.990 + * invoked on an Unmarshaller created from a JAXBContext referencing 1.991 + * JAXB 1.0 mapped classes 1.992 + * @since JAXB2.0 1.993 + */ 1.994 + public javax.xml.validation.Schema getSchema(); 1.995 + 1.996 + /** 1.997 + * Associates a configured instance of {@link XmlAdapter} with this unmarshaller. 1.998 + * 1.999 + * <p> 1.1000 + * This is a convenience method that invokes <code>setAdapter(adapter.getClass(),adapter);</code>. 1.1001 + * 1.1002 + * @see #setAdapter(Class,XmlAdapter) 1.1003 + * @throws IllegalArgumentException 1.1004 + * if the adapter parameter is null. 1.1005 + * @throws UnsupportedOperationException 1.1006 + * if invoked agains a JAXB 1.0 implementation. 1.1007 + * @since JAXB2.0 1.1008 + */ 1.1009 + public void setAdapter( XmlAdapter adapter ); 1.1010 + 1.1011 + /** 1.1012 + * Associates a configured instance of {@link XmlAdapter} with this unmarshaller. 1.1013 + * 1.1014 + * <p> 1.1015 + * Every unmarshaller internally maintains a 1.1016 + * {@link java.util.Map}<{@link Class},{@link XmlAdapter}>, 1.1017 + * which it uses for unmarshalling classes whose fields/methods are annotated 1.1018 + * with {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter}. 1.1019 + * 1.1020 + * <p> 1.1021 + * This method allows applications to use a configured instance of {@link XmlAdapter}. 1.1022 + * When an instance of an adapter is not given, an unmarshaller will create 1.1023 + * one by invoking its default constructor. 1.1024 + * 1.1025 + * @param type 1.1026 + * The type of the adapter. The specified instance will be used when 1.1027 + * {@link javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter#value()} 1.1028 + * refers to this type. 1.1029 + * @param adapter 1.1030 + * The instance of the adapter to be used. If null, it will un-register 1.1031 + * the current adapter set for this type. 1.1032 + * @throws IllegalArgumentException 1.1033 + * if the type parameter is null. 1.1034 + * @throws UnsupportedOperationException 1.1035 + * if invoked agains a JAXB 1.0 implementation. 1.1036 + * @since JAXB2.0 1.1037 + */ 1.1038 + public <A extends XmlAdapter> void setAdapter( Class<A> type, A adapter ); 1.1039 + 1.1040 + /** 1.1041 + * Gets the adapter associated with the specified type. 1.1042 + * 1.1043 + * This is the reverse operation of the {@link #setAdapter} method. 1.1044 + * 1.1045 + * @throws IllegalArgumentException 1.1046 + * if the type parameter is null. 1.1047 + * @throws UnsupportedOperationException 1.1048 + * if invoked agains a JAXB 1.0 implementation. 1.1049 + * @since JAXB2.0 1.1050 + */ 1.1051 + public <A extends XmlAdapter> A getAdapter( Class<A> type ); 1.1052 + 1.1053 + /** 1.1054 + * <p>Associate a context that resolves cid's, content-id URIs, to 1.1055 + * binary data passed as attachments.</p> 1.1056 + * <p/> 1.1057 + * <p>Unmarshal time validation, enabled via {@link #setSchema(Schema)}, 1.1058 + * must be supported even when unmarshaller is performing XOP processing. 1.1059 + * </p> 1.1060 + * 1.1061 + * @throws IllegalStateException if attempt to concurrently call this 1.1062 + * method during a unmarshal operation. 1.1063 + */ 1.1064 + void setAttachmentUnmarshaller(AttachmentUnmarshaller au); 1.1065 + 1.1066 + AttachmentUnmarshaller getAttachmentUnmarshaller(); 1.1067 + 1.1068 + /** 1.1069 + * <p/> 1.1070 + * Register an instance of an implementation of this class with {@link Unmarshaller} to externally listen 1.1071 + * for unmarshal events. 1.1072 + * <p/> 1.1073 + * <p/> 1.1074 + * This class enables pre and post processing of an instance of a JAXB mapped class 1.1075 + * as XML data is unmarshalled into it. The event callbacks are called when unmarshalling 1.1076 + * XML content into a JAXBElement instance or a JAXB mapped class that represents a complex type definition. 1.1077 + * The event callbacks are not called when unmarshalling to an instance of a 1.1078 + * Java datatype that represents a simple type definition. 1.1079 + * <p/> 1.1080 + * <p/> 1.1081 + * External listener is one of two different mechanisms for defining unmarshal event callbacks. 1.1082 + * See <a href="Unmarshaller.html#unmarshalEventCallback">Unmarshal Event Callbacks</a> for an overview. 1.1083 + * <p/> 1.1084 + * (@link #setListener(Listener)} 1.1085 + * (@link #getListener()} 1.1086 + * 1.1087 + * @since JAXB2.0 1.1088 + */ 1.1089 + public static abstract class Listener { 1.1090 + /** 1.1091 + * <p/> 1.1092 + * Callback method invoked before unmarshalling into <tt>target</tt>. 1.1093 + * <p/> 1.1094 + * <p/> 1.1095 + * This method is invoked immediately after <tt>target</tt> was created and 1.1096 + * before the unmarshalling of this object begins. Note that 1.1097 + * if the class of <tt>target</tt> defines its own <tt>beforeUnmarshal</tt> method, 1.1098 + * the class specific callback method is invoked before this method is invoked. 1.1099 + * 1.1100 + * @param target non-null instance of JAXB mapped class prior to unmarshalling into it. 1.1101 + * @param parent instance of JAXB mapped class that will eventually reference <tt>target</tt>. 1.1102 + * <tt>null</tt> when <tt>target</tt> is root element. 1.1103 + */ 1.1104 + public void beforeUnmarshal(Object target, Object parent) { 1.1105 + } 1.1106 + 1.1107 + /** 1.1108 + * <p/> 1.1109 + * Callback method invoked after unmarshalling XML data into <tt>target</tt>. 1.1110 + * <p/> 1.1111 + * <p/> 1.1112 + * This method is invoked after all the properties (except IDREF) are unmarshalled into <tt>target</tt>, 1.1113 + * but before <tt>target</tt> is set into its <tt>parent</tt> object. 1.1114 + * Note that if the class of <tt>target</tt> defines its own <tt>afterUnmarshal</tt> method, 1.1115 + * the class specific callback method is invoked before this method is invoked. 1.1116 + * 1.1117 + * @param target non-null instance of JAXB mapped class prior to unmarshalling into it. 1.1118 + * @param parent instance of JAXB mapped class that will reference <tt>target</tt>. 1.1119 + * <tt>null</tt> when <tt>target</tt> is root element. 1.1120 + */ 1.1121 + public void afterUnmarshal(Object target, Object parent) { 1.1122 + } 1.1123 + } 1.1124 + 1.1125 + /** 1.1126 + * <p> 1.1127 + * Register unmarshal event callback {@link Listener} with this {@link Unmarshaller}. 1.1128 + * 1.1129 + * <p> 1.1130 + * There is only one Listener per Unmarshaller. Setting a Listener replaces the previous set Listener. 1.1131 + * One can unregister current Listener by setting listener to <tt>null</tt>. 1.1132 + * 1.1133 + * @param listener provides unmarshal event callbacks for this {@link Unmarshaller} 1.1134 + * @since JAXB2.0 1.1135 + */ 1.1136 + public void setListener(Listener listener); 1.1137 + 1.1138 + /** 1.1139 + * <p>Return {@link Listener} registered with this {@link Unmarshaller}. 1.1140 + * 1.1141 + * @return registered {@link Listener} or <code>null</code> if no Listener is registered with this Unmarshaller. 1.1142 + * @since JAXB2.0 1.1143 + */ 1.1144 + public Listener getListener(); 1.1145 +}