Ant Tasks
Introduction
eXist-db 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. Ant 1.8.2 is included in the eXist-db v2.0 distribution (if you have installed the eXist-db source code).
In your build file, import the eXist-db tasks as follows:
The classpath has to be defined before as follows
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 test
suite.
All tasks share the following common attributes:
- uri
-
An XMLDB URI specifying the database collection.
- ssl
-
Use SSL encryption when communicating with the database (default: false).
- 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
Storing Documents
The store task uploads and stores the specified documents into the database. Documents are specified through one or more filesets or as single source file. The following attributes are recognized:
- createcollection
-
If set to "true", 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. If it is unset, the type will be guessed from identified MIME type
- defaultmimetype
-
The default MIME type to use when the resource MIME type cannot be identified. If it is not set, binary (application/octet-stream) is the default.
- forcemimetype
-
Use this attribute when you want to force an specific MIME type. You should also set 'type' attribute, because resource kind guessing is disabled in this mode.
- mimetypesfile
-
The mime-types.xml file used by Ant eXist-db extension to identify the resource kind ("binary" or "xml") and MIME type of the documents to store. If it is not set, it will use a default one which is either at eXist-db HOME installation or bundled inside the Ant eXist-db extension
- srcfile
-
a single source file to store; use instead of filesets
- permissions
-
The permissions to be applied to 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 collection from the collection specified in the uri attribute.
- collection
-
The name of the collection which should be removed.
- resource
-
The name of the resource which should be removed.
Creating Empty Collections
The create task creates a single empty collection from the collection specified in the uri attribute.
- collection
-
The name of the subcollection which should be created.
- permissions
-
The permissions to be applied to 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.
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.
- resource
-
The name of the resource which should be checked.
List Resources/Collections
The list task returns a list of all resources and/or conditions in the collection specified in the uri attribute.
- 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
Copy a Resource/Collection
The copy task copies a resource or collection to a new destination.
- 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.
Move a Resource/Collection
The move task moves a resource or collection to a new destination.
- 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.
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 XPath 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.
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.
- destDir
-
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).
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 an URI, the query attribute or within the text content of the element. External variables declared in the XQuery can be set via one or more nested <variable> elements. You can also use the loadfile task to load the query from a file as in the following example:
The XQuery task accepts the following attributes in addition to the common ones:
- query
-
The query to be processed.
- queryUri
-
The query to be processed specified as 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.
Extract a Resource/Collection
The extract task dumps a resource or collection to a file or directory.
- 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.
- createdirectories
-
If "true" directories for sub-collections will be created Otherwise all extracted resources are written to the destination directory directly.
- type
-
Type of the resource to extract. Only "xml" is supported currently.
- overwrite
-
Set to true to force overwriting of files.
Backup
Creates a backup of the specified database collection on the local disk. For example:
creates a backup of the system collection.
- dir
-
The directory where backup files will be stored.
Restore
Restores database contents from a backup. The backup is read
from location specified by the dir or
file attributes. The dir attribute should point to
a directory containing a valid backup, i.e. a directory with a
__contents__.xml backup descriptor in it (e.g.
/home/me/Backup/090228/db
). The
file attribute should specify a zip archive which
contains 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.
- file
-
A zip file which contains the backup to be restored.
The following example restores the /db/home collection:
List Groups
This task lists all groups defined in eXist-db.
- outputproperty
-
Name of new property to write the output to.
- separator
-
Separator character for output, by default "," (comma).
List Users
This task lists all users defined in eXist-db.
- outputproperty
-
Name of new property to write the output to.
- separator
-
Separator character for output, by default ",".
Lock Resource
This task locks a resource for a user.
- resource
-
Name of resource to lock.
- name
-
Name of user to lock the resource for.
Add User
This task adds a user.
- name
-
Name of the new user.
- home
-
Name of collection that is home collection.
- secret
-
The password of the new user.
- primaryGroup
-
Name of primary group of the new user.
Remove User
This task removes a user.
- name
-
Name of the user to remove.
Change password of an User
This task changes the password of an user.
- name
-
Name of the user to change the password for.
- secret
-
The new password of the user.
You can of course also change your own password.
Add Group
This task adds a group.
- name
-
Name of the new group.
Remove Group
This task removes a group.
- name
-
Name of the group to remove.
Change resource permissions (chmod)
This task changes the permissions of a resource or collection.
- resource
-
Name of resource to modify. If no resource has been specified, chmod will operate on the collection as defined by the uri.
- permissions
-
Permission modification string. Use either Unix-style syntax, e.g.:
rwxrwx---
or additive/subtractive syntax, e.g.:
[user|group|other]=[+|-][read|write|execute]
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
-
Permission modification string. Use either Unix-style syntax, e.g.:
rwxrwx---
or additive/subtractive syntax, e.g.:
[user|group|other]=[+|-][read|write|execute]
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.
NOTE: The mode attribute on the chown ANT task is deprecated in favor of the "permissions" attribute. In the case that both "mode" and "permissions" are specfied, then the permissions attribute is the only one used.
Change Owner of resource/collection (chown)
This task changes the owner of a resource or collection.
- name
-
Name of user to own the resource/collection.
- group
-
Name of group to own the resource/collection.
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.
Example Ant script - Simple Data Migration
This example Ant script shows how to copy data from two different instances of eXist-db (remote or local).
To use supply your own values for the source and target user, pass, and url properties. Run the default target 'migrate' to copy data from one instance of eXist-db to another.
You can find this Ant script under the samples/ant directory.