001 /* 002 * $Id: Unmarshaller.java,v 1.28 2003/02/28 21:44:24 ryans Exp $ 003 * 004 * Copyright 2001 Sun Microsystems, Inc. All Rights Reserved. 005 * 006 * This software is the proprietary information of Sun Microsystems, Inc. 007 * Use is subject to license terms. 008 * 009 */ 010 011 package javax.xml.bind; 012 013 /** 014 * The <tt>Unmarshaller</tt> class governs the process of deserializing XML 015 * data into newly created Java content trees, optionally validating the XML 016 * data as it is unmarshalled. It provides the basic unmarshalling methods: 017 * 018 * <p> 019 * Unmarshalling from a File: 020 * <blockquote> 021 * <pre> 022 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 023 * Unmarshaller u = jc.createUnmarshaller(); 024 * Object o = u.unmarshal( new File( "nosferatu.xml" ) ); 025 * </pre> 026 * </blockquote> 027 * 028 * 029 * <p> 030 * Unmarshalling from an InputStream: 031 * <blockquote> 032 * <pre> 033 * InputStream is = new FileInputStream( "nosferatu.xml" ); 034 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 035 * Unmarshaller u = jc.createUnmarshaller(); 036 * Object o = u.unmarshal( is ); 037 * </pre> 038 * </blockquote> 039 * 040 * <p> 041 * Unmarshalling from a URL: 042 * <blockquote> 043 * <pre> 044 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 045 * Unmarshaller u = jc.createUnmarshaller(); 046 * URL url = new URL( "http://beaker.east/nosferatu.xml" ); 047 * Object o = u.unmarshal( url ); 048 * </pre> 049 * </blockquote> 050 * 051 * <p> 052 * Unmarshalling from a StringBuffer using a 053 * <tt>javax.xml.transform.stream.StreamSource</tt>: 054 * <blockquote> 055 * <pre> 056 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 057 * Unmarshaller u = jc.createUnmarshaller(); 058 * StringBuffer xmlStr = new StringBuffer( "<?xml version="1.0"?>..." ); 059 * Object o = u.unmarshal( new StreamSource( new StringReader( xmlStr.toString() ) ) ); 060 * </pre> 061 * </blockquote> 062 * 063 * <p> 064 * Unmarshalling from a <tt>org.w3c.dom.Node</tt>: 065 * <blockquote> 066 * <pre> 067 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 068 * Unmarshaller u = jc.createUnmarshaller(); 069 * 070 * DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); 071 * dbf.setNamespaceAware(true); 072 * DocumentBuilder db = dbf.newDocumentBuilder(); 073 * Document doc = db.parse(new File( "nosferatu.xml")); 074 075 * Object o = u.unmarshal( doc ); 076 * </pre> 077 * </blockquote> 078 * 079 * <p> 080 * Unmarshalling from a <tt>javax.xml.transform.sax.SAXSource</tt> using a 081 * client specified validating SAX2.0 parser: 082 * <blockquote> 083 * <pre> 084 * // configure a validating SAX2.0 parser (Xerces2) 085 * static final String JAXP_SCHEMA_LANGUAGE = 086 * "http://java.sun.com/xml/jaxp/properties/schemaLanguage"; 087 * static final String JAXP_SCHEMA_LOCATION = 088 * "http://java.sun.com/xml/jaxp/properties/schemaSource"; 089 * static final String W3C_XML_SCHEMA = 090 * "http://www.w3.org/2001/XMLSchema"; 091 * 092 * System.setProperty( "javax.xml.parsers.SAXParserFactory", 093 * "org.apache.xerces.jaxp.SAXParserFactoryImpl" ); 094 * 095 * SAXParserFactory spf = SAXParserFactory.newInstance(); 096 * spf.setNamespaceAware(true); 097 * spf.setValidating(true); 098 * SAXParser saxParser = spf.newSAXParser(); 099 * 100 * try { 101 * saxParser.setProperty(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA); 102 * saxParser.setProperty(JAXP_SCHEMA_LOCATION, "http://...."); 103 * } catch (SAXNotRecognizedException x) { 104 * // exception handling omitted 105 * } 106 * 107 * XMLReader xmlReader = saxParser.getXMLReader(); 108 * SAXSource source = 109 * new SAXSource( xmlReader, new InputSource( "http://..." ) ); 110 * 111 * // Setup JAXB to unmarshal 112 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 113 * Unmarshaller u = jc.createUnmarshaller(); 114 * ValidationEventCollector vec = new ValidationEventCollector(); 115 * u.setEventHandler( vec ); 116 * 117 * // turn off the JAXB provider's default validation mechanism to 118 * // avoid duplicate validation 119 * u.setValidating( false ) 120 * 121 * // unmarshal 122 * Object o = u.unmarshal( source ); 123 * 124 * // check for events 125 * if( vec.hasEvents() ) { 126 * // iterate over events 127 * } 128 * </pre> 129 * </blockquote> 130 * 131 * <p> 132 * <a name="unmarshalEx"></a> 133 * <b>Unmarshalling XML Data</b><br> 134 * <blockquote> 135 * The <tt>JAXBContext</tt> object used to create this <tt>Unmarshaller</tt> 136 * was initialized with a <tt>contextPath</tt> which determines the schema 137 * derived content available to the <tt>Marshaller</tt>, <tt>Unmarshaller</tt>, 138 * and <tt>Validator</tt> objects it produces. If the <tt>JAXBContext</tt> 139 * object that was used to create this <tt>Unmarshaller</tt> does not have 140 * enough information to know how to unmarshal the XML content from the 141 * specified source, then the unmarshal operation will abort immediately by 142 * throwing a {@link UnmarshalException UnmarshalException}. 143 * </blockquote> 144 * 145 * <p> 146 * <b>Support for SAX2.0 Compliant Parsers</b><br> 147 * <blockquote> 148 * A client application has the ability to select the SAX2.0 compliant parser 149 * of their choice. If a SAX parser is not selected, then the JAXB Provider's 150 * default parser will be used. Eventhough the JAXB Provider's default parser 151 * is not required to be SAX2.0 compliant, all providers are required to allow 152 * a client application to specify their own SAX2.0 parser. Some providers may 153 * require the client application to specify the SAX2.0 parser at schema compile 154 * time. See {@link #unmarshal(javax.xml.transform.Source) unmarshal(Source)} 155 * for more detail. 156 * </blockquote> 157 * 158 * <p> 159 * <b>Validation and Well-Formedness</b><br> 160 * <blockquote> 161 * <p> 162 * A client application can enable or disable the provider's default validation 163 * mechanism via the <tt>setValidating</tt> API. Sophisticated clients can 164 * specify their own validating SAX 2.0 compliant parser and bypass the 165 * provider's default validation mechanism using the 166 * {@link #unmarshal(javax.xml.transform.Source) unmarshal(Source)} API. 167 * 168 * <p> 169 * For a more detailed definition of how validation errors and warnings are 170 * handled, see the {@link Validator Validator} javadoc. 171 * </blockquote> 172 * 173 * <p> 174 * <a name="supportedProps"></a> 175 * <b>Supported Properties</b><br> 176 * <blockquote> 177 * <p> 178 * There currently are not any properties required to be supported by all 179 * JAXB Providers on Unmarshaller. However, some providers may support 180 * their own set of provider specific properties. 181 * </blockquote> 182 * 183 * 184 * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul> 185 * @version $Revision: 1.28 $ $Date: 2003/02/28 21:44:24 $ 186 * @see JAXBContext 187 * @see Marshaller 188 * @see Validator 189 * @since JAXB1.0 190 */ 191 public interface Unmarshaller { 192 193 /** 194 * Unmarshal XML data from the specified file and return the resulting 195 * content tree. 196 * 197 * @param f the file to unmarshal XML data from 198 * @return the newly created root object of the java content tree 199 * 200 * @throws JAXBException 201 * If any unexpected errors occur while unmarshalling 202 * @throws UnmarshalException 203 * If the {@link ValidationEventHandler ValidationEventHandler} 204 * returns false from its <tt>handleEvent</tt> method or the 205 * <tt>Unmarshaller</tt> is unable to perform the XML to Java 206 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 207 * @throws IllegalArgumentException 208 * If the file parameter is null 209 */ 210 public Object unmarshal( java.io.File f ) throws JAXBException; 211 212 /** 213 * Unmarshal XML data from the specified InputStream and return the 214 * resulting content tree. Validation event location information may 215 * be incomplete when using this form of the unmarshal API. 216 * 217 * @param is the InputStream to unmarshal XML data from 218 * @return the newly created root object of the java content tree 219 * 220 * @throws JAXBException 221 * If any unexpected errors occur while unmarshalling 222 * @throws UnmarshalException 223 * If the {@link ValidationEventHandler ValidationEventHandler} 224 * returns false from its <tt>handleEvent</tt> method or the 225 * <tt>Unmarshaller</tt> is unable to perform the XML to Java 226 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 227 * @throws IllegalArgumentException 228 * If the InputStream parameter is null 229 */ 230 public Object unmarshal( java.io.InputStream is ) throws JAXBException; 231 232 /** 233 * Unmarshal XML data from the specified URL and return the resulting 234 * content tree. 235 * 236 * @param url the url to unmarshal XML data from 237 * @return the newly created root object of the java content tree 238 * 239 * @throws JAXBException 240 * If any unexpected errors occur while unmarshalling 241 * @throws UnmarshalException 242 * If the {@link ValidationEventHandler ValidationEventHandler} 243 * returns false from its <tt>handleEvent</tt> method or the 244 * <tt>Unmarshaller</tt> is unable to perform the XML to Java 245 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 246 * @throws IllegalArgumentException 247 * If the URL parameter is null 248 */ 249 public Object unmarshal( java.net.URL url ) throws JAXBException; 250 251 /** 252 * Unmarshal XML data from the specified SAX InputSource and return the 253 * resulting content tree. 254 * 255 * @param source the input source to unmarshal XML data from 256 * @return the newly created root object of the java content tree 257 * 258 * @throws JAXBException 259 * If any unexpected errors occur while unmarshalling 260 * @throws UnmarshalException 261 * If the {@link ValidationEventHandler ValidationEventHandler} 262 * returns false from its <tt>handleEvent</tt> method or the 263 * <tt>Unmarshaller</tt> is unable to perform the XML to Java 264 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 265 * @throws IllegalArgumentException 266 * If the InputSource parameter is null 267 */ 268 public Object unmarshal( org.xml.sax.InputSource source ) throws JAXBException; 269 270 /** 271 * Unmarshal XML data from the specified DOM tree and return the resulting 272 * content tree. 273 * 274 * @param node 275 * the document/element to unmarshal XML data from. 276 * The caller must support at least Document and Element. 277 * @return the newly created root object of the java content tree 278 * 279 * @throws JAXBException 280 * If any unexpected errors occur while unmarshalling 281 * @throws UnmarshalException 282 * If the {@link ValidationEventHandler ValidationEventHandler} 283 * returns false from its <tt>handleEvent</tt> method or the 284 * <tt>Unmarshaller</tt> is unable to perform the XML to Java 285 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 286 * @throws IllegalArgumentException 287 * If the Node parameter is null 288 */ 289 public Object unmarshal( org.w3c.dom.Node node ) throws JAXBException; 290 291 /** 292 * Unmarshal XML data from the specified XML Source and return the 293 * resulting content tree. 294 * <p> 295 * <b>SAX 2.0 Parser Pluggability</b> 296 * <p> 297 * A client application can choose not to use the default parser mechanism 298 * supplied with their JAXB provider. Any SAX 2.0 compliant parser can be 299 * substituted for the JAXB provider's default mechanism. To do so, the 300 * client application must properly configure a <tt>SAXSource</tt> containing 301 * an <tt>XMLReader</tt> implemented by the SAX 2.0 parser provider. If the 302 * <tt>XMLReader</tt> has an <tt>org.xml.sax.ErrorHandler</tt> registered 303 * on it, it will be replaced by the JAXB Provider so that validation errors 304 * can be reported via the <tt>ValidationEventHandler</tt> mechanism of 305 * JAXB. If the <tt>SAXSource</tt> does not contain an <tt>XMLReader</tt>, 306 * then the JAXB provider's default parser mechanism will be used. 307 * <p> 308 * This parser replacement mechanism can also be used to replace the JAXB 309 * provider's unmarshal-time validation engine. The client application 310 * must properly configure their SAX 2.0 compliant parser to perform 311 * validation (as shown in the example above). Any <tt>SAXParserExceptions 312 * </tt> encountered by the parser during the unmarshal operation will be 313 * processed by the JAXB provider and converted into JAXB 314 * <tt>ValidationEvent</tt> objects which will be reported back to the 315 * client via the <tt>ValidationEventHandler</tt> registered with the 316 * <tt>Unmarshaller</tt>. <i>Note:</i> specifying a substitute validating 317 * SAX 2.0 parser for unmarshalling does not necessarily replace the 318 * validation engine used by the JAXB provider for performing on-demand 319 * validation. 320 * <p> 321 * The only way for a client application to specify an alternate parser 322 * mechanism to be used during unmarshal is via the 323 * <tt>unmarshal(SAXSource)</tt> API. All other forms of the unmarshal 324 * method (File, URL, Node, etc) will use the JAXB provider's default 325 * parser and validator mechanisms. 326 * 327 * @param source the XML Source to unmarshal XML data from (providers are 328 * only required to support SAXSource, DOMSource, and StreamSource) 329 * @return the newly created root object of the java content tree 330 * 331 * @throws JAXBException 332 * If any unexpected errors occur while unmarshalling 333 * @throws UnmarshalException 334 * If the {@link ValidationEventHandler ValidationEventHandler} 335 * returns false from its <tt>handleEvent</tt> method or the 336 * <tt>Unmarshaller</tt> is unable to perform the XML to Java 337 * binding. See <a href="#unmarshalEx">Unmarshalling XML Data</a> 338 * @throws IllegalArgumentException 339 * If the Source parameter is null 340 */ 341 public Object unmarshal( javax.xml.transform.Source source ) 342 throws JAXBException; 343 344 /** 345 * Get an unmarshaller handler object that can be used as a component in 346 * an XML pipeline. 347 * 348 * <p> 349 * The JAXB Provider can return the same handler object for multiple 350 * invocations of this method. In other words, this method does not 351 * necessarily create a new instance of <tt>UnmarshallerHandler</tt>. If the 352 * application needs to use more than one <tt>UnmarshallerHandler</tt>, it 353 * should create more than one <tt>Unmarshaller</tt>. 354 * 355 * @return the unmarshaller handler object 356 * @see UnmarshallerHandler 357 */ 358 public UnmarshallerHandler getUnmarshallerHandler(); 359 360 /** 361 * Specifies whether or not the default validation mechanism of the 362 * <tt>Unmarshaller</tt> should validate during unmarshal operations. 363 * By default, the <tt>Unmarshaller</tt> does not validate. 364 * <p> 365 * This method may only be invoked before or after calling one of the 366 * unmarshal methods. 367 * <p> 368 * This method only controls the JAXB Provider's default unmarshal-time 369 * validation mechanism - it has no impact on clients that specify their 370 * own validating SAX 2.0 compliant parser. Clients that specify their 371 * own unmarshal-time validation mechanism may wish to turn off the JAXB 372 * Provider's default validation mechanism via this API to avoid "double 373 * validation". 374 * 375 * @param validating true if the Unmarshaller should validate during 376 * unmarshal, false otherwise 377 * @throws JAXBException if an error occurred while enabling or disabling 378 validation at unmarshal time 379 */ 380 public void setValidating( boolean validating ) 381 throws JAXBException; 382 383 /** 384 * Indicates whether or not the <tt>Unmarshaller</tt> is configured to 385 * validate during unmarshal operations. 386 * 387 * <p> 388 * This API returns the state of the JAXB Provider's default unmarshal-time 389 * validation mechanism. 390 * 391 * @return true if the Unmarshaller is configured to validate during 392 * unmarshal operations, false otherwise 393 * @throws JAXBException if an error occurs while retrieving the validating 394 * flag 395 */ 396 public boolean isValidating() 397 throws JAXBException; 398 399 /** 400 * Allow an application to register a <tt>ValidationEventHandler</tt>. 401 * <p> 402 * The <tt>ValidationEventHandler</tt> will be called by the JAXB Provider 403 * if any validation errors are encountered during calls to any of the 404 * unmarshal methods. If the client application does not register a 405 * <tt>ValidationEventHandler</tt> before invoking the unmarshal methods, 406 * then <tt>ValidationEvents</tt> will be handled by the default event 407 * handler which will terminate the unmarshal operation after the first 408 * error or fatal error is encountered. 409 * <p> 410 * Calling this method with a null parameter will cause the Unmarshaller 411 * to revert back to the default vefault event handler. 412 * 413 * @param handler the validation event handler 414 * @throws JAXBException if an error was encountered while setting the 415 * event handler 416 */ 417 public void setEventHandler( ValidationEventHandler handler ) 418 throws JAXBException; 419 420 /** 421 * Return the current event handler or the default event handler if one 422 * hasn't been set. 423 * 424 * @return the current ValidationEventHandler or the default event handler 425 * if it hasn't been set 426 * @throws JAXBException if an error was encountered while getting the 427 * current event handler 428 */ 429 public ValidationEventHandler getEventHandler() 430 throws JAXBException; 431 432 /** 433 * Set the particular property in the underlying implementation of 434 * <tt>Unarshaller</tt>. This method can only be used to set one of 435 * the standard JAXB defined properties above or a provider specific 436 * property. Attempting to set an undefined property will result in 437 * a PropertyException being thrown. See <a href="#supportedProps"> 438 * Supported Properties</a>. 439 * 440 * @param name the name of the property to be set. This value can either 441 * be specified using one of the constant fields or a user 442 * supplied string. 443 * @param value the value of the property to be set 444 * 445 * @throws PropertyException when there is an error processing the given 446 * property or value 447 * @throws IllegalArgumentException 448 * If the name parameter is null 449 */ 450 public void setProperty( String name, Object value ) 451 throws PropertyException; 452 453 /** 454 * Get the particular property in the underlying implementation of 455 * <tt>Unmarshaller</tt>. This method can only be used to get one of 456 * the standard JAXB defined properties above or a provider specific 457 * property. Attempting to get an undefined property will result in 458 * a PropertyException being thrown. See <a href="#supportedProps"> 459 * Supported Properties</a>. 460 * 461 * @param name the name of the property to retrieve 462 * @return the value of the requested property 463 * 464 * @throws PropertyException 465 * when there is an error retrieving the given property or value 466 * property name 467 * @throws IllegalArgumentException 468 * If the name parameter is null 469 */ 470 public Object getProperty( String name ) throws PropertyException; 471 472 473 }