Home » xml-commons-external-1.4.01-src » javax » xml » bind » util » [javadoc | source]

    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   }

Home » xml-commons-external-1.4.01-src » javax » xml » bind » util » [javadoc | source]