Ant Tasks

(1Q20)

eXist-db provides a library for the Ant build tool to automate common system administration and operation tasks, like backup/restore or importing files. The latest version of eXist-db's Ant Tasks can be found on Maven Central as the artifact exist-ant.

Basic configuration

To prepare your Ant build script for working with eXist-db, do the following:

Add the eXist-db Ant tasks namespace to your script, preferably on the root <project> element and with prefix xdb:
```
<project xmlns:xdb="http://exist-db.org/ant" … >
```

Import the eXist-db tasks with Ivy and then add the following code:

<typedef resource="org/exist/ant/antlib.xml" uri="http://exist-db.org/ant"/>

Common attributes

All tasks share the following common attributes:

uri

An XMLDB URI specifying the database collection through XMLRPC. For instance xmldb:exist://localhost:8080/exist/xmlrpc/db/my-collection-my-resource.xml.

All collection and resource paths specified in the tasks are relative to this.

ssl

Use SSL encryption when communicating with the database (default: false).

user

The user to connect with (default: guest).

password

Password for the user (default: guest).

failonerror

Whether or not a error should stop the build execution (default: true).

Storing Documents

The store task uploads and stores documents into the database. Documents are specified as single source file or with Ant filesets:

<xdb:store xmlns:xdb="http://exist-db.org/ant"
    uri="xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare/plays"
    createcollection="true">
    <fileset dir="samples/shakespeare"> 
        <include name="*.xml"/>
        <include name="*.xsl"/>
    </fileset>
</xdb:store>
<xdb:store xmlns:xdb="http://exist-db.org/ant"
  uri="xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare/plays"
  createcollection="true" srcfile="samples/shakespeare/hamlet.xml"/>

createcollection: If set to true, non-existing base collections are automatically created.
createsubcollections: If set to true, non-existing sub-collections are automatically created.
type: The type of the resource: either xml or binary. If binary, documents will be stored as binary resources. If unset, the type will be guessed from identified MIME type.
defaultmimetype: The default MIME type to use when the resource's MIME type cannot be identified. Default: binary (application/octet-stream).
forcemimetype: Use this attribute when you want to force the MIME type. Also set type attribute (because resource kind guessing is disabled in this mode).
mimetypesfile: The mime-types.xml file used to identify the resource's kind (binary or xml) and MIME type. If not set eXist-db's default MIME types file will be used. An example MIME types file can be found in the eXist-db installation directory.
srcfile: a single source file to store. Use either this or Ant filesets.
permissions: The permissions for the resource, expressed in a Unix-style form, e.g. rwxr-xr-x. Permissions will be applied to the resource/collection after it is created.

Removing Documents/Collections

The remove task removes a single resource or a collection:

<xdb:remove xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare/plays" resource="hamlet.xml"/>

<xdb:remove xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare" collection="plays"/>

Attributes (use either collection or resource, not both):

collection: The name of the collection to remove.
resource: The name of the resource which should be removed.

Creating Empty Collections

The create task creates a single, empty, collection:

<xdb:create xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare" collection="plays"/>

collection: The name of the collection to create.
permissions: The permissions to be applied to the collection, expressed in a Unix-style form, e.g. rwxr-xr-x. Permissions will be applied to the collection after it is created.

Check Existence of Resource/Collection

The exist task is a condition that checks whether a resource or collection as specified in the uri attribute exists or not. An ant target can be executed conditionally, depending on the property set or not set by the condition.

<condition property="exists">
  <xdb:exist xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare/plays" resource="hamlet.xml"/>
</condition>

resource: The name of the resource to check. If you don't specify this, the existence of the collection in the uri attribute is checked.

List Resources/Collections

The list task returns a list of resources and/or collections:

<xdb:list xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare/plays" resources="true" outputproperty="resources"/>

<xdb:list xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare" collections="true" outputproperty="collections"/>

Attributes:

resources: If true returns a list of resources.
collections: If true returns a list of collections.
separator: Separator character for the returned list. Default: ",".
outputproperty: Name of the (new) Ant property for the result

Copy a Resource/Collection

The copy task copies a resource or collection:

<xdb:copy xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare/plays" resource="hamlet.xml" destination="sub"/>

<xdb:copy xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare" collection="plays" destination="sub"/>

Attributes (use either collection or resource, not both):

resource: Takes the name of the resource to copy.
collection: Takes the name of the collection to copy.
destination: Takes the name of the destination collection to copy to.
name: Takes the new name of the resource or collection.

Move a Resource/Collection

The move task moves a resource or collection:

<xdb:move xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare/plays" resource="hamlet.xml" destination="sub"/>

<xdb:move xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare" collection="plays" destination="sub"/>

Attributes (use either collection or resource, not both):

resource: Takes the name of the resource to move.
collection: Takes the name of the collection to move.
destination: Takes the name of the destination collection to move to.
name: Takes the new name of the resource or collection.

Process an XPath Expression

The xpath task executes an XPath expression on a single or a collection of XML documents.

