001: /*
002: * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: */
005: package javax.xml.bind.util;
006:
007: import javax.xml.bind.JAXBContext;
008: import javax.xml.bind.JAXBException;
009: import javax.xml.bind.Unmarshaller;
010: import javax.xml.bind.UnmarshallerHandler;
011: import javax.xml.transform.sax.SAXResult;
012:
013: /**
014: * JAXP {@link javax.xml.transform.Result} implementation
015: * that unmarshals a JAXB object.
016: *
017: * <p>
018: * This utility class is useful to combine JAXB with
019: * other Java/XML technologies.
020: *
021: * <p>
022: * The following example shows how to use JAXB to unmarshal a document
023: * resulting from an XSLT transformation.
024: *
025: * <blockquote>
026: * <pre>
027: * JAXBResult result = new JAXBResult(
028: * JAXBContext.newInstance("org.acme.foo") );
029: *
030: * // set up XSLT transformation
031: * TransformerFactory tf = TransformerFactory.newInstance();
032: * Transformer t = tf.newTransformer(new StreamSource("test.xsl"));
033: *
034: * // run transformation
035: * t.transform(new StreamSource("document.xml"),result);
036: *
037: * // obtain the unmarshalled content tree
038: * Object o = result.getResult();
039: * </pre>
040: * </blockquote>
041: *
042: * <p>
043: * The fact that JAXBResult derives from SAXResult is an implementation
044: * detail. Thus in general applications are strongly discouraged from
045: * accessing methods defined on SAXResult.
046: *
047: * <p>
048: * In particular it shall never attempt to call the setHandler,
049: * setLexicalHandler, and setSystemId methods.
050: *
051: * @author
052: * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
053: */
054: public class JAXBResult extends SAXResult {
055:
056: /**
057: * Creates a new instance that uses the specified
058: * JAXBContext to unmarshal.
059: *
060: * @param context The JAXBContext that will be used to create the
061: * necessary Unmarshaller. This parameter must not be null.
062: * @exception JAXBException if an error is encountered while creating the
063: * JAXBResult or if the context parameter is null.
064: */
065: public JAXBResult(JAXBContext context) throws JAXBException {
066: this ((context == null) ? assertionFailed() : context
067: .createUnmarshaller());
068: }
069:
070: /**
071: * Creates a new instance that uses the specified
072: * Unmarshaller to unmarshal an object.
073: *
074: * <p>
075: * This JAXBResult object will use the specified Unmarshaller
076: * instance. It is the caller's responsibility not to use the
077: * same Unmarshaller for other purposes while it is being
078: * used by this object.
079: *
080: * <p>
081: * The primary purpose of this method is to allow the client
082: * to configure Unmarshaller. Unless you know what you are doing,
083: * it's easier and safer to pass a JAXBContext.
084: *
085: * @param _unmarshaller the unmarshaller. This parameter must not be null.
086: * @throws JAXBException if an error is encountered while creating the
087: * JAXBResult or the Unmarshaller parameter is null.
088: */
089: public JAXBResult(Unmarshaller _unmarshaller) throws JAXBException {
090: if (_unmarshaller == null)
091: throw new JAXBException(Messages
092: .format(Messages.RESULT_NULL_UNMARSHALLER));
093:
094: this .unmarshallerHandler = _unmarshaller
095: .getUnmarshallerHandler();
096:
097: super .setHandler(unmarshallerHandler);
098: }
099:
100: /**
101: * Unmarshaller that will be used to unmarshal
102: * the input documents.
103: */
104: private final UnmarshallerHandler unmarshallerHandler;
105:
106: /**
107: * Gets the unmarshalled object created by the transformation.
108: *
109: * @return
110: * Always return a non-null object.
111: *
112: * @exception IllegalStateException
113: * if this method is called before an object is unmarshalled.
114: *
115: * @exception JAXBException
116: * if there is any unmarshalling error.
117: * Note that the implementation is allowed to throw SAXException
118: * during the parsing when it finds an error.
119: */
120: public Object getResult() throws JAXBException {
121: return unmarshallerHandler.getResult();
122: }
123:
124: /**
125: * Hook to throw exception from the middle of a contructor chained call
126: * to this
127: */
128: private static Unmarshaller assertionFailed() throws JAXBException {
129: throw new JAXBException(Messages
130: .format(Messages.RESULT_NULL_CONTEXT));
131: }
132: }
|