Libraries Task

Libraries

Description

Extensible library download mechanism, integrated with the Maven repository hosted at ibiblio.org.

This task can:

Download publicly published JAR files by version
Download JAR files from private file: or http: repositories
Cache the JAR files in a directory tree
Check for updates on a regular schedule
Build paths for compilation/execution
Fail the build if needed libraries are missing
Force an update of all libraries
Skip all downloading when offline

Parameters

Attribute	Description	Required
destDir	Destination directory for all downloads	No - default is ${user.home}/.maven/repository
offline	Flag to indicate that the system is offline, and that no downloads should take place.	No
flatten	flag to indicate that files should be flattened when downloaded	No -default false
usetimestamp	flag to indicate that timestamps should be compared when probing for updates.	No -default false
pathID	Name of a path to create containing all libraries in this declaration.	No
repositoryRef	Reference to a predefined repository	No

The default destination is that used by Maven, ${user.home}/.maven/repository . It can be overridden by setting the property ant.maven.repository.dir to a new location.

Nested Elements

library

This is the core of the system: a library to (potentially) download.

Attribute	Description	Required
project	Name of the project	Yes
version		Yes
archive	Name of the archive	No
destinationName	Filename of downloaded file	No, default remote name
suffix	Suffix of the archive	No -default ".jar"
enabled	flag to turn on or off specific download/use of an archive	No -default "true"

Repository

A repository is an Ant datatype that extends the Repository type. Ant only ships with one: the mavenrepository. If no repository is declared inline, and no repositoryref attribute set, the task will default to the maven repository.

Attribute	Description	Required
url	URL of the repository	No

Example:

    <repository ref="predefined.repository" />

mavenrepository

This connects to the Maven repository at ibiblio.org, or another chosen. Private repositories should copy the existing layout.

If no url is set, the default URL is http://ibiblio.org/maven, unless the property ant.maven.repository.url is set to something else.

Attribute Description Required

url URL of the repository No

checkMD5 Flag to turn on MD5 checking (unimplemented) No

username HTTP authentication username No

password HTTP authentication password Only if username is set

UpdatePolicies

Update policies are an (extensible) means of tuning the download, running code before and possibly after a download. They can enable or disable checks for individual files, skip the download process, or perform some post-download validation.

All policies have at least the common set of attributes; some may have more, in which case an updated attribute list is shown.

Attribute	Description	Required
enabled	Enabled flag	No -default "true"

Policies can be chained by listing them in order. Before an update/download takes place, all policies will be executed in order. After the download, the policies will be invoked in reverse order. The compound policy in such a situation is left to the experimentor, though reading the source will help.

Developers may add new policies (such as signing incoming files) by adding new datatypes extending the LibraryPolicy class.

noupdate

This policy will disable remote downloads when enabled. It is the policy equivalent of the offline flag.

Example:

    <noupdate />

forceupdate

This policy forces all libraries to be downloaded. If any download failed, the build will halt.

Example:

    <forceupdate />

timestamp

This policy tells Ant to check the repository to see if the files have changed using timestamp checks. Any files which are up to date will not be downloaded again. It is equivalent to setting the useTimestamp flag.

Example:

    <timestamp />

scheduledupdate

This policy tells Ant to check the repository to see if the files have changed, but only intermittently. An interval of the size of the schedule has to have passed, or the set of files to check has to have changed.

Attribute	Description	Required
enabled	Enabled flag	No -default "true"
markerFile	Name of a file to cache download history	Yes
Days	number of days between update checks	No
Hours	number of hours between update checks	No
Minutes	number of minutes between update checks	No

Example:

    <scheduledupdate days="1" hours="3" minutes="17" />

Check for an update every 27 hours, 17 minutes.

assertdownloaded

This policy is really for testing the library. It does not alter the download policy, but after any download has taken place, it verifies that the number of files downloaded matches the number expected.

Attribute	Description	Required
count	number of downloaded files expected.	Yes
enabled	Enabled flag	No -default "true"

Example:

    <assertdownloaded count="4" />

Examples

    <!--
    versions.properties says
    xdoclet.version=2.0
    commons-logging.version=1.0.3
    commons-collections.version=3.1
    -->
    <property file="versions.properties" />
    
    <libraries destDir="${lib.dir}" pathid="xdoclet.lib" >
      <mavenrepository />
      <library project="xdoclet" 
        version="${xdoclet.version}" />
      <library project="commons-logging"  
        version="${commons-logging.version}" />
      <library project="commons-collections"  
        version="${commons-collections.version}" />
    </libraries>

Load in versions from a file, then download the relevant archives. No update schedule is defined, but a path is created for insertion into a classpath. This property file driven dependency model is what we recommend over hard coding versions in a build file.

   <libraries destDir="build/lib" offline="${offline}" flatten="true">
      <mavenrepository url="${private.server}"/>
      <library project="doomed" archive="dead-code"
        suffix=".war"
        destinationName="product.war"
        version="LATEST" />
      <scheduledupdate markerfile="build/lib/marker.properties"
        hours="11" />
    </libraries>

Download doomed/dead-code.LATEST.war from a private repository, save it to build/lib/product.war with an update schedule of every eleven hours.