Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Marklogic Ant Tasks
XQuery XSLT JavaScript Java
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
misc
releases Changed Default behavior of load to not do a full bulk load of all fi…
sample-build
src/com/marklogic/ant/taskdefs
tests
README.markdown Added documentation on bulkload on load task
build.xml

README.markdown

Marklogic ANT Tasks Library

Provides various support for MarkLogic Functionality to use in Build Deployment Scenarios

Dependencies:


  • Latest Marklogic xcc.jar
  • Task Specific Dependencies:
    • corb task dependencies : corb.jar
    • xqdoc task dependencies : xqdoc-ml.jar;saxon9he.jar;antlr-2.7.5.jar

Using MarkLogic Ant Tasks

The following is a basic project that defines the required information for ant to process your MarkLogic Ant Tasks.

 <!--Define ml namespace in project root element-->
  <project name="ML Ant Tasks" xmlns:ml="http://www.marklogic.com/ant">
    >
    <!--Set you the classpath to where your mlant.jar file is located.
        Include any other dependent jar files required to execute tasks
        noted in Dependencies section.
    -->
    <path id="mlant-classpath">
        <fileset dir="${lib-dir}">
              <include name="xcc.jar" />
              <include name="mlant.jar" />
              <include name="corb.jar"/>
              <include name="saxon9he.jar"/>
              <include name="xqdoc-ml.jar"/>
              <include name="antlr-2.7.5.jar"/>
              <include name="xqdoc-ml.jar"/>
        </fileset>
    </path>
    <!--
       Setup the type definition and assign classpathref to mlant-classpath
    -->
    <typedef 
       uri="http://www.marklogic.com/ant" 
       resource="com/marklogic/ant/antlib.xml"
       classpathref="mlant-classpath"
    />
    <!--Optional: Set the property for xccstring used to connect to MarkLogic database-->
    <property name="xccstring" value="xcc://test:test@localhost:9090/Docs">

    <!--Create a target element and use the tasks-->
    <target name="test-query">
      <ml:query xccurl="${xccstring}" query="'Hello World'">
    </target>

    <!--Have Fun-->
  </project>

ANT Tasks

Task NameDescription
loadLoads content from output of a fileset to MarkLogic Database
deleteDeletes content from MarkLogic database
queryAllows Adhoc query or set of queries to be run against a MarkLogic instance residing in a filesystem
invokeInvoke an XQuery Module against a MarkLogic database
spawnSpawns an XQuery Module against a MarkLogic database
Experimental Tasks
corbExecutes a corb job against MarkLogic database
xqsyncGenerates XQSync documents against a list of files in a filesystem directory

<load> Task

Description: Load content from filesystem into MarkLogic database. Note the default behavior is to load each file as a single transaction. To load all files as a single transaction use the bulkLoad=true parameter.

Attribute Parameters

AttributeDescriptionRequired
xccurlXCC Connection stringYes
failonerrorDetermines wether an exception will cause task to failNo
contenttypeSets the default contentType for defined docset. This parameter is useful there is an unknown mimetype and you want to explicitly set the type. Value can be xml|binary|text. No,
default=false

Elements Nested Parameters

Element NameDescriptionRequired
docsetDefines the uri where the content will be loaded and additional permissions, collections and fileset residing on local filesystem.Yes
failonerrorDetermines wether an exception will cause task to failNo
bulkloadDetermines if the load task is done in a single transaction or multiple transactions. The default is false

Example (Complete): Loads a document into /test-dir/ from ../src directory using fileset vector. Additionally a set of permissions and collections are assigned to documents loaded.

  <ml:load xccurl="${xccstring}">
      <ml:docset destdir="/test-dir/">
          <ml:permissionset>
              <ml:permission role="nobody" permission="execute" />
              <ml:permission role="nobody" permission="insert" />
              <ml:permission role="nobody" permission="read" />
              <ml:permission role="nobody" permission="update" />
          </ml:permissionset>
          <ml:collectionset>
              <ml:collection name="collection1" />
              <ml:collection name="collection2" />
          </ml:collectionset>
          <fileset dir="../src" includes="**/*" />                
      </ml:docset>
  </ml:load>

<delete> Task

