Skip to content
This repository

Marklogic Ant Tasks

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 lib
Octocat-spinner-32 misc
Octocat-spinner-32 releases
Octocat-spinner-32 sample-build
Octocat-spinner-32 src
Octocat-spinner-32 tests
Octocat-spinner-32 README.markdown
Octocat-spinner-32 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 Name Description
load Loads content from output of a fileset to MarkLogic Database
delete Deletes content from MarkLogic database
query Allows Adhoc query or set of queries to be run against a MarkLogic instance residing in a filesystem
invoke Invoke an XQuery Module against a MarkLogic database
spawn Spawns an XQuery Module against a MarkLogic database
Experimental Tasks
corb Executes a corb job against MarkLogic database
xqsync Generates 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

Attribute Description Required
xccurl XCC Connection string Yes
failonerror Determines wether an exception will cause task to fail No
contenttype Sets 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 Name Description Required
docset Defines the uri where the content will be loaded and additional permissions, collections and fileset residing on local filesystem. Yes
failonerror Determines wether an exception will cause task to fail No
bulkload Determines 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

Attribute Description Required
xccurl XCC Connection string Yes
documents Comma Seperated List of document uris to delete No
directories Comma Seperated List of directory uris to delete No
collections Comma Seperated List of collection names to delete Yes
failonerror Determines wether an exception will cause task to fail No
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

Attribute Description Required
xccurl XCC Connection string Yes
failonerror Determines wether an exception will cause task to fail No
query XQuery code to execute. At least the query attribute or a fileset is required to execute a given query task. No
output File system path to write output for queries. If not set will write output to standard output No
appendOutput Boolean value to determine if any output is appended to the output uri value No
default=false

Nested Element Parameters

Element Description Required
fileset When passed allows execution of multiple xquery files given a file vector No
paramset Allows 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

Attribute Description Required
xccurl XCC Connection string Yes
failonerror Determines wether an exception will cause task to fail No
moduleuri The location of the URI relative to the module root defined in the appserver Yes

Nested Element Parameters

Element Description Required
paramset Allows parameters to be passed to query or query files. No
options Invoke options to control invocation No

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

Attribute Description Required
xccurl XCC Connection string Yes
failonerror Determines wether an exception will cause task to fail No
moduleuri The location of the URI relative to the module root defined in the appserver Yes

Nested Element Parameters

Element Description Required
paramset Allows 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

Attribute Description Required
xccurl XCC Connection string Yes
failonerror Determines wether an exception will cause task to fail No
default=false
module location of the file Module to execute when processing a given document uri. The file must be a path located on the filesystem. Yes
collection collection for uri selection No
urismodule Custom uri module to invoked to select uris to process No
moduledb Modules database to use when executing the module No
threads Number of threads to run in parrallel when processing requests No
default=1
install Determines whether modules should be installed before executing the corb process. It is important to note if the modules URI No
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

Attribute Description Required
failonerror Determines wether an exception will cause task to fail No

Example:

  <ml:xqdoc/>

Nested Elements

<docset> Element

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

Parameters

Attribute Description Required
destdir The destination directory appended to all loaded documents Yes

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

Element Description Required
permission Sequence of permission elements Yes

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

Attribute Description Required
role Name of role for given permission Yes
permission Capabality for given permission. Can be 'read', 'insert', 'update','execute'. Only one role/permission pair is allowed per <permission/> element Yes

Example:

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

<collectionset> Element

Nested Element Parameters

Element Description Required
collection One or more collection elements Yes

Example:

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

<collection> Element

Attribute Parameters

Attribute Description Required
name Name of a collection to add Yes

Example:

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

<options> Element

Attribute Parameters

Attribute Description Required
cacheresults No
xqueryversion No
effectivePointInTime No
locale No
autoRetryDelayMillis No
maxAutoRetry No
requestName No
requestTimeLimit No
resultBufferSize No
timeoutMillis No
timezone No

Example:

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

<paramset> Element

Nested Element Parameters

Element Description Required
param List of parameters elements to pass to query,invoke or spawn task Yes

Example:

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

<param> Element

Description: Defines a parameter definition.

Attribute Parameters

Attribute Description Required
name Name of variable Yes
ns Namespace of the variable. Yes
type Type of the variable. No, will cast to string if not set
value Value of the variable Yes

Example:

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