001    /*
002     * $Id: UnmarshallerHandler.java,v 1.11 2003/01/14 02:24:26 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    package javax.xml.bind;
011    
012    import org.xml.sax.ContentHandler;
013    import javax.xml.bind.JAXBException;
014    
015    /**
016     * Unmarshaller implemented as SAX ContentHandler.
017     * 
018     * <p>
019     * Applications can use this interface to use their JAXB provider as a component 
020     * in an XML pipeline.  For example:
021     * 
022     * <pre>
023     *       JAXBContext context = JAXBContext.newInstance( "org.acme.foo" );
024     *
025     *       Unmarshaller unmarshaller = context.createUnmarshaller();
026     * 
027     *       UnmarshallerHandler unmarshallerHandler = unmarshaller.getUnmarshallerHandler();
028     *
029     *       SAXParserFactory spf = SAXParserFactory.newInstance();
030     *       spf.setNamespaceAware( true );
031     * 
032     *       XMLReader xmlReader = spf.newSAXParser().getXMLReader();
033     *       xmlReader.setContentHandler( unmarshallerHandler );
034     *       xmlReader.parse(new InputSource( new FileInputStream( XML_FILE ) ) );
035     *
036     *       MyObject myObject= (MyObject)unmarshallerHandler.getResult();                          
037     * </pre>
038     * 
039     * <p>
040     * This interface is reusable: even if the user fails to unmarshal
041     * an object, s/he can still start a new round of unmarshalling.
042     * 
043     * @author <ul><li>Kohsuke KAWAGUCHI, Sun Microsystems, Inc.</li></ul>
044     * @version $Revision: 1.11 $ $Date: 2003/01/14 02:24:26 $
045     * @see Unmarshaller#getUnmarshallerHandler()
046     * @since JAXB1.0
047     */
048    public interface UnmarshallerHandler extends ContentHandler
049    {
050        /**
051         * Obtains the unmarshalled result.
052         * 
053         * This method can be called only after this handler
054         * receives the endDocument SAX event.
055         * 
056         * @exception IllegalStateException
057         *      if this method is called before this handler
058         *      receives the endDocument event.
059         * 
060         * @exception JAXBException
061         *      if there is any unmarshalling error.
062         *      Note that the implementation is allowed to throw SAXException
063         *      during the parsing when it finds an error.
064         * 
065         * @return
066         *      always return a non-null valid object which was unmarshalled.
067         */
068        Object getResult() throws JAXBException, IllegalStateException;
069    }