Written Tutorial

Problem

You want to load a new module or replace an existing module using Query Console.

Solution

xquery version "1.0-ml";
 
let $uri := "/some/new/uri/module.xqy"
let $example-uri := "/some/existing/uri/module.xqy"
let $commit := fn:false()
 
let $node := fn:doc($uri)/text()
let $new-node := <foo><![CDATA[
xquery version "1.0-ml";
 
"Hello World"
]]></foo>/text()
 
return (
  if (fn:exists($node)) then (
    text{"Replacing document at", $uri},
    if ($commit) then xdmp:node-replace($node, $new-node) else ( $node, $new-node )
  ) else (
    text{"Adding document at", $uri},
    if ($commit) then
      xdmp:document-insert($uri, $new-node, 
        xdmp:document-get-permissions($example-uri), 
        xdmp:document-get-collections($example-uri))
    else ()
  )
)

Discussion

Sometimes you want to make a small change to the code in a modules database in order to run a quick test. Rather than reloading your entire modules database, this recipe lets you update just an individual module. Run this against your modules database, rather than your content database.

One of the “lets” is let $commit := fn:false(). This gives you the chance to make sure that everything will happen the way you expect before you actually do the update. Once you’re confident, change $commit to fn:true().

Based on the Principle of Least Privilege, your application should be running with users who do not have the “admin” role. This means that read and execute permissions must be explicitly granted for your application roles. This recipe handles this by simply lifting the permissions, as well as the collections, from another module in the modules database. The other module is identified by $example-uri.

The new source code you want to work with gets pasted into the <![CDATA[]]> section. In this case, we have a simple “Hello World”. The CDATA wrapper protects the code from being interpreted, which means you don’t need to escape anything.

In general, you should script loading most of your source code. You can use Community projects like the Roxy Deployer or ml-gradle to accomplish this. In particular, you wouldn’t want to use this recipe in production (that’s not the place to experiment)!