<apidoc:module name="CPFModule" category="Content Processing Framework" bucket="CPF Functions" 
  xmlns:apidoc="http://marklogic.com/xdmp/apidoc"
  xmlns="http://www.w3.org/1999/xhtml" lib="cpf"
>
<apidoc:summary access="public">
<p>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.
</p>
<p>To use the CPF module as part of your own XQuery module, include the
following line in your XQuery prolog:
</p>
<p><code>import module namespace cpf = "http://marklogic.com/cpf"
         at "/MarkLogic/cpf/cpf.xqy";</code></p>
<p>The library namespace prefix <code>cpf</code> is <em>not</em> predefined in
the server.</p>
</apidoc:summary>

<apidoc:function name="success" type="cpf" lib="cpf" 
                 category="Content Processing Framework" bucket="CPF Functions">
  <apidoc: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
<code>$cpf:document-uri</code> and <code>$cpf:transition</code> as
parameters. If the document does not exist, do nothing.
<p>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.
</p>
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="docid" type="xs:string">
    The URI of the document.
    </apidoc:param>
    <apidoc:param name="transition" type="element(*, p:transition)?">
    The pipeline transition being executed.
    </apidoc:param>
    <apidoc:param name="override-state" type="xs:anyURI?">
    The next state of the document, overriding the transition state.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> empty-sequence() </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy";

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

  cpf:success( $cpf:document-uri, $cpf:transition, () )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="failure" type="cpf" lib="cpf" 
                 category="Content Processing Framework" bucket="CPF Functions">
  <apidoc: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 <code>$cpf:document-uri</code>,
<code>$cpf:transition</code>, and <code>$cpf:exception</code> as parameters.
If the document does not exist, do nothing. 

<p>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.
</p>
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="docid" type="xs:string">
    The URI of the document.
    </apidoc:param>
    <apidoc:param name="transition" type="element(*, p:transition)?">
    The pipeline transition being executed.
    </apidoc:param>
    <apidoc:param name="exception" type="node()?">
    The exception leading to the processing failure, if any.
    </apidoc:param>
    <apidoc:param name="override-state" type="xs:anyURI?">
    The next state of the document, overriding the transition state.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> empty-sequence() </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy";

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

  cpf:failure( $cpf:document-uri, $cpf:transition, $cpf:exception, () )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="check-transition" type="cpf" lib="cpf" 
                 category="Content Processing Framework" bucket="CPF Functions">
  <apidoc:summary>
<p>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.
</p>
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="docid" type="xs:string">
    The URI of the document.
    </apidoc:param>
    <apidoc:param name="transition" type="element(*, p:transition)?">
    The pipeline transition being executed.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> xs:boolean </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy";

  declare variable $cpf:document-uri as xs:string external;
  declare 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, $e, () )
     }
  else ()
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="document-get-state" type="cpf" lib="cpf" 
                 category="Content Processing Framework" bucket="CPF Functions">
  <apidoc:summary>
Determine the document's current state, if any.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="doc" type="xs:string">
    The URI of the document.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> xs:anyURI? </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy";

  cpf:document-get-state( "/myDocs/example.xml" )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="document-set-state" type="cpf" lib="cpf" 
                 category="Content Processing Framework" bucket="CPF Functions">
  <apidoc:summary>
Set the document's state to the given state.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="doc" type="xs:string">
    The URI of the document.
    </apidoc:param>
    <apidoc:param name="state" type="xs:anyURI">
    The new state of the document.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> empty-sequence() </apidoc:return>
  <apidoc:usage>
  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".
  </apidoc:usage>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-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" )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="document-get-processing-status" type="cpf" lib="cpf" 
                 category="Content Processing Framework" bucket="CPF Functions">
  <apidoc:summary>
Determine the document's current processing status, if any. The status 
will be one of "created", "updated", "deleted", "active", or "done".
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="doc" type="xs:string">
    The URI of the document.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> xs:string?</apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy";

  cpf:document-get-processing-status( "/myDocs/example.xml" )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="document-set-processing-status" type="cpf" lib="cpf" 
                 category="Content Processing Framework" bucket="CPF Functions">
  <apidoc:summary>
Set the document's processing status to the given value.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="doc" type="xs:string">
    The URI of the document.
    </apidoc:param>
    <apidoc:param name="processing-status" type="xs:string">
    The new processing status, one of "created", "updated", "deleted",
  "active", or "done". 
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> empty-sequence() </apidoc:return>
  <apidoc:usage>
  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.
  </apidoc:usage>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy";

  cpf:document-set-processing-status( "/myDocs/example.xml", 
 		                    "deleted" )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="document-get-last-updated" type="cpf" lib="cpf" 
                 category="Content Processing Framework" bucket="CPF Functions">
  <apidoc:summary>
Determine the date and time of the last update to the document's content, if
any. 
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="doc" type="xs:string">
    The URI of the document.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> xs:dateTime?</apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy";

  cpf:document-get-last-updated( "/myDocs/example.xml" )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="document-set-last-updated" type="cpf" lib="cpf" 
                 category="Content Processing Framework" bucket="CPF Functions">
  <apidoc:summary>
Set the date and time of the document's last update.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="doc" type="xs:string">
    The URI of the document.
    </apidoc:param>
    <apidoc:param name="last-updated" type="xs:dateTime">
    The date and time at which the document was last updated, typically
    fn:current-dateTime().
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> empty-sequence() </apidoc:return>
  <apidoc:usage>
  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.
  </apidoc:usage>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-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() )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="document-get-error" type="cpf" lib="cpf" 
                 category="Content Processing Framework" bucket="CPF Functions">
  <apidoc:summary>
  Fetch a trace of the error that caused the document's processing to fail, if
  any. 
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="doc" type="xs:string">
    The URI of the document.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> node()? </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace cpf = "http://marklogic.com/cpf" 
		  at "/MarkLogic/cpf/cpf.xqy";

  cpf:document-get-error( "/myDocs/example.xml" )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="document-set-error" type="cpf" lib="cpf" 
                 category="Content Processing Framework" bucket="CPF Functions">
  <apidoc:summary>
Set the document's error trace to the given value.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="doc" type="xs:string">
    The URI of the document.
    </apidoc:param>
    <apidoc:param name="error" type="node()?">
    The error causing processing failure, or empty to erase the existing trace.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> empty-sequence() </apidoc:return>
  <apidoc:usage>
  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.
  </apidoc:usage>
</apidoc:function>
</apidoc:module>
