MarkLogic Server
XQUERY API DOCUMENTATION
4.1
All XQuery Functions
MarkLogic Built-In Functions
XQuery Library Modules
CPF Functions
W3C-Standard Functions
  W3C XQuery Reference
W3C XQuery Functions
W3C XQuery Language
This page was generated
February  9,  2010
11:53  AM
XQuery Built-In and Modules Function Reference

Module: Content Processing Framework

The CPF module is installed as part of the Content Processing Framework. These functions are used by content processing actions to manage the state of the document as it is being processed.

To use the CPF module as part of your own XQuery module, include the following line in your XQuery prolog:

import module namespace cpf = "http://marklogic.com/cpf" at "/MarkLogic/cpf/cpf.xqy"

The library namespace prefix cpf is not predefined in the server.
Function Summary
cpf:check-transition Verify that the current transition is the correct one for the document.
cpf:document-get-error Fetch a trace of the error that caused the document's processing to fail, if any.
cpf:document-get-last-updated Determine the date and time of the last update to the document's content, if any.
cpf:document-get-processing-status Determine the document's current processing status, if any.
cpf:document-get-state Determine the document's current state, if any.
cpf:document-set-error Set the document's error trace to the given value.
cpf:document-set-last-updated Set the date and time of the document's last update.
cpf:document-set-processing-status Set the document's processing status to the given value.
cpf:document-set-state Set the document's state to the given state.
cpf:failure Concludes the state action in failure, advancing the state as defined by the state transition.
cpf:success Concludes the action successfully, advancing the state as defined by the transition.
Function Detail
cpf:check-transition(
$docid as xs:string,
$transition as element(*, p:transition)?
)  as   xs:boolean
Summary:

Verify that the current transition is the correct one for the document. If a document is touched from multiple threads certain race conditions may apply that will cause the lookup of the transition to end up out of sync with the transition action when it is actually executed. In this case the action should do nothing; not even call cpf:success or cpf:failure. Some other CPF thread has already done the work on this document.


Parameters:
$docid : The URI of the document.
$transition : The pipeline transition being executed.

Example: 
  xquery version "0.9-ml"
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy"

  define variable $cpf:document-uri as xs:string external
  define variable $cpf:transition as node() external

  if (cpf:check-transition( $cpf:document-uri, $cpf:transition )) then
     try {
        do-my-work(),
        cpf:success( $cpf:document-uri, $cpf:transition, () )
     } catch ($e) {
        cpf:failure( $cpf:document-uri, $cpf:transition, $cpf:exception, () )
     }
  else ()
cpf:document-get-error(
$doc as xs:string
)  as   node()?
Summary:

Fetch a trace of the error that caused the document's processing to fail, if any.

Parameters:
$doc : The URI of the document.

Example: 
  xquery version "0.9-ml"
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy"

  cpf:document-get-error( "/myDocs/example.xml" )
cpf:document-get-last-updated(
$doc as xs:string
)  as   xs:dateTime
Summary:

Determine the date and time of the last update to the document's content, if any.

Parameters:
$doc : The URI of the document.

Example: 
  xquery version "0.9-ml"
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy"

  cpf:document-get-last-updated( "/myDocs/example.xml" )
cpf:document-get-processing-status(
$doc as xs:string
)  as   xs:string
Summary:

Determine the document's current processing status, if any. The status will be one of "created", "updated", "deleted", "active", or "done".

Parameters:
$doc : The URI of the document.

Example: 
  xquery version "0.9-ml"
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy"

  cpf:document-get-processing-status( "/myDocs/example.xml" )
cpf:document-get-state(
$doc as xs:string
)  as   xs:anyURI?
Summary:

Determine the document's current state, if any.

Parameters:
$doc : The URI of the document.

Example: 
  xquery version "0.9-ml"
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy"

  cpf:document-get-state( "/myDocs/example.xml" )
cpf:document-set-error(
$doc as xs:string,
$error as node()?
)  as   empty-sequence()
Summary:

Set the document's error trace to the given value.

Parameters:
$doc : The URI of the document.
$error : The error causing processing failure, or empty to erase the existing trace.

