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

Permission modification string. Use either Unix-style syntax like rwxrwx--- or additive/subtractive syntax like [user|group|other]=[+|-][read|write|execute], comma separated.

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>