01: /*
02: * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
03: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
04: */
05: package javax.xml.bind;
06:
07: import org.xml.sax.ContentHandler;
08:
09: /**
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.2 $ $Date: 2006/03/08 16:55:17 $
39: * @see Unmarshaller#getUnmarshallerHandler()
40: * @since JAXB1.0
41: */
42: public interface UnmarshallerHandler extends ContentHandler {
43: /**
44: * Obtains the unmarshalled result.
45: *
46: * This method can be called only after this handler
47: * receives the endDocument SAX event.
48: *
49: * @exception IllegalStateException
50: * if this method is called before this handler
51: * receives the endDocument event.
52: *
53: * @exception JAXBException
54: * if there is any unmarshalling error.
55: * Note that the implementation is allowed to throw SAXException
56: * during the parsing when it finds an error.
57: *
58: * @return
59: * always return a non-null valid object which was unmarshalled.
60: */
61: Object getResult() throws JAXBException, IllegalStateException;
62: }
|