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:
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 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 |
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:
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 |
The remove task removes a single resource or collection from the collection specified in the uri attribute.
collection |
The name of the subcollection which should be removed. |
---|---|
resource |
The name of the resource which should be removed. |
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. |
---|
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.
resource |
The name of the resource which should be checked. |
---|
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 |
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. |
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. |
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.
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). |
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:
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. |
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. |
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. |
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. |
---|
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:
This task lists all groups defined in eXist.
outputproperty |
Name of new property to write the output to. |
---|---|
separator |
Separator character for output, by default ",". |
This task lists all users defined in eXist.
outputproperty |
Name of new property to write the output to. |
---|---|
separator |
Separator character for output, by default ",". |
This task locks a resource for a user.
resource |
Name of resource to lock. |
---|---|
name |
Name of user to lock the resource for. |
This task adds a user.
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. |
This task does not seem to work currently!
This task remove a user.
name |
Name of user to lock the resource for. |
---|
This task remove a user.
resource |
Name of resource to modify. |
---|---|
mod |
Modification string. |
This task changes the owner of a resource
name |
Name of user to own the resource/collection. |
---|---|
group |
Name of group to own the resource/collection. |
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.