#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 <load/> 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"/>