jdomresult.java

JAVA的Jdom包

/*-- 

 $Id: JDOMResult.java,v 1.24 2007/11/10 05:29:02 jhunter Exp $

 Copyright (C) 2001-2007 Jason Hunter & Brett McLaughlin.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions, and the following disclaimer.
 
 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions, and the disclaimer that follows 
    these conditions in the documentation and/or other materials 
    provided with the distribution.

 3. The name "JDOM" must not be used to endorse or promote products
    derived from this software without prior written permission.  For
    written permission, please contact <request_AT_jdom_DOT_org>.
 
 4. Products derived from this software may not be called "JDOM", nor
    may "JDOM" appear in their name, without prior written permission
    from the JDOM Project Management <request_AT_jdom_DOT_org>.
 
 In addition, we request (but do not require) that you include in the 
 end-user documentation provided with the redistribution and/or in the 
 software itself an acknowledgement equivalent to the following:
     "This product includes software developed by the
      JDOM Project (http://www.jdom.org/)."
 Alternatively, the acknowledgment may be graphical using the logos 
 available at http://www.jdom.org/images/logos.

 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED.  IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 SUCH DAMAGE.

 This software consists of voluntary contributions made by many 
 individuals on behalf of the JDOM Project and was originally 
 created by Jason Hunter <jhunter_AT_jdom_DOT_org> and
 Brett McLaughlin <brett_AT_jdom_DOT_org>.  For more information
 on the JDOM Project, please see <http://www.jdom.org/>.
 
 */

package org.jdom.transform;

import java.util.*;

import javax.xml.transform.sax.*;

import org.jdom.*;
import org.jdom.input.*;
import org.xml.sax.*;
import org.xml.sax.ext.*;
import org.xml.sax.helpers.*;

/**
 * A holder for an XSL Transformation result, generally a list of nodes
 * although it can be a JDOM Document also. As stated by the XSLT 1.0
 * specification, the result tree generated by an XSL transformation is not
 * required to be a well-formed XML document. The result tree may have "any
 * sequence of nodes as children that would be possible for an
 * element node".
 * <p>
 * The following example shows how to apply an XSL Transformation
 * to a JDOM document and get the transformation result in the form
 * of a list of JDOM nodes:
 * <pre><code>
 *   public static List transform(Document doc, String stylesheet)
 *                                        throws JDOMException {
 *     try {
 *       Transformer transformer = TransformerFactory.newInstance()
 *                             .newTransformer(new StreamSource(stylesheet));
 *       JDOMSource in = new JDOMSource(doc);
 *       JDOMResult out = new JDOMResult();
 *       transformer.transform(in, out);
 *       return out.getResult();
 *     }
 *     catch (TransformerException e) {
 *       throw new JDOMException("XSLT Transformation failed", e);
 *     }
 *   }
 * </code></pre>
 *
 * @see      org.jdom.transform.JDOMSource
 *
 * @version $Revision: 1.24 $, $Date: 2007/11/10 05:29:02 $
 * @author  Laurent Bihanic
 * @author  Jason Hunter
 */
public class JDOMResult extends SAXResult {

    private static final String CVS_ID =
    "@(#) $RCSfile: JDOMResult.java,v $ $Revision: 1.24 $ $Date: 2007/11/10 05:29:02 $ $Name: jdom_1_1 $";

  /**
   * If {@link javax.xml.transform.TransformerFactory#getFeature}
   * returns <code>true</code> when passed this value as an
   * argument, the Transformer natively supports JDOM.
   * <p>
   * <strong>Note</strong>: This implementation does not override
   * the {@link SAXResult#FEATURE} value defined by its superclass
   * to be considered as a SAXResult by Transformer implementations
   * not natively supporting JDOM.</p>
   */
  public final static String JDOM_FEATURE =
                      "http://org.jdom.transform.JDOMResult/feature";

  /**
   * The result of a transformation, as set by Transformer
   * implementations that natively support JDOM, as a JDOM document
   * or a list of JDOM nodes.
   */
  private Object result = null;

  /**
   * Whether the application queried the result (as a list or a
   * document) since it was last set.
   */
  private boolean queried = false;

  /**
   * The custom JDOM factory to use when building the transformation
   * result or <code>null</code> to use the default JDOM classes.
   */
  private JDOMFactory factory = null;

  /**
   * Public default constructor.
   */
  public JDOMResult() {
    // Allocate custom builder object...
    DocumentBuilder builder = new DocumentBuilder();

    // And use it as ContentHandler and LexicalHandler.
    super.setHandler(builder);
    super.setLexicalHandler(builder);
  }

