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

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
class	XSLTProcess.TraceConfiguration Configuration for Xalan2 traces.

Field Summary

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

XSLTProcess()
Creates a new XSLTProcess Task.

Method Summary

void	add(FileNameMapper fileNameMapper) Adds a nested filenamemapper.
void	add(ResourceCollection rc) Adds a collection of resources to style in addition to the given file or the implicit fileset.
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 Liason implementation to use in processing.
java.util.Enumeration	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	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()

Creates a new XSLTProcess Task.

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 our 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. Other values are "xalan" for Xalan1

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.

Since:

Ant 1.8.0

getSuppressWarnings

public boolean getSuppressWarnings()

Whether to suppress warning messages of the processor.

Since:

Ant 1.8.0

setFailOnTransformationError

public void setFailOnTransformationError(boolean b)

Whether transformation errors should make the build fail.

Since:

Ant 1.8.0

setFailOnError

public void setFailOnError(boolean b)

Whether any errors should make the build fail.

Since:

Ant 1.8.0

setFailOnNoResources

public void setFailOnNoResources(boolean b)

Whether the build should fail if the nested resource collection is empty.

Since:

Ant 1.8.0

addSysproperty

public void addSysproperty(Environment.Variable sysp)

A system property to set during transformation.

Since:

Ant 1.8.0

addSyspropertyset

public void addSyspropertyset(PropertySet sysp)

A set of system properties to set during transformation.

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.

Since:

Ant 1.8.0

getTraceConfiguration

public XSLTProcess.TraceConfiguration getTraceConfiguration()

Configuration for Xalan2 traces.

Since:

Ant 1.8.0

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 getOutputProperties()

Get an enumeration on the outputproperties.

Returns:

the outputproperties

getLiaison

protected XSLTLiaison getLiaison()

Get the Liason implementation to use in processing.

Returns:

an instance of the XSLTLiason 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

Overrides:

init in class Task

Throws:

BuildException - on error

configureLiaison

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.

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.

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.

Since:

Ant 1.8.0