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 }