  /**
   * Sets the object(s) produced as result of an XSL Transformation.
   * <p>
   * <strong>Note</strong>: This method shall be used by the
   * {@link javax.xml.transform.Transformer} implementations that
   * natively support JDOM to directly set the transformation
   * result rather than considering this object as a
   * {@link SAXResult}.  Applications should <i>not</i> use this
   * method.</p>
   *
   * @param  result   the result of a transformation as a
   *                  {@link java.util.List list} of JDOM nodes
   *                  (Elements, Texts, Comments, PIs...).
   *
   * @see    #getResult
   */
  public void setResult(List result) {
    this.result  = result;
    this.queried = false;
  }

  /**
   * Returns the result of an XSL Transformation as a list of JDOM
   * nodes.
   * <p>
   * If the result of the transformation is a JDOM document,
   * this method converts it into a list of JDOM nodes; any
   * subsequent call to {@link #getDocument} will return
   * <code>null</code>.</p>
   *
   * @return the transformation result as a (possibly empty) list of
   *         JDOM nodes (Elements, Texts, Comments, PIs...).
   */
  public List getResult() {
    List nodes = Collections.EMPTY_LIST;

    // Retrieve result from the document builder if not set.
    this.retrieveResult();

    if (result instanceof List) {
      nodes = (List)result;
    }
    else {
      if ((result instanceof Document) && (queried == false)) {
        List content = ((Document)result).getContent();
        nodes = new ArrayList(content.size());

        while (content.size() != 0)
        {
          Object o = content.remove(0);
          nodes.add(o);
        }
        result = nodes;
      }
    }
    queried = true;

    return (nodes);
  }

  /**
   * Sets the document produced as result of an XSL Transformation.
   * <p>
   * <strong>Note</strong>: This method shall be used by the
   * {@link javax.xml.transform.Transformer} implementations that
   * natively support JDOM to directly set the transformation
   * result rather than considering this object as a
   * {@link SAXResult}.  Applications should <i>not</i> use this
   * method.</p>
   *
   * @param  document   the JDOM document result of a transformation.
   *
   * @see    #setResult
   * @see    #getDocument
   */
  public void setDocument(Document document) {
    this.result  = document;
    this.queried = false;
  }

  /**
   * Returns the result of an XSL Transformation as a JDOM document.
   * <p>
   * If the result of the transformation is a list of nodes,
   * this method attempts to convert it into a JDOM document. If
   * successful, any subsequent call to {@link #getResult} will
   * return an empty list.</p>
   * <p>
   * <strong>Warning</strong>: The XSLT 1.0 specification states that
   * the output of an XSL transformation is not a well-formed XML
   * document but a list of nodes. Applications should thus use
   * {@link #getResult} instead of this method or at least expect
   * <code>null</code> documents to be returned.
   *
   * @return the transformation result as a JDOM document or
   *         <code>null</code> if the result of the transformation
   *         can not be converted into a well-formed document.
   *
   * @see    #getResult
   */
  public Document getDocument() {
    Document doc = null;

    // Retrieve result from the document builder if not set.
    this.retrieveResult();

    if (result instanceof Document) {
      doc = (Document)result;
    }
    else {
      if ((result instanceof List) && (queried == false)) {
        // Try to create a document from the result nodes
        try {
          JDOMFactory f = this.getFactory();
          if (f == null) { f = new DefaultJDOMFactory(); }

          doc = f.document(null);
          doc.setContent((List)result);

          result = doc;
        }
        catch (RuntimeException ex1) {
          // Some of the result nodes are not valid children of a
          // Document node. => return null.
        }
      }
    }
    queried = true;

    return (doc);
  }

  /**
   * Sets a custom JDOMFactory to use when building the
   * transformation result. Use a custom factory to build the tree
   * with your own subclasses of the JDOM classes.
   *
   * @param  factory   the custom <code>JDOMFactory</code> to use or
   *                   <code>null</code> to use the default JDOM
   *                   classes.
   *
   * @see    #getFactory
   */
  public void setFactory(JDOMFactory factory) {
    this.factory = factory;
  }

  /**
   * Returns the custom JDOMFactory used to build the transformation
   * result.
   *
   * @return the custom <code>JDOMFactory</code> used to build the
   *         transformation result or <code>null</code> if the
   *         default JDOM classes are being used.
   *
   * @see    #setFactory
   */
  public JDOMFactory getFactory() {
    return this.factory;
  }

  /**
   * Checks whether a transformation result has been set and, if not,
   * retrieves the result tree being built by the document builder.
   */
  private void retrieveResult() {
    if (result == null) {
      this.setResult(((DocumentBuilder)this.getHandler()).getResult());
    }
  }

  //-------------------------------------------------------------------------
  // SAXResult overwritten methods
  //-------------------------------------------------------------------------

  /**
   * Sets the target to be a SAX2 ContentHandler.
   *
   * @param handler Must be a non-null ContentHandler reference.
   */
  public void setHandler(ContentHandler handler) { }

  /**
   * Sets the SAX2 LexicalHandler for the output.
   * <p>