This page was generated
June  25,  2015
8:20  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Plugin

The Plugin API module contains functions that allow you to register plugins for use by MarkLogic Server.

The Plugin API is installed as the following file:

install_dir/Modules/MarkLogic/plugin/plugin.xqy

where install_dir is the directory in which MarkLogic Server is installed.

To use the plugin.xqy module in your own XQuery modules, include the following line in your XQuery prolog:

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

The library uses the plugin: namespace, which is not predefined in the server.

Function Summary
plugin:asset Returns the named asset, which must exist in the assets/ directory of the plugin, as stored in the Extensions database.
plugin:asset-exists Returns true if the named asset exists, otherwise returns false.
plugin:capability This function returns a function pointer implementing a given capability from a particular plugin.
plugin:enumerate This function enumerates functions implementing all capabilities supported by the given plugin.
plugin:flush-scope This function unloads all application plugins from a given scope.
plugin:implementations This function returns a map referencing all of the plugins that implement the specified capability.
plugin:initialize-scope This function ensures the availability of all plugins from a given scope.
plugin:install-from-filesystem This function installs a Library Module plugin from a fixed location on the filesystem (Assets/plugins/...) into the Extensions database.
plugin:install-from-zip Installs a Library Module plugin from a zip file provided as a parameter into the Extensions database.
plugin:plugins This function returns unique IDs of the registered plugins that have the specified capabilities.
plugin:register This function registers the capabilities map for use by MarkLogic Server.
plugin:uninstall This function removes a named plugin or set of plugins from the extensions database.
Function Detail
plugin:asset(
$pid as xs:string,
$scope as xs:string,
$asset-path as xs:string)
)  as   node()?
Summary:

Returns the named asset, which must exist in the assets/ directory of the plugin, as stored in the Extensions database. This will only return a value for Library Module plugins.

Parameters:
$pid : A plugin ID.
$scope : A scope identifier. This must be a "dotted" package-style path, which will be resolved relative to the marklogic-dir/Assets/plugins directory. For example, a $scope value of my-plugin-scope is resolved to the marklogic-dir/Assets/plugins/myplugin-scope directory and a $scope value of my.plugin.scope is resolved to the marklogic-dir/Assets/plugins/my/plugin/scope directory.
$asset-path : The filename (omitting any path information) of an asset in this plugin space.

Example:
xquery version "1.0-ml"; 
 
import module namespace plugin = "http://marklogic.com/extension/plugin" 
      at "/MarkLogic/plugin/plugin.xqy";

plugin:asset-exists("collector-test", "marklogic.appservices", "picture.gif")

(: Returns the asset, 'picture.gif,' used by the collect-test plugin
   located in the Extensions database. :)      
      

plugin:asset-exists(
$pid as xs:string,
$scope as xs:string,
$asset-path as xs:string)
)  as   xs:boolean
Summary:

Returns true if the named asset exists, otherwise returns false.

Parameters:
$pid : A plugin ID.
$scope : A scope identifier. This must be a "dotted" package-style path, which will be resolved relative to the marklogic-dir/Assets/plugins directory. For example, a $scope value of my-plugin-scope is resolved to the marklogic-dir/Assets/plugins/myplugin-scope directory and a $scope value of my.plugin.scope is resolved to the marklogic-dir/Assets/plugins/my/plugin/scope directory.
$asset-path : The filename (omitting any path information) of an asset in this plugin space.

Example:
xquery version "1.0-ml"; 
 
import module namespace plugin = "http://marklogic.com/extension/plugin" 
      at "/MarkLogic/plugin/plugin.xqy";

plugin:asset-exists("collector-test", "marklogic.appservices", "picture.gif")

(: Returns true if the asset, 'picture.gif,' used by the collect-test plugin
   is located in the Extensions database. :)
      

plugin:capability(
$capability as xs:string,
$uri as xs:string,
[$scope as xs:string]
)  as   xdmp:function?
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.

Parameters:
$capability : The desired capability to match.
$uri : The unique identifier of the plugin.
$scope (optional): A scope identifier. This must be a "dotted" package-style path, which will be resolved relative to the marklogic-dir/Assets/plugins directory. For example, a $scope value of my-plugin-scope is resolved to the marklogic-dir/Assets/plugins/myplugin-scope directory and a $scope value of my.plugin.scope is resolved to the marklogic-dir/Assets/plugins/my/plugin/scope directory.

