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