Description: Deletes files/directories/collections from MarkLogic database.

Attribute Parameters

AttributeDescriptionRequired
xccurlXCC Connection stringYes
documentsComma Seperated List of document uris to deleteNo
directoriesComma Seperated List of directory uris to deleteNo
collectionsComma Seperated List of collection names to deleteYes
failonerrorDetermines wether an exception will cause task to failNo
default=false

Example: Deletes files from various documents, directories, or collections

  <ml:delete xccurl="${xccstring}"
    documents="/path/to/doc1.xml,/path/to/doc2.xml"
    directories="/dir1/,/dir2/"
    collections="collection1,collection2"
    failonerror="false"
  />

<query> Task

Run AdHoc queries against Marklogic database. Queries can a single query using @query attribute or multiple queries by passing a <fileset/> element. The fileset files must be main modules in order to be executed.

Parameters

AttributeDescriptionRequired
xccurlXCC Connection stringYes
failonerrorDetermines wether an exception will cause task to failNo
queryXQuery code to execute. At least the query attribute or a fileset is required to execute a given query task.No
outputFile system path to write output for queries. If not set will write output to standard outputNo
appendOutputBoolean value to determine if any output is appended to the output uri valueNo
default=false

Nested Element Parameters

ElementDescriptionRequired
filesetWhen passed allows execution of multiple xquery files given a file vectorNo
paramsetAllows parameters to be passed to query or query files.No

Example 1:(Simple Query)

   <ml:query xccurl="${xccstring}" query="1 + 2">

Returns

3

Example 2:(Passing External Arguments against query attribute)

    <ml:query xccurl="${xccstring}" query="
    declare variable $NAME as xs:string external;
    declare variable $TIMES as xs:integer external;
    for $in in (1 to $TIMES)
    return $NAME    
    ">
    <ml:paramset>
        <ml:param name="NAME" ns="" type="string" value="Michael"/>
        <ml:param name="TIMES" ns="" type="integer" value="3"/>
    </ml:paramset>
    </ml:query>

Returns

 Michael
 Michael
 Michael

Example 3: (Passing External Arguments to multiple xquery modules via a fileset) Same as Example 2 except the query is saved in test-parameters.xqy

    <ml:query xccurl="${xccstring}">
    <fileset file="${basedir}/testcases/test-parameters.xqy"/>
    <ml:paramset>
        <ml:param name="NAME" ns="" type="string" value="Douglass"/>
        <ml:param name="TIMES" ns="" type="integer" value="3"/>
    </ml:paramset>
    </ml:query>

Returns

 Douglass
 Douglass
 Douglass

<invoke> Task

Description: Invokes a mainModule at a given uri. The module must exists in the modules database configured for the app-server.

Attribute Parameters

AttributeDescriptionRequired
xccurlXCC Connection stringYes
failonerrorDetermines wether an exception will cause task to failNo
moduleuriThe location of the URI relative to the module root defined in the appserverYes

Nested Element Parameters

ElementDescriptionRequired
paramsetAllows parameters to be passed to query or query files.No
optionsInvoke options to control invocationNo

Example:

    <ml:invoke xccurl="${xccstring}" moduleUri="test/test.xqy">
        <ml:paramset>
           <ml:param name="foo" ns="" type="string" value="Douglass"/>
        </ml:paramset>
    </ml:invoke>

<spawn> Task

Description : Spawns a task on the Marklogic Task Server against a given moduleUri. The moduleUri must exist in the modules database for the appserver.

Parameters

AttributeDescriptionRequired
xccurlXCC Connection stringYes
failonerrorDetermines wether an exception will cause task to failNo
moduleuriThe location of the URI relative to the module root defined in the appserverYes

Nested Element Parameters

ElementDescriptionRequired
paramsetAllows parameters to be passed to query or query files.No

Example 1: Spawns the 'test/test.xqy' passing parameter name foo.

    <ml:spawn xccurl="${xccstring}" moduleUri="test/test.xqy">
        <ml:paramset>
            <ml:param name="foo" ns="" type="string" value="Douglass"/>
        </ml:paramset>
    </ml:invoke>

<corb> Task