Example:
  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. :)
    

plugin:enumerate(
$uri as xs:string,
[$scope as xs:string]
)  as   map:map
Summary:

This function enumerates functions implementing all capabilities supported by the given plugin. It returns a map, keyed on the capabilities.

Parameters:
$uri : The unique identifier of the plugin.
$scope (optional): A scope identifier. This must be a "dotted" package-style path, which will be resolved relative to the marklogic-dir/Assets/plugins directory. For example, a $scope value of my-plugin-scope is resolved to the marklogic-dir/Assets/plugins/myplugin-scope directory and a $scope value of my.plugin.scope is resolved to the marklogic-dir/Assets/plugins/my/plugin/scope directory.

Example:

  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. :)
    

plugin:flush-scope(
$scope as xs:string
)  as   empty-sequence()
Summary:

This function unloads all application plugins from a given scope. Note that system plugins are unaffected by this function. Like plugin:initialize-scope, this function requires the application-plugin-registrar role.

Parameters:
$scope : A scope identifier. This must be a "dotted" package-style path, which will be resolved relative to the marklogic-dir/Assets/plugins directory. For example, a $scope value of my-plugin-scope is resolved to the marklogic-dir/Assets/plugins/myplugin-scope directory and a $scope value of my.plugin.scope is resolved to the marklogic-dir/Assets/plugins/my/plugin/scope directory.

Required Privilege:

This function requires the privileges in the application-plugin-registrar role, and the best practice is to put plugin:flush-scope in a function that is amped to the application-plugin-registrar role.

Example:
xquery version "1.0-ml"; 
 
import module namespace plugin = "http://marklogic.com/extension/plugin" 
      at "/MarkLogic/plugin/plugin.xqy";

plugin:flush-scope("marklogic.appservices")

(: Unloads all of the plugins located in /Assets/plugins/marklogic/appservices :)

plugin:implementations(
$capability as xs:string,
[$scope as xs:string]
)  as   map:map
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.

Parameters:
$capability : The desired capability to match.
$scope (optional): A scope identifier. This must be a "dotted" package-style path, which will be resolved relative to the marklogic-dir/Assets/plugins directory. For example, a $scope value of my-plugin-scope is resolved to the marklogic-dir/Assets/plugins/myplugin-scope directory and a $scope value of my.plugin.scope is resolved to the marklogic-dir/Assets/plugins/my/plugin/scope directory.

Example:
  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'. :)
    

plugin:initialize-scope(
$scope as xs:string
)  as   xs:integer
Summary:

This function ensures the availability of all plugins from a given scope. A scope is a directory relative to marklogic-dir/Assets/plugins. Attempting to reload the System scope (with an empty string for $scope) has no effect (and hence returns 0). Any application that calls this function must do so through a function amped to the application-plugin-registrar role.

This function MUST be called by an application before querying or enumerating plugins (or else see an empty set of available plugins). Even if called on every request, this function will only load from the directory on the first call. This function checks the global debug flag, and if true, forces a reload on every request.


Parameters:
$scope : A scope identifier. This must be a "dotted" package-style path, which will be resolved relative to the marklogic-dir/Assets/plugins directory. For example, a $scope value of my-plugin-scope is resolved to the marklogic-dir/Assets/plugins/myplugin-scope directory and a $scope value of my.plugin.scope is resolved to the marklogic-dir/Assets/plugins/my/plugin/scope directory.

Required Privilege:

This function requires the privileges in the application-plugin-registrar role, and the best practice is to put plugin:initialize-scope in a a function that is amped to the application-plugin-registrar role.


Example:
xquery version "1.0-ml"; 
 
import module namespace plugin = "http://marklogic.com/extension/plugin" 
    at "/MarkLogic/plugin/plugin.xqy";

plugin:initialize-scope("marklogic.appservices")

(: Initializes all of the plugins located in /Assets/plugins/marklogic/appservices :)
 

plugin:install-from-filesystem(
$scope as xs:string
)  as   xs:integer
Summary:

