Ant Tasks

eXist provides a library for the Ant build tool to automate common tasks like backup/restore or importing a bunch of files. To use this library you need at least Ant 1.6, which is included in the eXist distribution (if you installed the eXist source code).

In your build file, import the eXist tasks as follows:

Example: Import the Tasks



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

The classpath has to be defined before as follows

Example: Definition of Classpath


<path id="classpath.core">
<fileset dir="${server.dir}/lib/core">
<include name="*.jar"/>
</fileset>
<pathelement path="${server.dir}/exist.jar"/>
<pathelement path="${server.dir}/exist-optional.jar"/>
</path>

Note

For a working example have a look into the file webapp/xqts/build.xml , which is used to prepare the database for running the xquery testsuite.

All tasks share the following common attributes:

uri

An XMLDB URI specifying the database collection.

initdb

Setting this option to "true" will automatically initialize a database instance if the uri points to an embedded database.

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

1. Storing Documents

The store task uploads and stores the specified documents into the database. Documents are specified through a fileset or as single source file. The following attributes are recognized:

Example: Storing Documents


<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", a non-existing base collections will be automatically created.

createsubcollections

If set to "true", any non-existing sub-collections will be automatically created.

type

The type of the resource: either "xml" or "binary". If "binary", documents will be stored as binary resources.

srcfile

a single source file to store, use instead of a fileset

2. Removing Documents/Collections

The remove task removes a single resource or collection from the collection specified in the uri attribute.

Example: Remove a Resource


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

Example: Remove a Collection


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

collection

The name of the subcollection which should be removed.

resource

The name of the resource which should be removed.

3. Creating Empty Collections

The create task creates a single empty collection from the collection specified in the uri attribute.

Example: Create a Collection


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

collection

The name of the subcollection which should be created.

4. Check Existence of Resource/Collection

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

Example: Check a Collection


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

resource

The name of the resource which should be checked.

5. List Resources/Collections

The list task returns a list of all resources and/or conditions in the collection specified in the uri attribute.

Example: List Resources


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

Example: List Collections


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

resources

If "true" lists resources

collections

If "true" lists collections

separator

separator character for the returned list, default is ","

outputproperty

name of a new ant property that will contain the result

6. Copy a Resource/Collection

The copy task copies a resource or collection to a new destination.

Example: Copy a Resource


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

Example: Copy a Collection


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

resource

The name of the resource which should be copied.

collection

The name of the collection which should be copied.

destination

The name of the destination collection to copy to.

name

The new name of the resource or collection in the destination.

7. Move a Resource/Collection

The move task moves a resource or collection to a new destination.

Example: Move a Resource


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

Example: Move a Collection


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

resource

The name of the resource which should be moved.

collection

The name of the collection which should be moved.

destination

The name of the destination collection to move to.

name

The new name of the resource or collection in the destination.

8. Process an XPath Expression

The xpath task executes an XPath expression. The output of the script is discarded, except when a destination file or output property is specified.

The XQuery may either be specified through the query attribute or within the text content of the element. A optional namespace may be used for the query.

Example: Process an XPath


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

The query task accepts the following attributes:

query

The query to be processed.

resource

query a resource instead of a collection.

count

If "true" the number of found results is returned instead of the results itself.

outputproperty

return the results as a string in a new property. In this case only the text of the result is returned.

destfile

write the results of the query to a destination file. In this case the whole XML fragments of the result is written to the file. Care should be taken to get a wellformed document (e.g. one root tag).

namespace

XML namespace to use for the query (optional).

9. Process an XQuery Expression

The xquery task executes an XQuery expression. This task is primarily intended for transformations. The output of the script is discarded when no destination file or output property is specified.

The XQuery may either be specified through the query attribute or within the text content of the element. You can also use the loadfile task to load the query from a file as in the following example:

Example: Process an XQuery


<loadfile property="xquery" srcFile="wzb.xq"/>
<xdb:xquery xmlns:xdb="http://exist-db.org/ant"
uri="xmldb:exist:///db" query="${xquery}"/>

The query task accepts the following attributes:

query

The query to be processed.

queryUri

The query to be processed specified a URI.

outputproperty

return the results as a string in a new property.

destfile

write the results of the query to a destination file.

queryfile

read the query from a file.

10. Extract a Resource/Collection

The extract task dumps a resource or collection to a file or directory.

Example: Extract a Resource


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

Example: Extract a Collection


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

resource

The name of the resource which should be extracted.

subcollections

If "true" all sub-collections of the specified collection are extracted as well

destfile

The name of the destination file to extract to. Only supported when a resource is extracted.

destdir

The name of a destination directory to extract to. Has to be used when extracting a collection.

createsubdirectories

If "true" directories for sub-collections will be created Otherwise all extracted resoruces are written to the destination directory directly.

type

Type of the resource to extract. Only "xml" is supported currently.

11. Backup

Creates a backup of the specified database collection on the local disk. For example:

Example: Backing up the System Collection


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

creates a backup of the system collection.

dir

The directory where backup files will be stored.

12. Restore

Restores database contents from a backup. The file attribute should point to one of the __contents__.xml files created by the backup. The base attribute specifies the base XMLDB URI (i.e. the URI without collections) used for the restore. The collection names will be read from the __contents__.xml file.

dir

A directory containing a __content__.xml file to be used for the restore.

The following example restores the /db/home collection:

Example: Restore a Collection


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

13. List Groups

This task lists all groups defined in eXist.

Example: Write list of groups to output property


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

outputproperty

Name of new property to write the output to.

separator

Separator character for output, by default ",".

14. List Users

This task lists all users defined in eXist.

Example: Write list of users to output property


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

outputproperty

Name of new property to write the output to.

separator

Separator character for output, by default ",".

15. Lock Resource

This task locks a resource for a user.

Example: Lock Resource


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

resource

Name of resource to lock.

name

Name of user to lock the resource for.

16. Add User

This task adds a user.

Example: Add User


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

name

Name of user to lock the resource for.

home

Name of collection that is home collection.

secret

The password of the new user.

primaryGroup

Name of primary group of the new user.

Note

This task does not seem to work currently!

17. Remove User

This task remove a user.

Example: Remove User


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

name

Name of user to lock the resource for.

18. Change Mod

This task remove a user.

Example: Chmod


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

resource

Name of resource to modify.

mod

Modification string.

19. Change Owner

This task changes the owner of a resource

Example: Chown


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

name

Name of user to own the resource/collection.

group

Name of group to own the resource/collection.

20. Database Shutdown

The shutdown task is required if you use the database in embedded mode. It will try to shut down the database instance listening at the provided URI.