<xdb:xpath xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc/db" query="/example-queries/query"/>

Attributes:

query: Takes the XPath expression to process.
resource: Run the XPath query on this resource instead of a collection.
count: If true, the number of results is returned (instead of the results themselves).
outputproperty: Name of the (new) property for returning the results of the query in.
destDir: Write the results of the query to this destination file. Care should be taken to get a well-formed document (one root tag!).
namespace: Optional XML namespace for the query.

If you don't specify an output property or destination file, the results are discarded.

Process an XQuery Expression

The xquery task executes an XQuery expression:

<loadfile property="xquery" srcFile="wzb.xq"/>
<xdb:xquery  xmlns:xdb="http://exist-db.org/ant"
    uri="xmldb:exist://localhost:8080/exist/xmlrpc/db" query="${xquery}"
    user="guest" password="guest-passwd">
      <variable name="alpha" value="aaa-alep" />
</xdb:xquery>

<xdb:xquery xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc/db" queryUri="http://www.example.com/query/xquery-task.xql" user="guest" password="guest-passwd">
  <variable name="beta" value="ϐ"/>
</xdb:xquery>

Attributes:

query: Takes the full query that should be processed.
queryUri: Takes the query to process, specified as a URI.
outputproperty: Name of the (new) property for returning the results of the query in.
destfile: Write the results of the query to this destination file. Care should be taken to get a well-formed document (one root tag!).
queryfile: The query to process, specified as a filename.

The XQuery may also be specified as text content of the element.

Passing variables to the XQuery script can be done using one or more nested <variable> child elements. Declare these variables in your XQuery script as external. For instance, a variable passed as <variable name="test" value="Yup"/> can be accessed in the XQuery script as declare variable $beta external;:

Extract a Resource/Collection

The extract task extracts XML resources or collections with XML resources to disk. Extraction of binary resources is not supported.

<xdb:extract xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare/plays" resource="hamlet.xml" destfile="/tmp/hamlet.xml"/>

<xdb:extract xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc/db/shakespeare/plays" destdir="/tmp" subcollections="true" createdirectories="true"/>

Attributes:

resource: The name of the resource to extract.
sub-collections: If true all sub-collections of the specified collection are extracted as well.
destfile: The name of the destination file to extract to on extracting a resource.
destdir: The name of a destination directory to extract to on extracting a collection.
createdirectories: If true directories for sub-collections will be created. Otherwise all extracted resources are written to the same destination directory.
type: Type of the resource to extract. Only xml is supported currently.
overwrite: Set to true to force overwriting of files.

Backup

The backup task creates a backup of the specified database collection on disk:

<xdb:backup xmlns:xdb="http://exist-db.org/ant" uri="${backup.uri}/db/system" dir="${backup.dir}" user="${backup.user}" password="${backup.pass}"/>

Attributes:

dir: The directory where the backup files will be stored.

Restore

The restore task restores database contents from a backup.

<xdb:restore xmlns:xdb="http://exist-db.org/ant" uri="xmldb:exist://localhost:8080/exist/xmlrpc" user="admin" dir="${backup.dir}/db/home"/>

Attributes (use either dir or file, not both):

dir: The directory (containing a __content__.xml file) to restore.
file: A zip file which contains the backup to be restored.

List User Groups

The groups task lists all user groups defined in eXist-db:

<xdb:groups xmlns:xdb="http://exist-db.org/ant" uri="${backup.uri}/db/system" outputproperty="groups"/>

Attributes:

outputproperty: Name of (new) property to write the output to.
separator: Separator character for the returned list. Default: ",".

List Users

The users task lists all users defined in eXist-db:

<xdb:users xmlns:xdb="http://exist-db.org/ant" uri="${backup.uri}/db/system" outputproperty="users"/>

Attributes:

outputproperty: Name of (new) property to write the output to.
separator: Separator character for the returned list. Default: ",".

Lock Resource

The lock task locks a resource for a specific user:

<xdb:lock xmlns:xdb="http://exist-db.org/ant" uri="${backup.uri}/db/shakespeare/plays" resource="hamlet.xml" name="guest"/>

Attributes:

resource: Takes the name of the resource to lock.
name: Takes the name of the user to lock the resource for.

Add User

The adduser task adds a user:

<xdb:adduser xmlns:xdb="http://exist-db.org/ant" uri="${backup.uri}/db" name="guest" secret="ToPSecreT" primaryGroup="users"/>

Attributes:

name: Takes the username of the new user.
home: Name of the new user's home collection.
secret: Takes the password for the new user.
primaryGroup: Name of primary user group for the new user.

Remove User

The rmuser task removes a user:

<xdb:rmuser xmlns:xdb="http://exist-db.org/ant" uri="${backup.uri}/db" name="guest"/>

Attributes:

name: Takes the username of the user to remove.

Change User Password

The password task changes a user's password.

