Plugins allow you to provide functionality to all of the applications in your MarkLogic Server cluster without the application having to call any code. This section describes the system plugin framework in MarkLogic Server and includes the following parts:
Plugins are used to automatically perform some functionality before any request is evaluated. A plugin is an XQuery main module, and it can therefore perform arbitrary work. The plugin framework evaluates the main modules in the
<marklogic-dir>/Plugins directory before each request is evaluated.
Pluginsdirectory is evaluated before the first request against each App Server is evaluated on each node in the cluster. This process repeats again after the
Pluginsdirectory is modified.
Pluginsdirectory must be added to the
Pluginsdirectory on each node in a MarkLogic Server cluster.
/Pluginsdirectory. If there are any errors in a plugin module, you must fix them before you will be able to successfully evalate any requests against any App Server.
Pluginsdirectory is modified; it does not check for modifications of the individual files in the
Pluginsdirectory. If you are using an editor to modify a plugin that creates a new file (which in turn modifies the directory) upon each update, then MarkLogic Server will see the update within the next second. If your editor modifies the file in place, then you will have to touch the directory to change the modification date for the latest changes to be loaded (alternatively, you can restart MarkLogic Server). If you delete a plugin from the
Pluginsdirectory, it remains registered on any App Servers that have already evaluated the plugin until either you restart MarkLogic Server or another plugin registers with the same name on each App Server.
System plugins use the built-in plugin framework in MarkLogic Server along with the xdmp:set-server-field and xdmp:get-server-field functions. As described in Overview of System Plugins, system plugins are stored in the <marklogic-dir>
/Plugins directory and any errors in them are thrown on all App Servers in the cluster.
Application plugins are built on top of system plugins and are designed for use by applications. For example, application plugins are used in Information Studio, and these application plugins enable developers to extend the functionality of Information Studio with their own customized functionality. Application plugins are stored in the <marklogic-dir>
/Assets/plugins/marklogic/appservices directory, and, unlike system plugins, they do not cause errors to other applications if the plugin code contains errors. For details on using plugins with Information Studio to create custom collectors and transformers, see Creating Custom Collectors and Transforms in the Information Studio Developer's Guide.
The plugin:register function is the mechanism that a plugin module uses to make plugin functionality available anywhere in a MarkLogic Server cluster. The other functions in the
plugin API are used to implement the register capability. The
plugin API uses server fields (the xdmp:set-server-field and xdmp:get-server-field family of functions) to register the ID and capabilities of each plugin. This API, in combination with the plugin framework that scans the
Plugins directory, allows you to create functionality that is available to all App Servers in a MarkLogic Server cluster.
With the plugin API, you can register a set of plugins, and then you can ask for all of the plugins with a particular capability, and the functionality delivered by each plugin is available to your application. Information Studio uses this mechanism in its user interface to offer collectors and transformers. For details about the plugin API, see the MarkLogic XQuery and XSLT Function Reference.
To use a system plugin, you must deploy the plugin main module to the
Plugins directory. To deploy a plugin to a MarkLogic Server cluster, you must copy the plugin main module to the plugin directory of each host in the cluster.
Any system plugin module you write should have a unique filename. Do not modify any of the plugin files that MarkLogic ships in the <marklogic-dir>
/Plugins directory. Any changes you make to MarkLogic-installed files in the
Plugins directory will be overridden after each upgrade of MarkLogic Server.
Information Studio uses application plugins for its collectors and transformers, but does not put them in the <marklogic-dir>
/Plugins directory. Instead, it puts them in the <marklogic-dir>
/Assets/plugins/marklogic/appservices directory. In the directory that Information Studio uses, it is possible to create your own plugins to extend Information Studio or for use outside of Information Studio. You need to initialize those plugins with the plugin:initialize-scope function, which specifies the path within the
Assets/plugins/marklogic/appservices directory to find the XQuery modules. For more details, see the Plugin Module API documentation in the MarkLogic XQuery and XSLT Function Reference and the Creating Custom Collectors and Transforms Information Studio Developer's Guide.
For information about the differect between application plugins and system plugins,see System Plugins versus Application Plugins.
One use case for a system plugin is to check passwords for things like number of characters, special characters, and so on. Included in the
<marklogic-dir>/Samples/Plugins directory are sample plugin modules for password checking.
When no plugins are registered with the above capability in the <marklogic-dir>
/Plugins directory, then no other work is done upon setting a password. If you include plugins that register with the above
password-check capability in the <marklogic-dir>
/Plugins directory, then the module(s) are run when you set a password. If multiple plugins are registered with that capability, then they will all run. The order in which they run is undetermined, so the code should be designed such that the order does not matter.
There is a sample included that checks for a minimum length and a sample included that checks to see if the password contains digits. You can create your own plugin module to perform any sort of password checking you require (for example, check for a particular length, the existence of various special characters, repeated charatcers, upper or lower case, and so on).
Additionally, you can write a plugin to save extra history in the Security database user document, which stores information that you can use or update in your password checking code. The element you can use to store information for password checking applications is
sec:password-extra. You can use the sec:user-set-password-extra and sec:user-set-password-extra functions (in
security.xqy) to modify the
sec:password-extra element in the user document. Use these APIs to create elements as children of the
If you look at the
<marklogic-dir>/Samples/Plugins/password-check-minimum-length.xqy file, you will notice that it is a main module with a function that returns empty on success, and an error message if the password is less than a minimum number of characters. In the body of the main module, the plugin is registered with a map that includes its capability (it could register several capabilities, but this only registers one) and a unique name (in this case, the name of the xqy file:
let $map := map:map(), $_ := map:put($map, "http://marklogic.com/xdmp/security/password-check", xdmp:function(xs:QName("pwd:minimum-length"))) return plugin:register($map, "password-check-minimum-length.xqy")
You should use a unique name to register your plugin (the second argument to plugin:register). If the name is used by another plugin, only one of them will end up being registered (because the other one will overwrite the registration).
If you want to implement your own logic that is performed when a password is checked (both on creating a user and on changing the password), then you can write a plugin, as described in the next section.
<marklogic-dir>Samples/Plugins/password-check-*.xqyfiles to the
Pluginsdirectory. For example:
password-check-minimum-length), open them in a text editor.
pwd:minimum-lengthfunction and change the 4 to a 6 (or to whatever you prefer). When you are done, the body of the function looks as follows:
my-password-plugin.xqy, change the plugin:register call as follows:
If you made a typo or some other mistake that causes a syntax error in the plugin, any request you make to any App Server will throw an exception. If that happens, edit the file to correct any errors.
Pluginsdirectory on each host in your cluster.