UnmarshallerHandler


1   /*
2    * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
3    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
4    */
5   package javax.xml.bind;
6   
7   import org.xml.sax.ContentHandler  ;
8   
9   /**
10   * Unmarshaller implemented as SAX ContentHandler.
11   * 
12   * <p>
13   * Applications can use this interface to use their JAXB provider as a component 
14   * in an XML pipeline.  For example:
15   * 
16   * <pre>
17   *       JAXBContext context = JAXBContext.newInstance( "org.acme.foo" );
18   *
19   *       Unmarshaller unmarshaller = context.createUnmarshaller();
20   * 
21   *       UnmarshallerHandler unmarshallerHandler = unmarshaller.getUnmarshallerHandler();
22   *
23   *       SAXParserFactory spf = SAXParserFactory.newInstance();
24   *       spf.setNamespaceAware( true );
25   * 
26   *       XMLReader xmlReader = spf.newSAXParser().getXMLReader();
27   *       xmlReader.setContentHandler( unmarshallerHandler );
28   *       xmlReader.parse(new InputSource( new FileInputStream( XML_FILE ) ) );
29   *
30   *       MyObject myObject= (MyObject)unmarshallerHandler.getResult();                          
31   * </pre>
32   * 
33   * <p>
34   * This interface is reusable: even if the user fails to unmarshal
35   * an object, s/he can still start a new round of unmarshalling.
36   * 
37   * @author <ul><li>Kohsuke KAWAGUCHI, Sun Microsystems, Inc.</li></ul>
38   * @version $Revision: 1.1 $ $Date: 2004/12/14 21:50:41 $
39   * @see Unmarshaller#getUnmarshallerHandler()
40   * @since JAXB1.0
41   */
42  public interface UnmarshallerHandler extends ContentHandler  
43  {
44      /**
45       * Obtains the unmarshalled result.
46       * 
47       * This method can be called only after this handler
48       * receives the endDocument SAX event.
49       * 
50       * @exception IllegalStateException
51       *      if this method is called before this handler
52       *      receives the endDocument event.
53       * 
54       * @exception JAXBException
55       *      if there is any unmarshalling error.
56       *      Note that the implementation is allowed to throw SAXException
57       *      during the parsing when it finds an error.
58       * 
59       * @return
60       *      always return a non-null valid object which was unmarshalled.
61       */
62      Object   getResult() throws JAXBException, IllegalStateException  ;
63  }
64
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags