# WebDAV ant tasks

Tasks for Jakarta Ant for dealing with WebDAV repositories.

Tested with ant 1.6.1.

Library dependencies:

- Jakarta Commons HTTP Client
- Jakarta Slide WebDAV Client library
- Jakarta Commons Logging library

### Task definitions

Copy the four java libraries to your `${ANT_HOME}/lib` directory. And choose on of the following options to declare the WebDAV tasks.

Way 1: Declare the tasks in like the following. Daclare any name and use the name for the tasks described below.

     <target name="declare-tasks">
       <taskdef name="davput" classname="org.apache.webdav.ant.taskdefs.Put"/>
       <taskdef name="davget" classname="org.apache.webdav.ant.taskdefs.Get"/>
       <taskdef name="lock"   classname="org.apache.webdav.ant.taskdefs.Lock"/>
       <taskdef name="unlock" classname="org.apache.webdav.ant.taskdefs.Unlock"/>
       <taskdef name="mkcol"  classname="org.apache.webdav.ant.taskdefs.Mkcol"/>
       <taskdef name="davdelete" classname="org.apache.webdav.ant.taskdefs.Delete"/>
       <taskdef name="proppatch" classname="org.apache.webdav.ant.taskdefs.Proppatch"/>
       <taskdef name="davcopy" classname="org.apache.webdav.ant.taskdefs.Copy"/>
       <taskdef name="davmove" classname="org.apache.webdav.ant.taskdefs.Move"/>
     </target>

Way 1a.

      <target name="declare-tasks">
        <taskdef resource="org/apache/webdav/ant/taskdefs.properties"/>
      </target>

Way 2: Declare the namespace `antlib:org.apache.webdav.ant`, e.g. at the `project` element of your `build.xml`.

      <project name="site-update"
               default="upload"
               xmlns:dav="antlib:org.apache.webdav.ant">
        <target name="uplaod"
          <dav:put url="http://${DAV.server}/${DAV.root}"
                   userid="${DAV.user}" password="${DAV.password}"
                   lock="true" overwrite="false">
            <dav:fileset dir="site">
              <dav:include name="**/*.html"/>
            </dav:fileset>
          </dav:put>
        </target>
      </project>

As you can see you use the prefix declared for the namespace `antlib:org.apache.webdav.ant` for all WebDAV ant tasks and for all its children. (The later I didn't understand, but without it doesn't work.)

## common attributes

All of the ant tasks described below have the following attributes.

Attribute | Description | Required
url | The WebDAV URL to work on. | Yes.
userid | The username for authentication. | No.
password | Thes users password for authentication. | No.
verbose | Makes the task as verbose as with ants -v option. Defaults to `false`. | No.

## davget, dav:get

#### Description

Retrieves a file a WebDAV-fileset from a WebDAV server and stored it in a local directory.

Attribute | Description | Required
toDir | The local directory where to store the resources retrieved. | Yes. Either todir of tofile must be specified.
toFile | A filename where to store the resource given directly by `url` attribute.
overwrite | If set to `true` WebDAV resources are overwritten without any test. Otherwise they are overwritten only if its `getlastmodified` property is less then the local last modified date. Defaults to `false`. | No.
encoding | Specifies the encoding of the files to be retrieved. This should be set when using filter, otherwise it is unused. | No.

#### Nested Elements

The files to be retrieved are specified by nested `davfileset`s.

This task supports filtering using nested `FilterSet`s. If filters are used the encoding attribute should be set.

#### Examples

      <davget url="http://any.host.com/DAV"
              userid="${DAV.user}" password="${DAV.password}"
              todir="tmp">
        <davfileset dir="any/collection">
          <include name="**/*.xml"/>
        </davfileset>
      </davget>

Retrieves all XML files from the DAV collection published under `http://any.host.com/DAV/any/collection`and its sub collections.

      <davget url="http://${DAV.server}/${DAV.root}/path/to/any/file.txt"
              userid="${DAV.user}" password="${DAV.password}"
              tofile="tmp/filterTest.txt" encoding="UTF-8"
              overwrite="true">
        <filterset>
          <filter token="XXX" value="YYY"/>
        </filterset>
      </davget>

Retrieves a single file and applies a filter to it.

## davput, dav:put

#### Description

Uploads local files to a WebDAV server.

Attribute | Description | Required
file | A single file to be uploaded | No.
lock | Specifies whether the root URL (given by the url attribute) is to be locked before uploading. Defaults to `true`. | No.
locktoken | Gives a locktoken to be used while writing. May be obtained with the `lock` task. | No.
overwrite | If set to `true` local files are overwritten without any test. Otherwise they are overwritten only if they are older then the WebDAV resource. Defaults to `false`. | No.
encoding | Specifies the encoding of the files to be retrieved. This should be set when using filter, otherwise it is unused. | No.

#### Nested Elements

Files to be uploaded are specified by nested `FileSet`s. If the `file` attribute is given no `FileSet`s are allowed.

This task supports filtering using nested `FilterSet`s. If filters are used the encoding attribute should be set.

`davput` also supports nested `zipfileset`s.

#### Examples

      <davput url="http://${DAV.server}/${DAV.root}/xx/yy/zz"
              userid="${DAV.user}" password="${DAV.password}">
        <fileset dir="${basedir}">
          <include name="**/*.xml"/>
        </fileset>
      </davput>

Uploads all XML files in the base directory that are newer then its version in the DAV collection. The `zz` collection is locked before reading and writing and unlocked if the task is finished.

      <davput url="http://${DAV.server}/${DAV.root}/x/y/z"
              userid="${DAV.user}" password="${DAV.password}"
              overwrite="true" encoding="UTF-8"
              file="filterTest.txt">
        <filterset>
          <filter token="FILTER" value="VALUE"/>
        </filterset>
      </davput>

Puts a single file to the given URL. If the resource at `/x/y/z` exists and is a collection the given file is puted as new member of this collection. If the resource is not a collection the file will replace the existing resource.

While uploading a filter is applied.

      <davput url="http://${DAV.server}/${DAV.root}/docs/"
         userid="${DAV.user}" password="${DAV.password}">
         <zipfileset src="docs.zip">
           <include name="**/*.xml"/>
         </zipfileset>
      </davput>

Uploads all XML files found in the zipfile `docs.zip`.

## mkcol, dav:mkcol

#### Description

Creates a WebDAV collection and all required parent collections.

Attribute | Description | Required
locktoken | Gives a locktoken to be used while writing. May be obtained with the `lock` task. | No.

#### Examples

      <mkcol url="http://${DAV.server}/xx/yy/zz"
             userid="${DAV.user}" password="${DAV.password}"/>

Creates a collection named `/xx/yy/zz`. If the collections `/xx` and `/xx/yy` do not exist they are created too.

## davcopy, dav:copy

#### Description

Copies/renames a resource on a single WebDAV-Server.

Attribute | Description | Required
destination | URL to which the source (given by the common `url` attribute) is to be copied. This URL may be relative to `url` or an absolute one. | Yes.
overwrite | Determines whether the destination is overwritten if it always exists. | No. Defaults to `false`.
depth | Determines whether the copy of collections is shallow (`0`)or deep (`infinity`). | No. Defaults to `infinity`.

#### Examples

       <davcopy url="http://${DAV.server}/DAV/resource1" verbose="true"
                userid="${DAV.user}" password="${DAV.password}"
                destination="http://${DAV.server}/DAV/copy_of_resource1"/>

Copies `resource` to `copy_of_resource`. If `resource` is a collection the whole content is copied too.

       <davcopy url="http://${DAV.server}/DAV/resource1" verbose="true"
                userid="${DAV.user}" password="${DAV.password}"
                destination="copy_of_resource1"/>

Does the same as the first example, but the destination is given relative.

## davmove, dav:move

#### Description

Moves/renames a WebDAV-resource.

Attribute | Description | Required
destination | URL to which the source (given by the common `url` attribute) is to be moved. This URL may be relative to `url` or an absolute one. | Yes.
overwrite | Determines whether the destination is overwritten if it always exists. | No. Defaults to `false`.

#### Examples

       <davmove url="http://${DAV.server}/DAV/resource1" verbose="true"
                userid="${DAV.user}" password="${DAV.password}"
                destination="http://${DAV.server}/DAV/resource2"/>

Renames the resource `resource1` to `resource2`.

       <davmove url="http://${DAV.server}/DAV/coll1/resource" verbose="true"
                userid="${DAV.user}" password="${DAV.password}"
                destination="/DAV/coll2/resource"/>

Moves the resource `resource` from collection `coll1` to `coll2` using a relative destination URL.

## davdelete, dav:delete

#### Description

Deletes a WebDAV resource or a set of resources.

Attribute | Description | Required
locktoken | Gives a locktoken to be used while writing. May be obtained with the `lock` task. | No.

#### Nested Elements

Resources to be deleted are given by nested `davfileset`s

#### Examples

      <davdelete url="http://${DAV.server}/DAV/"
                 userid="${DAV.user}" password="${DAV.password}">
        <davfileset dir="docs">
          <include name="**/*.xml"/>
        </davfileset>
      </davdelete>

Deletes all XML files in the `/DAV/docs` collection and its subcollections.

      <davdelete url="http://${DAV.server}/DAV/xx"
                 userid="${DAV.user}" password="${DAV.password}">
      </davdelete>

Deletes the resource `/DAV/xx`.

## proppatch, dav:proppatch

#### Description

Sets or removes properties on WebDAV resources. (experimental)

