Introduction

This is a library of tasks/types to allow arbitrary resources to be, as transparently as possible, cached to the filesystem for use with tasks that require file resources: for example, many of the tasks that work with archives. You might need access to the contents of a JAR resource located at a given URL, by means of the unzip task. Alternatively, you might simply need access to a particular entry in the JAR as a zipentry. Long story short, the fscache Antlib allows you to expose a resource of arbitrary origin as a filesystem resource, and provides options which can be used or omitted to control the generation of the cache. In most cases accepting default options will cause temporary files to be generated on-demand in your system ${java.io.tmpdir} temp directory, and these files will be marked for deletion on VM exit. Other possible applications of this functionality include compiling Java source found e.g. in an archive using the javac task, or accessing nested archive resources by caching multiple levels from an outer archive file, e.g. reading a JAR resource from a WAR or, indirectly, an EAR file.

Requirements

The current version of this antlib is built against the Ant 1.8.x development version, to be found in Ant's Subversion trunk.

Where is it?

The source code for the library lives in the sandbox antlibs subspace of Ant's SVN - http://svn.apache.org/viewvc/ant/sandbox/antlibs/fscache/trunk/.

Installation

If you are building this from sources, run the antlib target and you'll get a file ant-fscache.jar.

There are several ways to use the tasks:

• The traditional way:

            <typedef resource="org/apache/ant/fscache/antlib.xml"
                     classpath="YOUR-PATH-TO/ant-fscache.jar"/>
          

  Using this approach the provided extensions will live in the default namespace. Note that the antlib is written in such a way that the default task/typenames (collect, single, preload) may be too generic and should either be explicitly overridden or used with a namespace.

• Similar, but assigning a namespace URI

            <typedef uri="antlib:org.apache.ant.fscache"
                     resource="org/apache/ant/fscache/antlib.xml"
                     classpath="YOUR-PATH-TO/ant-fscache.jar"/>
          

  Placing the properties extensions into their own namespace, usable e.g.:

            <project xmlns:fscache="antlib:org.apache.ant.fscache">
              ...
              <collect>
                <!-- other resources -->
              </collect>
          

  or a variation thereof.

• Using Ant's autodiscovery. Place ant-fscache.jar into a directory and use ant -lib DIR-CONTAINING-THE-JAR or copy it into ANT_HOME/lib - and then in your build file, simply declare the namespace on the project tag:

            <project xmlns:fscache="antlib:org.apache.ant.fscache">
          

  And all tasks of this library will automatically be available in the fscache namespace without any typedef.

Tasks and Types

Presents nested Resource Collections of arbitrary types such that they live in a single directory structure on the filesystem.

Parameters specified as nested elements

One or more nested Resource Collections must be specified.

A nested File Mapper may be specified.

Filesystem cache for a single nested Resource. The specific file used can be specified explicitly or derived using the name of the nested resource.

This type inherits from the file resource type and therefore supports its same attributes in addition to the following:

Parameters specified as nested elements

A single nested Resource is required.

Task to preload cached resources onto disk. This is necessary when one needs to use a filesystem cache with e.g. directory-based tasks such as Javac.

Parameters specified as nested elements

One or more nested Resource Collections must be specified. It is considered an error condition if any resource returned from these is not a cached resource.