View Javadoc
1   /*
2    * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.xml.bind;
27  
28  import org.xml.sax.ContentHandler;
29  
30  /**
31   * Unmarshaller implemented as SAX ContentHandler.
32   *
33   * <p>
34   * Applications can use this interface to use their JAXB provider as a component
35   * in an XML pipeline.  For example:
36   *
37   * <pre>
38   *       JAXBContext context = JAXBContext.newInstance( "org.acme.foo" );
39   *
40   *       Unmarshaller unmarshaller = context.createUnmarshaller();
41   *
42   *       UnmarshallerHandler unmarshallerHandler = unmarshaller.getUnmarshallerHandler();
43   *
44   *       SAXParserFactory spf = SAXParserFactory.newInstance();
45   *       spf.setNamespaceAware( true );
46   *
47   *       XMLReader xmlReader = spf.newSAXParser().getXMLReader();
48   *       xmlReader.setContentHandler( unmarshallerHandler );
49   *       xmlReader.parse(new InputSource( new FileInputStream( XML_FILE ) ) );
50   *
51   *       MyObject myObject= (MyObject)unmarshallerHandler.getResult();
52   * </pre>
53   *
54   * <p>
55   * This interface is reusable: even if the user fails to unmarshal
56   * an object, s/he can still start a new round of unmarshalling.
57   *
58   * @author <ul><li>Kohsuke KAWAGUCHI, Sun Microsystems, Inc.</li></ul>
59   * @see Unmarshaller#getUnmarshallerHandler()
60   * @since JAXB1.0
61   */
62  public interface UnmarshallerHandler extends ContentHandler
63  {
64      /**
65       * Obtains the unmarshalled result.
66       *
67       * This method can be called only after this handler
68       * receives the endDocument SAX event.
69       *
70       * @exception IllegalStateException
71       *      if this method is called before this handler
72       *      receives the endDocument event.
73       *
74       * @exception JAXBException
75       *      if there is any unmarshalling error.
76       *      Note that the implementation is allowed to throw SAXException
77       *      during the parsing when it finds an error.
78       *
79       * @return
80       *      always return a non-null valid object which was unmarshalled.
81       */
82      Object getResult() throws JAXBException, IllegalStateException;
83  }