1 /*
2 * Copyright 2005-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25 package javax.xml.bind.util;
26
27 import javax.xml.bind.JAXBContext;
28 import javax.xml.bind.JAXBException;
29 import javax.xml.bind.Unmarshaller;
30 import javax.xml.bind.UnmarshallerHandler;
31 import javax.xml.transform.sax.SAXResult;
32
33 /**
34 * JAXP {@link javax.xml.transform.Result} implementation
35 * that unmarshals a JAXB object.
36 *
37 * <p>
38 * This utility class is useful to combine JAXB with
39 * other Java/XML technologies.
40 *
41 * <p>
42 * The following example shows how to use JAXB to unmarshal a document
43 * resulting from an XSLT transformation.
44 *
45 * <blockquote>
46 * <pre>
47 * JAXBResult result = new JAXBResult(
48 * JAXBContext.newInstance("org.acme.foo") );
49 *
50 * // set up XSLT transformation
51 * TransformerFactory tf = TransformerFactory.newInstance();
52 * Transformer t = tf.newTransformer(new StreamSource("test.xsl"));
53 *
54 * // run transformation
55 * t.transform(new StreamSource("document.xml"),result);
56 *
57 * // obtain the unmarshalled content tree
58 * Object o = result.getResult();
59 * </pre>
60 * </blockquote>
61 *
62 * <p>
63 * The fact that JAXBResult derives from SAXResult is an implementation
64 * detail. Thus in general applications are strongly discouraged from
65 * accessing methods defined on SAXResult.
66 *
67 * <p>
68 * In particular it shall never attempt to call the setHandler,
69 * setLexicalHandler, and setSystemId methods.
70 *
71 * @author
72 * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
73 */
74 public class JAXBResult extends SAXResult {
75
76 /**
77 * Creates a new instance that uses the specified
78 * JAXBContext to unmarshal.
79 *
80 * @param context The JAXBContext that will be used to create the
81 * necessary Unmarshaller. This parameter must not be null.
82 * @exception JAXBException if an error is encountered while creating the
83 * JAXBResult or if the context parameter is null.
84 */
85 public JAXBResult( JAXBContext context ) throws JAXBException {
86 this( ( context == null ) ? assertionFailed() : context.createUnmarshaller() );
87 }
88
89 /**
90 * Creates a new instance that uses the specified
91 * Unmarshaller to unmarshal an object.
92 *
93 * <p>
94 * This JAXBResult object will use the specified Unmarshaller
95 * instance. It is the caller's responsibility not to use the
96 * same Unmarshaller for other purposes while it is being
97 * used by this object.
98 *
99 * <p>
100 * The primary purpose of this method is to allow the client
101 * to configure Unmarshaller. Unless you know what you are doing,
102 * it's easier and safer to pass a JAXBContext.
103 *
104 * @param _unmarshaller the unmarshaller. This parameter must not be null.
105 * @throws JAXBException if an error is encountered while creating the
106 * JAXBResult or the Unmarshaller parameter is null.
107 */
108 public JAXBResult( Unmarshaller _unmarshaller ) throws JAXBException {
109 if( _unmarshaller == null )
110 throw new JAXBException(
111 Messages.format( Messages.RESULT_NULL_UNMARSHALLER ) );
112
113 this.unmarshallerHandler = _unmarshaller.getUnmarshallerHandler();
114
115 super.setHandler(unmarshallerHandler);
116 }
117
118 /**
119 * Unmarshaller that will be used to unmarshal
120 * the input documents.
121 */
122 private final UnmarshallerHandler unmarshallerHandler;
123
124 /**
125 * Gets the unmarshalled object created by the transformation.
126 *
127 * @return
128 * Always return a non-null object.
129 *
130 * @exception IllegalStateException
131 * if this method is called before an object is unmarshalled.
132 *
133 * @exception JAXBException
134 * if there is any unmarshalling error.
135 * Note that the implementation is allowed to throw SAXException
136 * during the parsing when it finds an error.
137 */
138 public Object getResult() throws JAXBException {
139 return unmarshallerHandler.getResult();
140 }
141
142 /**
143 * Hook to throw exception from the middle of a contructor chained call
144 * to this
145 */
146 private static Unmarshaller assertionFailed() throws JAXBException {
147 throw new JAXBException( Messages.format( Messages.RESULT_NULL_CONTEXT ) );
148 }
149 }