DVSL Ant Task Reference

Processes a set of XML documents using a stylesheet written in DVSL (Declarative Velocity Style Language).

This is useful for building views of XML based documentation, or for generating code, etc. Conceptually, this task performs the same function as the <style> task included with the Ant distribution but using a stylesheet with DVSL syntax instead of XSLT.

As DVSL has a tight binding with Java objects, access is provided to the "Toolbox" which loads properties and objects which are then exposed to the stylesheet in a transparent manner.

Since DVSL utilizes Velocity for rendering its output, access is provided to allow configuring the Velocity runtime environment from within this task.

It is possible to refine the set of files that are being processed. This can be done with the includes, includesfile, excludes, excludesfile and defaultexcludes attributes. With the includes or includesfile attribute you specify the files you want to have included by using patterns. The exclude or excludesfile attribute is used to specify the files you want to have excluded. This is also done with patterns. And finally with the defaultexcludes attribute, you can specify whether you want to use default exclusions or not. See the section on directory based tasks, on how the inclusion/exclusion of files works, and how to write patterns.

This task forms an implicit FileSet and supports all attributes of <fileset> (dir becomes basedir) as well as the nested <include>, <exclude> and <patternset> elements.

DVSL supports the use of a <tool> element which is used to pass values to the DVSL toolbox configuration.

All Velocity messages are routed through Ant's logging system but will only be output if their level exceeds that of Ant's current logging level. By default, this means Velocity informational messages are suppressed while warning and error messages are output. The following table shows the mapping between Ant logging options and the corresponding levels of Velocity messages which are output.

Ant Logging Option Velocity Messages Output
-quiet errors
no option errors, warnings
-verbose errors, warnings, informational
-debug errors, warnings, informational, debug

If the logfile attribute is specified to this task, all Velocity messages are written to the specified log file without regard to any logging option specified to Ant.

Parameters

Attribute Description Required
basedir where to find the source XML file, default is the project's basedir. No
destdir directory in which to store the results. Yes, unless in and out have been specified.
extension desired file extension to be used for the targets. If not specified, the default is ".html". No
style name of the stylesheet to use - given either relative to the project's basedir or as an absolute path Yes
classpath classpath to use when loading toolbox and velocity configuration classes. No
classpathref the classpath to use, given as reference to a path defined elsewhere. No
force Recreate target files, even if they are newer than their corresponding source files or the stylesheet. No
includes comma separated list of patterns of files that must be included. All files are included when omitted. No
includesfile the name of a file. Each line of this file is taken to be an include pattern No
excludes comma separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. No
excludesfile the name of a file. Each line of this file is taken to be an exclude pattern No
defaultexcludes indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. No
in specifies a single XML document to be styled. Should be used with the out attribute. No
out specifies the output name for the styled result from the in attribute. No
outputencoding encoding to be used for output files. If not specified, the default is UTF-8. No
logfile log file for Velocity messages. The default is to log through Ant's logging system but limit output based on Ant's logging level. Specifying this attribute causes all Velocity messages to be sent to the specified file instead. No
toolboxfile specifies the toolbox properties file name. No
velocityconfigclass specifies a class to load which sets Velocity properties. The class must implement the java.util.Map interface. No
validatingparser specifies that the parser for the input XML should validate. Boolean valued, default is false No

Parameters specified as nested elements

classpath

Classpath to use when loading toolbox and velocity configuration classes. This is defined using a path-like structure.

tool

Set a toolbox property. Properties specified with this nested element override those defined in a properties file specified by the toolboxfile attribute.

Parameters
Attribute Description Required
name Name of the toolbox property Yes
value Value of the toolbox property. Yes

velconfig

Velconfig is used to set a Velocity configuration property. Properties specified with this nested element override those defined in a class loaded via the velocityconfigclass attribute.

Parameters
Attribute Description Required
name Name of the Velocity configuration property Yes
value Value of the Velocity configuration property. Yes

Application Values

DVSL as of v0.43, supports applications making application specific values available via the $context API. (Please see DVSL User Guide.) When using Ant and DVSL, the following values are accessable :

  • infilename : the current input file name, sans path. Ex. 'input.xml'. This can be accessed via $context.getAppValue('infilename')
  • outfilename : the current output file name, sans path. Ex. 'output.html'. This can be accessed via $context.getAppValue('outfilename')

Declaring the DVSL Task in the build file

This task as with any other task not shipped with Ant must be defined in the build file using a <taskdef> declaration. For example, the following declaration associates a task named <dvsl> with the class org.apache.dvsl.DVSLTask. In addition, the required jars for DVSL support are specified in classpath using a FileSet. 
<taskdef name="dvsl" classname="org.apache.dvsl.DVSLTask">
  <classpath>
    <fileset dir="${lib.dir}">
      <include name="velocity-dvsl-*.jar" />
      <include name="velocity-dep-*.jar" />
      <include name="dom4j-*.jar" />
    </fileset>
  </classpath>
</taskdef>

Examples

Simple case running a transformation on all files in a directory: 
<dvsl basedir="doc" destdir="build/doc"
      extension=".html" style="style/apache.dvsl" />

Using parameters to set Toolbox and Velocity properties:

<dvsl basedir="doc" destdir="build/doc"
      extension=".html" style="style/apache.xsl"
      classpath=".">
  <tool name="toolbox.string.mystring" value="Some arbitrary text" />
  <tool name="toolbox.tool.footool" value="Footool" />
  <velconfig name="runtime.log" value="${basedir}/dvsl.log" />
</dvsl>