<xdb:password xmlns:xdb="http://exist-db.org/ant" uri="${backup.uri}/db" user="dba-user" password="dba-user-SecreT" name="guest" secret="Guest-Changed-Secret"/>

Attributes:

name: Takes the username of the user to change the password for.
secret: Takes the new password for the user.

Add User Group

The addgroup task adds a user group.

<xdb:addgroup xmlns:xdb="http://exist-db.org/ant" uri="${backup.uri}/db" name="guest"/>

Attributes:

name: Takes the groupname of the new group.

Remove User Group

The rmgroup task removes a user group.

<xdb:rmgroup xmlns:xdb="http://exist-db.org/ant" uri="${backup.uri}/db" name="guest"/>

Attributes:

name: Takes the groupname of the group to remove.

Change Resource Permissions

The chmod task changes the permissions of a resource or collection.

<xdb:chmod xmlns:xdb="http://exist-db.org/ant" uri="${backup.uri}/db/shakespear/plays" resource="hamlet.xml" mode="group=-write,other=-write"/>

Attributes:

resource

Name of the resource to modify. If no resource has been specified, chmod will operate on the collection specified by the uri attribute.

permissions

For example, to set read and write permissions for the group, but not for others:

group=+read,+write,other=-read,-write

The new settings are OR-ed with the existing settings.

mode

DEPRECATED: Permission modification string. Use permissions instead.

Change Owner of resource/collection (chown)

The chown task changes the owner of a resource or collection.

<xdb:chown xmlns:xdb="http://exist-db.org/ant" uri="${backup.uri}/db/shakespeare/plays" resource="hamlet.xml" name="guest" group="guest"/>

Attributes:

name: Name of the user to own the resource/collection.
group: Name of the user group to own the resource/collection.

Database Shutdown

The shutdown task will shut down the database instance listening at the provided URI.

Example Ant script

This example Ant script shows how to copy data from two different instances of eXist-db (remote or local).

Supply your own values for the source and target user, pass, and url properties. You can find this Ant script under the $EXIST_HOME/exist-samples/src/main/resources/org/exist/samples/ant directory.

<project xmlns:xdb="http://exist-db.org/ant" name="exist-data-migrate" default="migrate">
  <description>
    Migrate data from one instance of eXist-db to another
  </description>
  <!-- edit these properties // -->
  <property name="p.exist.dir" value="/opt/eXist-1.0"/>
  <property name="p.source.exist.url" value="xmldb:exist://www.example.org:8080/exist/xmlrpc/db/"/>
  <property name="p.source.user" value="myusername"/>
  <property name="p.source.pass" value="myuserpass"/>
  <property name="p.target.exist.url" value="xmldb:exist://www.example.org:8680/exist/xmlrpc/db/"/>
  <property name="p.target.user" value="myotherusername"/>
  <property name="p.target.pass" value="myotheruserpass"/>
  <property name="p.export.dir" location="export"/>
  <!-- import eXist-db tasks -->
  <typedef resource="org/exist/ant/antlib.xml" uri="http://exist-db.org/ant">
    <classpath>
      <fileset dir="${p.exist.dir}/lib/core">
        <include name="*.jar"/>
      </fileset>
      <fileset dir="${p.exist.dir}/lib/endorsed">
        <include name="*.jar"/>
      </fileset>
      <fileset dir="${p.exist.dir}/lib/optional">
        <include name="*.jar"/>
      </fileset>
      <pathelement location="${p.exist.dir}/exist.jar"/>
      <pathelement location="${p.exist.dir}/exist-optional.jar"/>
    </classpath>
  </typedef>
  <target name="clean">
    <delete dir="${p.export.dir}"/>
    <mkdir dir="${p.export.dir}"/>
  </target>
  <target name="migrate" depends="extract-source, load-target">
    <echo message="migration complete"/>
  </target>
  <target name="extract-source" depends="clean" description="export xml from source eXist-db instance">
    <xdb:extract uri="${p.source.exist.url}" user="${p.source.user}" password="${p.source.pass}" destdir="${p.export.dir}"/>
  </target>
  <target name="load-target" description="store xml to target eXist-db instance">
    <xdb:store uri="${p.target.exist.url}" user="${p.target.user}" password="${p.target.pass}" createcollection="true" createsubcollections="true">
      <fileset dir="${p.export.dir}"/>
    </xdb:store>
  </target>
  <target name="check-env" description="check env and dependencies are installed">
  </target>
</project>

Ant Tasks

Basic configuration

Common attributes

Storing Documents

Removing Documents/Collections

Creating Empty Collections

Check Existence of Resource/Collection

List Resources/Collections

Copy a Resource/Collection

Move a Resource/Collection

Process an XPath Expression

Process an XQuery Expression

Extract a Resource/Collection

Backup

Restore

List User Groups

List Users

Lock Resource

Add User

Remove User

Change User Password

Add User Group

Remove User Group

Change Resource Permissions

Change Owner of resource/collection (chown)

Database Shutdown

Example Ant script

Contents