<apidoc:module name="PluginModule" category="Plugin" lib="plugin" 
bucket="XQuery Library Modules" xmlns:apidoc="http://marklogic.com/xdmp/apidoc">

<apidoc:summary category="Plugin" bucket="XQuery Library Modules">
<p>The Plugin API module contains functions that allow you to register plugins for use
   by MarkLogic Server. </p>	
<p>The Plugin API is installed as the following file:</p>
   <code><em>install_dir</em>/Modules/MarkLogic/plugin/plugin.xqy</code> 
 
<p>where <code><em>install_dir</em></code> is the directory in which 
   MarkLogic Server is installed.</p>
<p> To use the <code>plugin.xqy</code> module in your own XQuery modules, 
    include the following line in your XQuery prolog:</p>
<pre xml:space="preserve">
  <code>
   import module namespace plugin = "http://marklogic.com/extension/plugin"  
      at "/MarkLogic/plugin/plugin.xqy";
  </code></pre>
<p>The library uses the <code>plugin:</code> namespace, which is 
   <em>not</em> predefined in the server.</p>
<p>MarkLogic recommends enabling the URI Lexicon when using 
   Plugin; the URI lexicon will improve performance, especially when 
   the database grows to a large number of documents.</p>
</apidoc:summary>
 
<apidoc:function name="plugins" lib="plugin" category="Plugin" bucket="XQuery Library Modules" xmlns:apidoc="http://marklogic.com/xdmp/apidoc" >
  <apidoc:summary>
  This function returns unique IDs of the registered plugins 
  that have the specified capabilities. If no matching plugins are registered, an 
  empty sequence is returned.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="capability" type="xs:string*">
    A list of strings representing desired capabilities to match.  The plugin 
    must match all of the listed capabilities.  Specify an empty sequence to return
    the IDs of all of the plugins.
    </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 plugin = "http://marklogic.com/extension/plugin" 
      at "/MarkLogic/plugin/plugin.xqy";

  plugin:plugins("http://marklogic.com/appservices/infostudio/collector/abort")

  (: Lists all collector plugins with the 'abort' capability. :)
    ]]></pre>
  </apidoc:example>
</apidoc:function>
<apidoc:function name="enumerate" lib="plugin" category="Plugin" bucket="XQuery Library Modules" xmlns:apidoc="http://marklogic.com/xdmp/apidoc">
  <apidoc:summary>
  This function enumerates functions implementing all capabilities supported 
  by the given plugin. It returns a map, keyed on the capabilities.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="uri" type="xs:string">
    The unique identifier of the plugin.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return>map:map</apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[

  xquery version "1.0-ml"; 

  import module namespace plugin = "http://marklogic.com/extension/plugin" 
      at "/MarkLogic/plugin/plugin.xqy";

  plugin:enumerate("plugin:collector-filescan.xqy")

  (: Returns the capabilities map for the filescan collector. :)
    ]]></pre>
  </apidoc:example>
</apidoc:function>
<apidoc:function name="capability" lib="plugin" category="Plugin" bucket="XQuery Library Modules" xmlns:apidoc="http://marklogic.com/xdmp/apidoc">
  <apidoc:summary>
  This function returns a function pointer implementing a given capability from a 
  particular plugin.  If the plugin doesn't exist an exception is thrown. If the 
  plugin does exist but the capability isn't present, an empty sequence is returned.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="capability" type="xs:string">
    The desired capability to match.
    </apidoc:param>
    <apidoc:param name="uri" type="xs:string">
    The unique identifier of the plugin.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return>xdmp:function?</apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml"; 

  import module namespace plugin = "http://marklogic.com/extension/plugin" 
      at "/MarkLogic/plugin/plugin.xqy";

  plugin:capability(
     "http://marklogic.com/appservices/infostudio/collector/cancel", 
     "plugin:collector-filescan.xqy")

  (: Returns a pointer to the function that implements the 'cancel' capability. :)
    ]]></pre>
  </apidoc:example>
</apidoc:function>
<apidoc:function name="implementations" lib="plugin" category="Plugin" bucket="XQuery Library Modules" xmlns:apidoc="http://marklogic.com/xdmp/apidoc">
  <apidoc:summary>
  This function returns a map referencing all of the plugins that implement the 
  specified capability. If no plugins implement the given capability, returns 
  an empty map.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="capability" type="xs:string">
    The desired capability to match.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return>map:map</apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml"; 

  import module namespace plugin = "http://marklogic.com/extension/plugin" 
      at "/MarkLogic/plugin/plugin.xqy";

  plugin:implementations(
     "http://marklogic.com/appservices/infostudio/collector/cancel")

  (: Returns a pointer to the function that implements the 'cancel' capability 
     for each plugin that implements 'cancel'. :)
    ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="register" lib="plugin" category="Plugin" bucket="XQuery Library Modules" xmlns:apidoc="http://marklogic.com/xdmp/apidoc">
  <apidoc:summary>This function registers the capabilities map for use by MarkLogic
  Server.</apidoc:summary>
  <apidoc:params>
    <apidoc:param name="capabilities" type="map:map">The map of capabilities to be
    registered.</apidoc:param>
    <apidoc:param name="plugin-uri" type="xs:string">
     An identifier that uniquely identifies this plugin.  If a plugin is added with the 
     same identifier an existing plugin, then the newly registered plugin will be used.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return>xs:string</apidoc:return>
  <apidoc:privilege>
  <p><code>http://marklogic.com/xdmp/privileges/plugin-register</code></p>
  </apidoc:privilege>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml"; 

  declare namespace testdoc = "http://marklogic.com/extension/plugin/testdoc";

  import module namespace plugin = "http://marklogic.com/extension/plugin" 
      at "/MarkLogic/plugin/plugin.xqy";

  declare function testdoc:capabilities() 
  as map:map
  {
    let $map := map:map()
    let $_ := map:put($map, "http://marklogic.com/appservices/infostudio/collector/model", 
                       xdmp:function(xs:QName("testdoc:model")))
    let $_ := map:put($map, "http://marklogic.com/appservices/infostudio/collector/start",  
                       xdmp:function(xs:QName("testdoc:start")))
    let $_ := map:put($map, "http://marklogic.com/appservices/infostudio/collector/config-view",  
                       xdmp:function(xs:QName("testdoc:view")))
    let $_ := map:put($map, "http://marklogic.com/appservices/infostudio/collector/cancel",  
                       xdmp:function(xs:QName("testdoc:cancel")))
    let $_ := map:put($map, "http://marklogic.com/appservices/infostudio/collector/abort",  
                       xdmp:function(xs:QName("testdoc:abort")))
    let $_ := map:put($map, "http://marklogic.com/appservices/infostudio/collector/validate",  
                       xdmp:function(xs:QName("testdoc:validate")))
    let $_ := map:put($map, "http://marklogic.com/appservices/string",  
                       xdmp:function(xs:QName("testdoc:string")))
    return $map
  };

  (: Implement the functions in the capabilities map. :)

  plugin:register(testdoc:capabilities(), "testdoc.xqy")

  (: Registers the capabilities in the map for this plugin. :)
      ]]></pre>
  </apidoc:example>
</apidoc:function>


</apidoc:module>
