<apidoc:module name="LinksModule" category="Links" bucket="CPF Functions" 
  xmlns:apidoc="http://marklogic.com/xdmp/apidoc"
  xmlns="http://www.w3.org/1999/xhtml" lib="lnk"
>
<apidoc:summary access="public">
<p>The links module is installed as part of the Content Processing Framework.
These functions are used to manage the relationships among documents in the
database, for example, as between a binary source document and an XML document
generated by a conversion process from that source document.
The Content Processing Framework will use links to determine if related
documents should also be removed when a document is deleted from the
database. 
</p>
<p>To use the links module as part of your own XQuery module, include the
following line in your XQuery prolog:
</p>
<p><code>import module namespace lnk = "http://marklogic.com/cpf/links"
         at "/MarkLogic/cpf/links.xqy";</code></p>
<p>The library namespace prefix <code>lnk</code> is <em>not</em> predefined in
the server.</p>
</apidoc:summary>

<apidoc:function name="create" type="link" lib="lnk" 
                 category="Links" bucket="CPF Functions">
  <apidoc:summary>
Create a link between the two given documents with the given role labels 
and strength. An error is raised if either of the documents involved does
not exist or if the link would be invalid for some reason. This function 
will replace any existing link between those two documents with the new link.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="from" type="xs:string">
    The URI of the document at the tail of the link.
    </apidoc:param>
    <apidoc:param name="to" type="xs:string">
    The URI of the document at the head of the link.
    </apidoc:param>
    <apidoc:param name="role" type="xs:string">
    A label for the relationship of the head of the link to the tail of the
  link, one of "source", "consumer", "container",
  "variant", and "related".
    </apidoc:param>
    <apidoc:param name="rev-role" type="xs:string">
    A label for the reverse relationship of the tail of the link to the head of
   the link.
    </apidoc:param>
    <apidoc:param name="strength" type="xs:string">
    An indicator of the strength of the relationship between the two documents,
    either "strong" or "weak".
    </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 lnk = "http://marklogic.com/cpf/links" 
		  at "/MarkLogic/cpf/links.xqy";

  lnk:create( "/myDocs/example.xhtml", "/myDocs/example.doc", 
              "source", "conversion", "strong" ) 
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="insert" type="link" lib="lnk" 
                 category="Links" bucket="CPF Functions">
  <apidoc:summary>
 Insert the given link. An error is raised if either of the documents involved
 does not exist or if the link is invalid in some way. This function will
 replace any existing link between those two documents.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="link" type="element(lnk:link)">
    The link element.
    </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 lnk = "http://marklogic.com/cpf/links" 
		  at "/MarkLogic/cpf/links.xqy";

  lnk:insert( lnk:get( "/myDocs/fr/example.xhtml", "/myDocs/example.xhtml" ) )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="remove" type="link" lib="lnk" 
                 category="Links" bucket="CPF Functions">
  <apidoc:summary>
Remove the link between the two given documents and return the removed link. 
An error is raised if no such link exists. 
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="from" type="xs:string">
    The URI of the document at the tail of the link.
    </apidoc:param>
    <apidoc:param name="to" type="xs:string">
    The URI of the document at the head of the link.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> element(lnk:link) </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace lnk = "http://marklogic.com/cpf/links" 
		  at "/MarkLogic/cpf/links.xqy";

  lnk:remove( "/myDocs/example.xhtml", "/myDocs/example.doc" )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="get" type="link" lib="lnk" 
                 category="Links" bucket="CPF Functions">
  <apidoc:summary>
Find and return the link between the two documents, if any. This function
will check the properties of link and raise an error if they are 
inconsistent or incomplete in some way.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="from" type="xs:string">
    The URI of the document at the tail of the link.
    </apidoc:param>
    <apidoc:param name="to" type="xs:string">
    The URI of the document at the head of the link.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> element(lnk:link)? </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace lnk = "http://marklogic.com/cpf/links" 
		  at "/MarkLogic/cpf/links.xqy";

  lnk:get( "/myDocs/fr/example.xhtml", "/myDocs/example.xhtml" )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="from" type="link" lib="lnk" 
                 category="Links" bucket="CPF Functions">
  <apidoc:summary>
Find and return all the links from the given document to some other. 
This function will check the properties of the link and raise an error
if they are inconsistent or incomplete in some way.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="from" type="xs:string">
    The URI of the document at the tail of the link.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> element(lnk:link)* </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace lnk = "http://marklogic.com/cpf/links" 
		  at "/MarkLogic/cpf/links.xqy";

  for $link in lnk:from( "/myDocs/example.xhtml" )
  return $link/@to
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="to" type="link" lib="lnk" 
                 category="Links" bucket="CPF Functions">
  <apidoc:summary>
Find and return all the links to the given document from some other. 
This function will check the properties of the link and
raise an error if they are inconsistent or incomplete in some way.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="to" type="xs:string">
    The URI of the document at the head of the link.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> element(lnk:link)* </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace lnk = "http://marklogic.com/cpf/links" 
		  at "/MarkLogic/cpf/links.xqy";

  for $link in lnk:from( "/myDocs/example.xhtml" )
  return $link/@to
  ]]></pre>
  </apidoc:example>
</apidoc:function>


</apidoc:module>