This function installs a Library Module plugin from a fixed location on the filesystem (Assets/plugins/...) into the Extensions database. Any application that calls this function must do so through a function amped to the application-plugin-registrar role. It returns the number of plugins installed.

Parameters:
$scope : A scope identifier. This must be a "dotted" package-style path, which will be resolved relative to the marklogic-dir/Assets/plugins directory. For example, a $scope value of my-plugin-scope is resolved to the marklogic-dir/Assets/plugins/myplugin-scope directory and a $scope value of my.plugin.scope is resolved to the marklogic-dir/Assets/plugins/my/plugin/scope directory.

Example:
xquery version "1.0-ml"; 
 
import module namespace plugin = "http://marklogic.com/extension/plugin" 
      at "/MarkLogic/plugin/plugin.xqy";

plugin:install-from-filesystem("marklogic.appservices")

(: Installs all of the plugins located in /Assets/plugins/marklogic/appservices
   into the Extensions database. :) 
    

plugin:install-from-zip(
$scope as xs:string,
$zip as binary())
)  as   xs:integer
Summary:

Installs a Library Module plugin from a zip file provided as a parameter into the Extensions database. Any application that calls this function must do so through a function amped to the application-plugin-registrar role. Returns an integer representing the number of plugins installed.

Parameters:
$scope : A scope identifier. This must be a "dotted" package-style path, which will be resolved relative to the marklogic-dir/Assets/plugins directory. For example, a $scope value of my-plugin-scope is resolved to the marklogic-dir/Assets/plugins/myplugin-scope directory and a $scope value of my.plugin.scope is resolved to the marklogic-dir/Assets/plugins/my/plugin/scope directory.
$zip : A zip file, consisting of the zipped directory of a Library Module plugin (that is, manifest.xml must exist at the root level, with assets/ and lib/ subdirectories).

Example:
xquery version "1.0-ml"; 
 
import module namespace plugin = "http://marklogic.com/extension/plugin" 
      at "/MarkLogic/plugin/plugin.xqy";

plugin:install-from-zip("
      marklogic.appservices.collector-test", 
      xdmp:document-get("Assets/plugins/marklogic/appservices/collector-test.zip")/node())

(: Installs the plugin code from the 'collector-test.zip' file. :)         
      

plugin:plugins(
$capability as xs:string*,
[$scope as xs:string]
)  as   xs:string*
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.

Parameters:
$capability : 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.
$scope (optional): A scope identifier. This must be a "dotted" package-style path, which will be resolved relative to the marklogic-dir/Assets/plugins directory. For example, a $scope value of my-plugin-scope is resolved to the marklogic-dir/Assets/plugins/myplugin-scope directory and a $scope value of my.plugin.scope is resolved to the marklogic-dir/Assets/plugins/my/plugin/scope directory.

Example:
  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. :)
    

plugin:register(
$capabilities as map:map,
$plugin-uri as xs:string
)  as   xs:string
Summary:

This function registers the capabilities map for use by MarkLogic Server. It returns the URI of the plugin.

Parameters:
$capabilities : The map of capabilities to be registered.
$plugin-uri : An identifier that uniquely identifies this plugin. If a plugin is added with the same identifier as an existing plugin, then the newly registered plugin will be used.

Required Privilege:

http://marklogic.com/xdmp/privileges/plugin-register


Example:
  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. :)
      

plugin:uninstall(
$scope as xs:string,
$pid as xs:string
)  as   empty-sequence()
Summary:

This function removes a named plugin or set of plugins from the extensions database.

Parameters:
$scope : A scope identifier. This must be a "dotted" package-style path, which will be resolved relative to the marklogic-dir/Assets/plugins directory. For example, a $scope value of my-plugin-scope is resolved to the marklogic-dir/Assets/plugins/myplugin-scope directory and a $scope value of my.plugin.scope is resolved to the marklogic-dir/Assets/plugins/my/plugin/scope directory.
$pid : A plugin ID.

Example:
xquery version "1.0-ml"; 
 
import module namespace plugin = "http://marklogic.com/extension/plugin" 
      at "/MarkLogic/plugin/plugin.xqy";

plugin:uninstall("marklogic.appservices", "collector-test")

(: Uninstalls the 'collector-test' plugin located in 
   /Assets/plugins/marklogic/appservices from the Extensions database. :)