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 }