Attribute | Description | Required
locktoken | Gives a locktoken to be used while writing. May be obtained with the `lock` task. | No.

#### Nested Elements

Resources to be proppatch'ed are given by nested `davfileset`s. Without a `davfileset` the resource given by the `url` attribute is used.

##### set, remove

The `set` elements specifies a property to be set.

The `remove` elements specifies a property to be set.

Attribute | Description | Required
name | The name of the property . | Yes
namespace | The namespace of the property. Defaults to the DAV namespace (`DAV:`). | No
namespaceprefix | The prefix to be used in the DAV request for the namespace. This should only be needed in the rare case where the server expects a certain prefix. | No. Discouraged.
value (for `<set>` only) | The value of the property. Must not be given if the element contains text. | No.

#### Examples

      <proppatch url="http://${DAV.server}/DAV/test.txt"
                 userid="${DAV.user}" password="${DAV.password}">
         <set name="displayname" value="TEST.TXT"/>
      </proppatch>

Sets the `DAV:displayname` of the resource `DAV/test.txt`.

      <proppatch url="http://${DAV.server}/DAV/users/sl"
                 userid="${DAV.user}" password="${DAV.password}">
        <set name="email" namespace="imb">sl@itaw</set>
        <set name="displayname">stefan"</set>
        <remove name="address" namespace="imb"/>
      </proppatch>

Sets and removes some properties for a user resource.

      <proppatch url="http://${DAV.server}/DAV/pub"
                 userid="${DAV.user}" password="${DAV.password}">
         <set name="status" namespace="http://www.abb.com/" value="published"/>
         <davfileset/>
      </proppatch>

Sets the `{http://www.abb.com/}status` property on all resources in the `/DAV/pub` collection.

## lock, dav:lock

#### Description

Locks a WebDAV resource and stores the locktoken recieved in a property. Together with the `unlock` task this in intended to execute multiple WebDAV operations within the same lock.

Attribute | Description | Required
property | The name of the property where the locktoken is stored. | Yes.
timeout | The timeout of the lock in seconds. Defaults to 3600. | No.
ownerinfo | The owner info of the lock. Defaults to the `userid` or to `ant` if no userid is given. | No.
depth | The depth of the lock. Valid values are 0`` of `infinity`. Defaults to `infinity`. | No.

#### Examples

      <lock url="http://${DAV.server}/DAV/col"
            userid="${DAV.user}" password="${DAV.password}"
            property="locktoken"/>
      <mkcol url="http://${DAV.server}/DAV/col"
            userid="${DAV.user}" password="${DAV.password}"
            locktoken="${locktoken}"/>
      <davput url="http://${DAV.server}/DAV/col"
            userid="${DAV.user}" password="${DAV.password}"
            locktoken="${locktoken}" overwrite="false">
        <fileset dir="${basedir}">
          <include name="**/*.xml"/>
        </fileset>
      </davput>
      <unlock url="http://${DAV.server}/DAV/col"
            userid="${DAV.user}" password="${DAV.password}"
            locktoken="${locktoken}"/>

Locks the resource `/DAV` and stores the locktoken in the property `locktoken`. Executes two writing tasks with the same locktoken and unlocks the `/DAV` resource.

      <lock url="http://${DAV.server}/DAV"
            userid="${DAV.user}" password="${DAV.password}"
            property="locktoken"
            timeout="100" ownerinfo="${user}" depth="0"/>

Locks the resource `/DAV` for 100 seconds.

## unlock, dav:unlock

#### Description

Removes a lock. See `lock`.

Attribute | Description | Required
locktoken | Gives a locktoken of the lock to be removed. | Yes.

## davfileset

#### Description

Defines a group of WebDAV resources like a fileset for local files. Resources will be found in a collection tree determined by the root collection.

Resources in the set are specified by nested `<patternset>` `<include>`, `<includesfile>`, `<exclude>` or `<excludesfile>` elements. Without any child element a davfileset selects all resources below the root collection.

Attribute | Description | Required
dir | The root of the collection tree of this DavFileSet. This is a URL path relative to the URL of the surrounding task. | No.
casesensitive | Must the include and exclude patterns be treated in a case sensitive way? Defaults to `true`. | No.

#### Examples

      <davfileset dir="xx/yy">
        <include name="**/*.xml"/>
      </davfileset>

Selects all XML-files in the collection `xx/yy` below the URL given in the surrounding task.

      <patternset id="HtmlFiles">
        <include name="**/*.htm"/>
        <include name="**/*.html"/>
      </patternset>
      ...
      <davfileset>
        <patternset refid="HtmlFiles"/>
      </davfileset>

Selects all HTML sources below the URL given in the surrounding task.

      <davfileset dir="tmp"/>

Selects all resources in the `tmp` collections and its subcollections.