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