XSLTProcess (Apache Ant API)

Package org.apache.tools.ant.taskdefs

## Class XSLTProcess

- java.lang.Object
- - org.apache.tools.ant.ProjectComponent
  - - org.apache.tools.ant.Task
    - - org.apache.tools.ant.taskdefs.MatchingTask
      - - org.apache.tools.ant.taskdefs.XSLTProcess

- All Implemented Interfaces:
    `java.lang.Cloneable`, `XSLTLogger`, `SelectorContainer`

      public class XSLTProcess
      extends MatchingTask
      implements XSLTLogger

  Processes a set of XML documents via XSLT. This is useful for building views of XML based documentation.
  Since:
    Ant 1.1

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `XSLTProcess.Factory` | The factory element to configure a transformer factory
    `static class` | `XSLTProcess.OutputProperty` | Specify how the result tree should be output as specified in the specification.
    `static class` | `XSLTProcess.Param` | The Param inner class used to store XSL parameters
    `static class` | `XSLTProcess.ParamType` | Enum for types of the parameter expression.
    `class` | `XSLTProcess.TraceConfiguration` | Configuration for Xalan2 traces.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `PROCESSOR_TRAX` | The default processor is trax

    - ### Fields inherited from class org.apache.tools.ant.taskdefs.MatchingTask

      `fileset`

    - ### Fields inherited from class org.apache.tools.ant.Task

      `target, taskName, taskType, wrapper`

    - ### Fields inherited from class org.apache.tools.ant.ProjectComponent

      `description, location, project`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `XSLTProcess()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `add​(ResourceCollection rc)` | Adds a collection of resources to style in addition to the given file or the implicit fileset.
    `void` | `add​(FileNameMapper fileNameMapper)` | Adds a nested filenamemapper.
    `void` | `addConfiguredStyle​(Resources rc)` | Add a nested <style> element.
    `void` | `addConfiguredXMLCatalog​(XMLCatalog xmlCatalog)` | Add the catalog to our internal catalog
    `void` | `addMapper​(Mapper mapper)` | Defines the mapper to map source to destination files.
    `void` | `addSysproperty​(Environment.Variable sysp)` | A system property to set during transformation.
    `void` | `addSyspropertyset​(PropertySet sysp)` | A set of system properties to set during transformation.
    `protected void` | `configureLiaison​(java.io.File stylesheet)` | Deprecated. since Ant 1.7
    `protected void` | `configureLiaison​(Resource stylesheet)` | Loads the stylesheet and set xsl:param parameters.
    `Path` | `createClasspath()` | Set the optional classpath to the XSL processor
    `XSLTProcess.Factory` | `createFactory()` | Create the factory element to configure a trax liaison.
    `XSLTProcess.OutputProperty` | `createOutputProperty()` | Create an instance of an output property to be configured.
    `XSLTProcess.Param` | `createParam()` | Create an instance of an XSL parameter for configuration by Ant.
    `XSLTProcess.TraceConfiguration` | `createTrace()` | Enables Xalan2 traces and uses the given configuration.
    `void` | `execute()` | Executes the task.
    `XSLTProcess.Factory` | `getFactory()` | Get the factory instance configured for this processor
    `protected XSLTLiaison` | `getLiaison()` | Get the Liaison implementation to use in processing.
    `java.util.Enumeration<XSLTProcess.OutputProperty>` | `getOutputProperties()` | Get an enumeration on the outputproperties.
    `boolean` | `getSuppressWarnings()` | Whether to suppress warning messages of the processor.
    `XSLTProcess.TraceConfiguration` | `getTraceConfiguration()` | Configuration for Xalan2 traces.
    `XMLCatalog` | `getXMLCatalog()` | Get the XML catalog containing entity definitions
    `protected void` | `handleError​(java.lang.String msg)` | Throws an exception with the given message if failOnError is true, otherwise logs the message using the WARN level.
    `protected void` | `handleError​(java.lang.Throwable ex)` | Throws an exception with the given nested exception if failOnError is true, otherwise logs the message using the WARN level.
    `protected void` | `handleTransformationError​(java.lang.Exception ex)` | Throws an exception with the given nested exception if failOnError and failOnTransformationError are true, otherwise logs the message using the WARN level.
    `void` | `init()` | Initialize internal instance of XMLCatalog.
    `void` | `setBasedir​(java.io.File dir)` | Set the base directory; optional, default is the project's basedir.
    `void` | `setClasspath​(Path classpath)` | Set the optional classpath to the XSL processor
    `void` | `setClasspathRef​(Reference r)` | Set the reference to an optional classpath to the XSL processor
    `void` | `setDestdir​(java.io.File dir)` | Set the destination directory into which the XSL result files should be copied to; required, unless `in` and `out` are specified.
    `void` | `setExtension​(java.lang.String name)` | Set the desired file extension to be used for the target; optional, default is html.
    `void` | `setFailOnError​(boolean b)` | Whether any errors should make the build fail.
    `void` | `setFailOnNoResources​(boolean b)` | Whether the build should fail if the nested resource collection is empty.
    `void` | `setFailOnTransformationError​(boolean b)` | Whether transformation errors should make the build fail.
    `void` | `setFileDirParameter​(java.lang.String fileDirParameter)` | Pass the directory name of the current processed file as a xsl parameter to the transformation.
    `void` | `setFileNameParameter​(java.lang.String fileNameParameter)` | Pass the filename of the current processed file as a xsl parameter to the transformation.
    `void` | `setForce​(boolean force)` | Set whether to check dependencies, or always generate; optional, default is false.
    `void` | `setGranularity​(long granularity)` | Set the number of milliseconds leeway to give before deciding a target is out of date.
    `void` | `setIn​(java.io.File inFile)` | specifies a single XML document to be styled.
    `void` | `setOut​(java.io.File outFile)` | Specifies the output name for the styled result from the `in` attribute; required if `in` is set
    `void` | `setProcessor​(java.lang.String processor)` | Set the name of the XSL processor to use; optional, default trax.
    `void` | `setReloadStylesheet​(boolean b)` | Controls whether the stylesheet is reloaded for every transform.
    `void` | `setScanIncludedDirectories​(boolean b)` | Whether to style all files in the included directories as well; optional, default is true.
    `void` | `setStyle​(java.lang.String xslFile)` | Name of the stylesheet to use - given either relative to the project's basedir or as an absolute path; required.
    `void` | `setSuppressWarnings​(boolean b)` | Whether to suppress warning messages of the processor.
    `void` | `setUseImplicitFileset​(boolean useimplicitfileset)` | Whether to use the implicit fileset.
    `void` | `setXslResource​(Resource xslResource)` | API method to set the XSL Resource.

    - ### Methods inherited from class org.apache.tools.ant.taskdefs.MatchingTask

      `add, addAnd, addContains, addContainsRegexp, addCustom, addDate, addDepend, addDepth, addDifferent, addFilename, addMajority, addModified, addNone, addNot, addOr, addPresent, addSelector, addSize, addType, appendSelector, createExclude, createExcludesFile, createInclude, createIncludesFile, createPatternSet, getDirectoryScanner, getImplicitFileSet, getSelectors, hasSelectors, selectorCount, selectorElements, setCaseSensitive, setDefaultexcludes, setExcludes, setExcludesfile, setFollowSymlinks, setIncludes, setIncludesfile, setProject, XsetIgnore, XsetItems`

    - ### Methods inherited from class org.apache.tools.ant.Task

      `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

    - ### Methods inherited from class org.apache.tools.ant.ProjectComponent

      `clone, getDescription, getLocation, getProject, setDescription, setLocation`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface org.apache.tools.ant.taskdefs.XSLTLogger

      `log`

