nu.xom.xslt

## Class XSLTransform

- Object
- - nu.xom.xslt.XSLTransform

-     public final class XSLTransform
      extends Object

  Serves as an interface to a TrAX aware XSLT processor such as Xalan or Saxon. The following example shows how to apply an XSL Transformation to a XOM document and get the transformation result in the form of a XOM `Nodes` object:

  >     public static Nodes transform(Document in)
  >        throws XSLException, ParsingException, IOException {
  >          Builder builder = new Builder();
  >          Document stylesheet = builder.build("mystylesheet.xsl");
  >          XSLTransform transform = new XSLTransform(stylesheet);
  >          return transform.transform(in);
  >      }

  XOM relies on TrAX to perform the transformation. The `javax.xml.transform.TransformerFactory` Java system property determines which XSLT engine TrAX uses. Its value should be the fully qualified name of the implementation of the abstract `javax.xml.transform.TransformerFactory` class. Values of this property for popular XSLT processors include:

  - Saxon 6.x: `com.icl.saxon.TransformerFactoryImpl`
  - Saxon 7.x through 9.x: `net.sf.saxon.TransformerFactoryImpl`
  - Xalan interpretive: `org.apache.xalan.processor.TransformerFactoryImpl`
  - Xalan XSLTC: `org.apache.xalan.xsltc.trax.TransformerFactoryImpl`
  - jd.xslt: `jd.xml.xslt.trax.TransformerFactoryImpl`
  - Oracle: `oracle.xml.jaxp.JXSAXTransformerFactory`
  - Java bundled Xalan: `com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl`

  This property can be set in all the usual ways a Java system property can be set. TrAX picks from them in this order:

  1. The most recent value specified by invoking `System.setProperty("javax.xml.transform.TransformerFactory", "classname")`
  2. The value specified at the command line using the `-Djavax.xml.transform.TransformerFactory=classname` option to the java interpreter
  3. The class named in the `lib/jaxp.properties` properties file in the JRE directory, in a line like this one:

         javax.xml.transform.TransformerFactory=classname

  4. The class named in the `META-INF/services/javax.xml.transform.TransformerFactory` file in the JAR archives available to the runtime
  5. Finally, if all of the above options fail, a default implementation is chosen. In Sun's JDK this is usually com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl.
  Version:
    1.2.11
  Author:
    Elliotte Rusty Harold

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `XSLTransform(Document stylesheet)` Creates a new `XSLTransform` by reading the stylesheet from the supplied document.
    `XSLTransform(Document stylesheet, NodeFactory factory)` Creates a new `XSLTransform` by reading the stylesheet from the supplied document.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `setParameter(String name, Object value)` Supply a parameter to transformations performed by this object.
    `void` | `setParameter(String name, String namespace, Object value)` Supply a parameter to transformations performed by this object.
    `static Document` | `toDocument(Nodes nodes)` Builds a `Document` object from a `Nodes` object.
    `String` | `toString()` Returns a string form of this `XSLTransform`, suitable for debugging.
    `Nodes` | `transform(Document in)` Creates a new `Nodes` from the input `Document` by applying this object's stylesheet.
    `Nodes` | `transform(Nodes in)` Creates a new `Nodes` object from the input `Nodes` object by applying this object's stylesheet.

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### XSLTransform

          public XSLTransform(Document stylesheet)
                       throws XSLException

      Creates a new `XSLTransform` by reading the stylesheet from the supplied document.

      Parameters:
        `stylesheet` - document containing the stylesheet
      Throws:
        `XSLException` - when the supplied document is not syntactically correct XSLT

    - #### XSLTransform

          public XSLTransform(Document stylesheet,
                              NodeFactory factory)
                       throws XSLException

      Creates a new `XSLTransform` by reading the stylesheet from the supplied document. The supplied factory will be used to create all nodes in the result tree, so that a transform can create instances of subclasses of the standard XOM classes. Because an XSL transformation generates a list of nodes rather than a document, the factory's `startMakingDocument` and `finishMakingDocument` methods are not called.

      Parameters:
        `stylesheet` - document containing the stylesheet
        `factory` - the factory used to build nodes in the result tree
      Throws:
        `XSLException` - when the supplied document is not syntactically correct XSLT

  - ### Method Detail

    - #### transform

          public Nodes transform(Document in)
                          throws XSLException

      Creates a new `Nodes` from the input `Document` by applying this object's stylesheet. The original `Document` is not changed.

      Parameters:
        `in` - document to transform
      Returns:
        a `Nodes` containing the result of the transformation
      Throws:
        `XSLException` - if the transformation fails, normally due to an XSLT error

    - #### setParameter

          public void setParameter(String name,
                                   Object value)

      Supply a parameter to transformations performed by this object. The value is normally a `Boolean`, `Double`, or `String`. However, it may be another type if the underlying XSLT processor supports that type. Passing null for the value removes the parameter.

      Parameters:
        `name` - the name of the parameter
        `value` - the value of the parameter

    - #### setParameter

          public void setParameter(String name,
                                   String namespace,
                                   Object value)

      Supply a parameter to transformations performed by this object. The value is normally a `Boolean`, `Double`, or `String`. However, it may be another type if the underlying XSLT processor supports that type. Passing null for the value removes the parameter.

      Parameters:
        `name` - the name of the parameter
        `namespace` - the namespace URI of the parameter
        `value` - the value of the parameter

    - #### transform

          public Nodes transform(Nodes in)
                          throws XSLException

      Creates a new `Nodes` object from the input `Nodes` object by applying this object's stylesheet. The original `Nodes` object is not changed.

      Parameters:
        `in` - document to transform
      Returns:
        a `Nodes` containing the result of the transformation
      Throws:
        `XSLException` - if the transformation fails, normally due to an XSLT error

    - #### toDocument

          public static Document toDocument(Nodes nodes)

      Builds a `Document` object from a `Nodes` object. This is useful when the stylesheet is known to produce a well-formed document with a single root element. That is, the `Node` returned contains only comments, processing instructions, and exactly one element. If the stylesheet produces anything else, this method throws `XMLException`.

      Parameters:
        `nodes` - the nodes to be placed in the new document
      Returns:
        a document containing the nodes
      Throws:
        `XMLException` - if `nodes` does not contain exactly one element or if it contains any text nodes or attributes

    - #### toString

          public String toString()

      Returns a string form of this `XSLTransform`, suitable for debugging.

      Overrides:
        `toString` in class `Object`
      Returns:
        debugging string

Copyright 2002-2020 Elliotte Rusty Harold
elharo@ibiblio.org