Usage Notes:

In general, applications should not not need to set the error trace of a document. cpf:failure will automatically set this trace, and cpf:success will clear it.

cpf:document-set-last-updated(
$doc as xs:string,
$last-updated as xs:dateTime
)  as   empty-sequence()
Summary:

Set the date and time of the document's last update.

Parameters:
$doc : The URI of the document.
$last-updated : The date and time at which the document was last updated, typically fn:current-dateTime().

Usage Notes:

In general, applications should only set the update time of a document in the document update action and should set it to the current date and time to ensure consistency of processing.

Example: 
  xquery version "0.9-ml"
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy"

  cpf:document-set-last-updated( "/myDocs/example.xml", 
		               fn:current-dateTime() )
cpf:document-set-processing-status(
$doc as xs:string,
$processing-status as xs:string
)  as   empty-sequence()
Summary:

Set the document's processing status to the given value.

Parameters:
$doc : The URI of the document.
$processing-status : The new processing status, one of "created", "updated", "deleted", "active", or "done".

Usage Notes:

In general, applications should not not need to set the processing status of a document. If the document is currently being actively processed by the content processing framework, changing its processing status may have unexpected results. Manually setting the document's processing status should therefore be done only on documents whose processing status is "done". Setting the document's processing status to "updated" can be a means of triggering reprocessing; setting it to "deleted" can be a means of providing a soft-delete capability.

Example: 
  xquery version "0.9-ml"
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy"

  cpf:document-set-processing-status( "/myDocs/example.xml", 
 		                    "deleted" )
cpf:document-set-state(
$doc as xs:string,
$state as xs:anyURI
)  as   empty-sequence()
Summary:

Set the document's state to the given state.

Parameters:
$doc : The URI of the document.
$state : The new state of the document.

Usage Notes:

Setting a document's state may trigger content processing. If the document is currently being actively processed by the content processing framework, changing its state may have unexpected results. Manually setting the document's state should therefore be done only on documents whose processing status is "done".

Example: 
  xquery version "0.9-ml"
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy"

  cpf:document-set-state( "/myDocs/example.xml", 
                          "http://marklogic.com/states/reprocess" )
cpf:failure(
$docid as xs:string,
$transition as element(*, p:transition)?,
$exception as node()?,
$override-state as xs:anyURI?
)  as   empty-sequence()
Summary:

Concludes the state action in failure, advancing the state as defined by the state transition. The state action must call this method to indicate failure, passing the external variables $cpf:document-uri, $cpf:transition, and $cpf:exception as parameters. If the document does not exist, do nothing.

Side effects: Advances the document state to the transition's on-failure state, if any, and marks the document as processed in the current state.


Parameters:
$docid : The URI of the document.
$transition : The pipeline transition being executed.
$exception : The exception leading to the processing failure, if any.
$override-state : The next state of the document, overriding the transition state.

Example: 
  xquery version "0.9-ml"
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy"

  define variable $cpf:document-uri as xs:string external
  define variable $cpf:transition as node() external
  define variable $cpf:exception as node() external

  cpf:failure( $cpf:document-uri, $cpf:transition, $cpf:exception, () )
cpf:success(
$docid as xs:string,
$transition as element(*, p:transition)?,
$override-state as xs:anyURI?
)  as   empty-sequence()
Summary:

Concludes the action successfully, advancing the state as defined by the transition. The action must call this method to indicate completion of successful processing, passing the external variables $cpf:document-uri and $cpf:transition as parameters. If the document does not exist, do nothing.

Side effects: Advances the document state to the transition's on-success state, if any, and marks the document as processed in the current state.


Parameters:
$docid : The URI of the document.
$transition : The pipeline transition being executed.
$override-state : The next state of the document, overriding the transition state.

Example: 
  xquery version "0.9-ml"
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy"

  define variable $cpf:document-uri as xs:string external
  define variable $cpf:transition as node() external

  cpf:success( $cpf:document-uri, $cpf:transition, () )
 © Copyright 2002-2009 Mark Logic Corporation.    All rights reserved.