- - ### Field Detail

    - #### PROCESSOR_TRAX

          public static final java.lang.String PROCESSOR_TRAX

      The default processor is trax
      Since:
        Ant 1.7
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### XSLTProcess

          public XSLTProcess()

  - ### Method Detail

    - #### setScanIncludedDirectories

          public void setScanIncludedDirectories​(boolean b)

      Whether to style all files in the included directories as well; optional, default is true.
      Parameters:
        `b` - true if files in included directories are processed.
      Since:
        Ant 1.5

    - #### setReloadStylesheet

          public void setReloadStylesheet​(boolean b)

      Controls whether the stylesheet is reloaded for every transform.

      Setting this to true may get around a bug in certain Xalan-J versions, default is false.

      Parameters:
        `b` - a `boolean` value
      Since:
        Ant 1.5.2

    - #### addMapper

          public void addMapper​(Mapper mapper)

      Defines the mapper to map source to destination files.
      Parameters:
        `mapper` - the mapper to use
      Throws:
        `BuildException` - if more than one mapper is defined
      Since:
        Ant 1.6.2

    - #### add

          public void add​(ResourceCollection rc)

      Adds a collection of resources to style in addition to the given file or the implicit fileset.
      Parameters:
        `rc` - the collection of resources to style
      Since:
        Ant 1.7

    - #### addConfiguredStyle

          public void addConfiguredStyle​(Resources rc)

      Add a nested <style> element.
      Parameters:
        `rc` - the configured Resources object represented as <style>.
      Since:
        Ant 1.7

    - #### setXslResource

          public void setXslResource​(Resource xslResource)

      API method to set the XSL Resource.
      Parameters:
        `xslResource` - Resource to set as the stylesheet.
      Since:
        Ant 1.7

    - #### add

          public void add​(FileNameMapper fileNameMapper)
                   throws BuildException

      Adds a nested filenamemapper.
      Parameters:
        `fileNameMapper` - the mapper to add
      Throws:
        `BuildException` - if more than one mapper is defined
      Since:
        Ant 1.7.0

    - #### execute

          public void execute()
                       throws BuildException

      Executes the task.
      Overrides:
        `execute` in class `Task`
      Throws:
        `BuildException` - if there is an execution problem.
      To do:
        validate that if either in or out is defined, then both are

    - #### setForce

          public void setForce​(boolean force)

      Set whether to check dependencies, or always generate; optional, default is false.
      Parameters:
        `force` - true if always generate.

    - #### setBasedir

          public void setBasedir​(java.io.File dir)

      Set the base directory; optional, default is the project's basedir.
      Parameters:
        `dir` - the base directory

    - #### setDestdir

          public void setDestdir​(java.io.File dir)

      Set the destination directory into which the XSL result files should be copied to; required, unless `in` and `out` are specified.
      Parameters:
        `dir` - the name of the destination directory

    - #### setExtension

          public void setExtension​(java.lang.String name)

      Set the desired file extension to be used for the target; optional, default is html.
      Parameters:
        `name` - the extension to use

    - #### setStyle

          public void setStyle​(java.lang.String xslFile)

      Name of the stylesheet to use - given either relative to the project's basedir or as an absolute path; required.
      Parameters:
        `xslFile` - the stylesheet to use

    - #### setClasspath

          public void setClasspath​(Path classpath)

      Set the optional classpath to the XSL processor
      Parameters:
        `classpath` - the classpath to use when loading the XSL processor

    - #### createClasspath

          public Path createClasspath()

      Set the optional classpath to the XSL processor
      Returns:
        a path instance to be configured by the Ant core.

    - #### setClasspathRef

          public void setClasspathRef​(Reference r)

      Set the reference to an optional classpath to the XSL processor
      Parameters:
        `r` - the id of the Ant path instance to act as the classpath for loading the XSL processor

    - #### setProcessor

          public void setProcessor​(java.lang.String processor)

      Set the name of the XSL processor to use; optional, default trax.
      Parameters:
        `processor` - the name of the XSL processor

    - #### setUseImplicitFileset

          public void setUseImplicitFileset​(boolean useimplicitfileset)

      Whether to use the implicit fileset.

      Set this to false if you want explicit control with nested resource collections.

      Parameters:
        `useimplicitfileset` - set to true if you want to use implicit fileset
      Since:
        Ant 1.7

    - #### addConfiguredXMLCatalog

          public void addConfiguredXMLCatalog​(XMLCatalog xmlCatalog)

      Add the catalog to our internal catalog
      Parameters:
        `xmlCatalog` - the XMLCatalog instance to use to look up DTDs

    - #### setFileNameParameter

          public void setFileNameParameter​(java.lang.String fileNameParameter)

      Pass the filename of the current processed file as a xsl parameter to the transformation. This value sets the name of that xsl parameter.
      Parameters:
        `fileNameParameter` - name of the xsl parameter retrieving the current file name

    - #### setFileDirParameter

          public void setFileDirParameter​(java.lang.String fileDirParameter)

      Pass the directory name of the current processed file as a xsl parameter to the transformation. This value sets the name of that xsl parameter.
      Parameters:
        `fileDirParameter` - name of the xsl parameter retrieving the current file directory

    - #### setSuppressWarnings

          public void setSuppressWarnings​(boolean b)

      Whether to suppress warning messages of the processor.
      Parameters:
        `b` - boolean
      Since:
        Ant 1.8.0

    - #### getSuppressWarnings

          public boolean getSuppressWarnings()

      Whether to suppress warning messages of the processor.
      Returns:
        boolean
      Since:
        Ant 1.8.0

    - #### setFailOnTransformationError

          public void setFailOnTransformationError​(boolean b)

      Whether transformation errors should make the build fail.
      Parameters:
        `b` - boolean
      Since:
        Ant 1.8.0

    - #### setFailOnError

          public void setFailOnError​(boolean b)

      Whether any errors should make the build fail.
      Parameters:
        `b` - boolean
      Since:
        Ant 1.8.0

    - #### setFailOnNoResources

          public void setFailOnNoResources​(boolean b)

      Whether the build should fail if the nested resource collection is empty.
      Parameters:
        `b` - boolean
      Since:
        Ant 1.8.0

    - #### addSysproperty

          public void addSysproperty​(Environment.Variable sysp)

      A system property to set during transformation.
      Parameters:
        `sysp` - Environment.Variable
      Since:
        Ant 1.8.0

    - #### addSyspropertyset

          public void addSyspropertyset​(PropertySet sysp)

      A set of system properties to set during transformation.
      Parameters:
        `sysp` - PropertySet
      Since:
        Ant 1.8.0

    - #### createTrace

          public XSLTProcess.TraceConfiguration createTrace()

      Enables Xalan2 traces and uses the given configuration.

      Note that this element doesn't have any effect with a processor other than trax or if the Transformer is not Xalan2's transformer implementation.

      Returns:
        TraceConfiguration
      Since:
        Ant 1.8.0

    - #### getTraceConfiguration

          public XSLTProcess.TraceConfiguration getTraceConfiguration()

      Configuration for Xalan2 traces.
      Returns:
        TraceConfiguration
      Since:
        Ant 1.8.0

    - #### setGranularity

          public void setGranularity​(long granularity)

      Set the number of milliseconds leeway to give before deciding a target is out of date.

      Default is 1 second, or 2 seconds on DOS systems.

      Parameters:
        `granularity` - the granularity used to decide if a target is out of date.
      Since:
        Ant 1.10.16

    - #### setOut

          public void setOut​(java.io.File outFile)

      Specifies the output name for the styled result from the `in` attribute; required if `in` is set
      Parameters:
        `outFile` - the output File instance.

    - #### setIn

          public void setIn​(java.io.File inFile)

      specifies a single XML document to be styled. Should be used with the `out` attribute; required if `out` is set
      Parameters:
        `inFile` - the input file

    - #### getFactory

          public XSLTProcess.Factory getFactory()

      Get the factory instance configured for this processor
      Returns:
        the factory instance in use

    - #### getXMLCatalog

          public XMLCatalog getXMLCatalog()

      Get the XML catalog containing entity definitions
      Returns:
        the XML catalog for the task.

    - #### getOutputProperties

          public java.util.Enumeration<XSLTProcess.OutputProperty> getOutputProperties()

      Get an enumeration on the outputproperties.
      Returns:
        the outputproperties

    - #### getLiaison

          protected XSLTLiaison getLiaison()

      Get the Liaison implementation to use in processing.
      Returns:
        an instance of the XSLTLiaison interface.

    - #### createParam

          public XSLTProcess.Param createParam()

      Create an instance of an XSL parameter for configuration by Ant.
      Returns:
        an instance of the Param class to be configured.

    - #### createOutputProperty

          public XSLTProcess.OutputProperty createOutputProperty()

      Create an instance of an output property to be configured.
      Returns:
        the newly created output property.
      Since:
        Ant 1.5

    - #### init

          public void init()
                    throws BuildException

      Initialize internal instance of XMLCatalog. Initialize XPath for parameter evaluation.
      Overrides:
        `init` in class `Task`
      Throws:
        `BuildException` - on error

    - #### configureLiaison

          @Deprecated
          protected void configureLiaison​(java.io.File stylesheet)
                                   throws BuildException

      Deprecated.
      since Ant 1.7
      Loads the stylesheet and set xsl:param parameters.
      Parameters:
        `stylesheet` - the file from which to load the stylesheet.
      Throws:
        `BuildException` - if the stylesheet cannot be loaded.

    - #### configureLiaison

          protected void configureLiaison​(Resource stylesheet)
                                   throws BuildException

      Loads the stylesheet and set xsl:param parameters.
      Parameters:
        `stylesheet` - the resource from which to load the stylesheet.
      Throws:
        `BuildException` - if the stylesheet cannot be loaded.
      Since:
        Ant 1.7

    - #### createFactory

          public XSLTProcess.Factory createFactory()
                                            throws BuildException

      Create the factory element to configure a trax liaison.
      Returns:
        the newly created factory element.
      Throws:
        `BuildException` - if the element is created more than one time.

    - #### handleError

          protected void handleError​(java.lang.String msg)

      Throws an exception with the given message if failOnError is true, otherwise logs the message using the WARN level.
      Parameters:
        `msg` - String
      Since:
        Ant 1.8.0

    - #### handleError

          protected void handleError​(java.lang.Throwable ex)

      Throws an exception with the given nested exception if failOnError is true, otherwise logs the message using the WARN level.
      Parameters:
        `ex` - Throwable
      Since:
        Ant 1.8.0

    - #### handleTransformationError

          protected void handleTransformationError​(java.lang.Exception ex)

      Throws an exception with the given nested exception if failOnError and failOnTransformationError are true, otherwise logs the message using the WARN level.
      Parameters:
        `ex` - Exception
      Since:
        Ant 1.8.0