[guide] <Task Methods>

Task Methods are special adapters for standard Ant tasks that let you use them as method implementations for certain SAM components like <artifactdef> and <reactiondef>. Normally, SAM definitions rely on antlib-based macrodefs to implement most of their functionality. However, there are many situations where other forms of method implementation become very useful. Task methods were originally created to facilitate one-step artifact definitions that are needed to produce artifacts that were required inputs to other artifact definitions. They are now a standard SAM method type. To use a task method you must prefix the method’s name with the marker “task:” string like: <method use="task:unzip"/>.

Every task method accepts a special locformat parameter that describes the caller’s preferred form for the returned artifact location. The two valid values for this parameter are “ospath” for a filesystem path (the default) and “ospathurl” for a file:// URL.

All of the available SAM task methods are described below; currently, there is no support for dynamic expansion of this set.

Task Method: mkdir

The task:mkdir method accepts all of the parameters of the standalone Ant <mkdir> task. Furthermore, to be consistent with the chkdir method, mkdir also accepts a path parameter as a synonym for the standard dir parameter. The artifact location is set to the target directory’s file path (the path parameter).

Task Method: chkdir

The task:chkdir method lets you ensure that a directory exists, is readable, is writable, and is scrubbed clean. You should think of the chkdir method as an enhanced mkdir that is better suited to managing existing directories. The artifact location is set to the target directory’s file path (the path parameter).

Task Methods: get, download

The task:get and task:download methods accept all of the parameters of the standalone Ant <get> task. The artifact location is set to the downloaded item’s path (the dest parameter).

Task Methods: cvs

The task:cvs method accept all of the parameters of the standalone Ant <cvs> task. The artifact location is set to the checked out item’s parent directory (the dest parameter or the calling project’s basedir).

Task Methods: unzip, unjar, gunzip, untar, bunzip, bunzip2

Each of the various expansion task methods accept all of the parameters of their matching standalone Ant tasks. In addition, each task also accepts a SAM-specific clean parameter which controls whether existing destination directories are first scrubbed before the archive is expanded. The artifact location is set to the destination directory’s path (the dest parameter).

Task Method: xslt

The task:xslt method accepts all of the parameters of the standalone Ant <xslt> task. To associate an <xmlcatalog> with the operation, use the SAM-specific xmlcatalogref parameter to point to an external catalog. The artifact location is set to the transformed item’s path (could be a directory or a file depending on the parameters to the xslt method).

Examples

The following snippet declares a set of directory artifact definitions based on the chkdir task method. Some directories are automatically created (like docs) while others must pre-exist (like stylesheets). This artifact definition is not terribly interesting by itself; however, it is very useful as a setup procedure for other, more complex, generation methods like the mkapidocs method used by the apidocs definition.

    <artifactdef name="directory">
       <defaults announce="no">
          <method use="task:chkdir"/>
       </defaults>
       <version name="docs">
          <parameter name="path" value="@{dist.dir}/docs"/>
       </version>
       <version name="reports" allowoverrides="yes">
          <parameter name="clean" value="yes"/>
          <parameter name="path" value="@{dist.dir}/reports"/>
       </version>
       <version name="stylesheets">
          <parameter name="path" value="@{conf.dir}/stylesheets"/>
          <parameter name="mustexist" value="yes"/>
       </version>
       <version name="css">
            <setup>
                <directory-stylesheets/>
            </setup>
          <parameter name="path" value="@{directory-stylesheets.loc}/css"/>
          <parameter name="mustexist" value="yes"/>
       </version>
       …
    </artifactdef>
    ...
    <artifactdef name="apidocs">
        <defaults>
            <method use="mkapidocs"/>
            <setup>
                <directory-docs/>
                <directory-css/>
            </setup>
            <parameter name="css" value="@{directory-css.loc}"/>
            <parameter name="html" value="@{directory-docs.loc}/apis"/>
        </defaults>
        …
    </artifactdef>

The following snippet declares a set of materials artifact definitions based on the unjar task method. The definition is then used by an AntUnit testsuite AllTests to generate the input data files for its tests. Also note that the testsuite uses the preceding directory artifact definition to generate its output directories.

    <artifactdef name="materials">
       <defaults>
          <method use="task:unjar"/>
          <parameter name="dest" value="@{root.dir}/materials"/>
          <parameter name="clean" value="${scrub.enabled}"/>
       </defaults>
       <version name="baseline">
          <parameter name="src" value="@{materials.dir}/baselines.jar"/>
       </version>
       …
    </artifactdef>
    ...
    <testsuite fullpackage="myproject.ebfs" name="AllTests">
        <setup>
            <directory-results clean="yes" artifactlocation="test.results"/>
            <directory-reports artifactlocation="test.reports"/>
            <materials-baseline artifactlocation="test.materials"/>
        </setup>
        <testselector categorylike="ebf"/>
        …
    </testsuite>

Related Topics

• The SAMS taskmethod Java package contains all of the builtin task method implementations.