Description: Executes a Corb task. This is a wrapper for the corb.jar. The latest version of corb.jar can be found at here: https://github.com/marklogic/corb

Parameters

AttributeDescriptionRequired
xccurlXCC Connection stringYes
failonerrorDetermines wether an exception will cause task to failNo
default=false
modulelocation of the file Module to execute when processing a given document uri. The file must be a path located on the filesystem. Yes
collectioncollection for uri selectionNo
urismoduleCustom uri module to invoked to select uris to processNo
moduledbModules database to use when executing the moduleNo
threadsNumber of threads to run in parrallel when processing requestsNo
default=1
installDetermines whether modules should be installed before executing the corb process. It is important to note if the modules URINo
default=false

Example:

<ml:corb xccurl="${xccstring}" 
    collection="" 
    module="${basedir}/tests/corb/uri-logger.xqy"
    moduledb="Documents"
    moduleroot="/"
    threads="4"
    install="false" 
/>

<xqdoc> Task

Attribute Parameters

AttributeDescriptionRequired
failonerrorDetermines wether an exception will cause task to failNo

Example:

  <ml:xqdoc/>

Nested Elements

<docset> Element

Description : Sets the directory uri location for loading content into database via ml:load task.

Parameters

AttributeDescriptionRequired
destdirThe destination directory appended to all loaded documentsYes

Example:

      <ml:docset destdir="/test-dir/">
          <ml:permissionset>
              <ml:permission role="nobody" permission="execute" />
              <ml:permission role="nobody" permission="insert" />
              <ml:permission role="nobody" permission="read" />
              <ml:permission role="nobody" permission="update" />
          </ml:permissionset>
          <ml:collectionset>
              <ml:collection name="collection1" />
              <ml:collection name="collection2" />
          </ml:collectionset>
          <fileset dir="../src" includes="**/*" />                
      </ml:docset>

<permissionset> Element

Description: Defines set of permissions to assign using &lt;load/&gt; task

Nested Element Parameters

ElementDescriptionRequired
permissionSequence of permission elementsYes

Example:

    <ml:permissionset>
        <ml:permission role="nobody" permission="execute" />
        <ml:permission role="nobody" permission="insert" />
        <ml:permission role="nobody" permission="read" />
        <ml:permission role="nobody" permission="update" />
    </ml:permissionset>

<permission> Element

Description: Defines a permission to associate to a document when using <load/> task

Attribute Parameters

AttributeDescriptionRequired
roleName of role for given permissionYes
permissionCapabality for given permission. Can be 'read', 'insert', 'update','execute'. Only one role/permission pair is allowed per <permission/> elementYes

Example:

  <ml:permission role="role-name" permission="insert"/>

<collectionset> Element

Nested Element Parameters

ElementDescriptionRequired
collectionOne or more collection elementsYes

Example:

  <ml:collectionset>
     <ml:collection name="collection-name-1">
     <ml:collection name="collection-name-2">
  </ml:collectionset>

<collection> Element

Attribute Parameters

AttributeDescriptionRequired
nameName of a collection to addYes

Example:

  <ml:collection name="my-collection"/>

<options> Element

Attribute Parameters

AttributeDescriptionRequired
cacheresultsNo
xqueryversionNo
effectivePointInTimeNo
localeNo
autoRetryDelayMillisNo
maxAutoRetryNo
requestNameNo
requestTimeLimitNo
resultBufferSizeNo
timeoutMillisNo
timezoneNo

Example:

       <!--Documentation not complete-->
    <ml:options
       cacheResults="true"
       xqueryversion="1.0-ml"
    />

<paramset> Element

Nested Element Parameters

ElementDescriptionRequired
paramList of parameters elements to pass to query,invoke or spawn taskYes

Example:

    <ml:paramset>
        <ml:param name="foo" ns="" type="string" value="Douglass"/>
    </ml:paramset>

<param> Element

Description: Defines a parameter definition.

Attribute Parameters

AttributeDescriptionRequired
nameName of variableYes
nsNamespace of the variable.Yes
typeType of the variable.No, will cast to string if not set
valueValue of the variableYes

Example:

  <ml:param name="foo" ns="" type="string" value="Douglass"/>
Something went wrong with that request. Please try again.