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:
  `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 enum`
`XSLTProcess.ParamType`
Enum for types of the parameter expression.
`final class`
`XSLTProcess.TraceConfiguration`
Configuration for Xalan2 traces.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final 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

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(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.
`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(String msg)`
Throws an exception with the given message if failOnError is true, otherwise logs the message using the WARN level.
`protected void`
`handleError(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(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(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(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(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(String fileDirParameter)`
Pass the directory name of the current processed file as a xsl parameter to the transformation.
`void`
`setFileNameParameter(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`
`setIn(File inFile)`
specifies a single XML document to be styled.
`void`
`setOut(File outFile)`
Specifies the output name for the styled result from the `in` attribute; required if `in` is set
`void`
`setProcessor(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(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 Details

### PROCESSOR_TRAX

public static final String PROCESSOR_TRAX
The default processor is trax

Since:
  Ant 1.7
See Also:
  - Constant Field Values

## Constructor Details

### XSLTProcess

public XSLTProcess()

## Method Details

### 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(File dir)
Set the base directory; optional, default is the project's basedir.

Parameters:
  `dir` - the base directory

### setDestdir

public void setDestdir(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(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(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(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(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(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

### setOut

public void setOut(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(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 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(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(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(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(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