How modules are loaded

By default, ml-gradle loads modules from src/main/ml-modules. This directory aligns with the Maven convention of placing all application code under "src/main", and "ml-modules" was chosen as a MarkLogic-specific path.

To accommodate storing both REST API specific modules (such as options, services, and transforms) and "regular" application modules under the same parent directory, the following directory structure is used for identifying where different kinds of modules should be stored:

1. /root - You store any modules here that aren't REST API options, services, transforms, or namespaces. The module will be loaded with a URI relative to "/root" (it won't have "/root" in the URI).
2. /ext - You can also store any modules here too, just like "/root". What's the difference? "/ext" was actually supported first in an effort to mirror what the REST API suggests with its /v1/ext endpoint. But in practice, there's little value in storing modules under "/ext", so it's easier just to toss everything under "/root".
3. /options - Search options are stored here. The name of the file (minus the extension) is used to name the search options loaded into ML.
4. /services - Resource extensions are stored here. The name of the file (minus the extension) is used to name the resource extension.
5. /transforms - Transforms are stored here. The name of the file (minus the extension) is used to name the transform.
6. /namespaces - A namespace file contains the namespace URI, and the name of the file (minus the extension, which can be anything) is used for the namespace prefix.
7. In addition, any "unrecognized" directory under ml-modules - i.e. a directory that isn't one of the above - will have its contents loaded into the modules database. Prior to ml-gradle 3.0.0, the URI of each such document would include the name of the unrecognized directory. But with version 3.0.0 and greater, the URI does not have the unrecognized directory name. Best practice is to stick with "ext" and "root" for modules and not use this feature!

Modules are loaded when you run "mlDeploy". They can also be loaded by themselves:

gradle mlLoadModules

It's often helpful to use info-level logging so you can see which modules are loaded:

gradle -i mlLoadModules

You can also reload modules - i.e. clear the modules database first, and then load modules:

gradle mlReloadModules

Only loading modules that need loading

See Watching for module changes for more information on this topic.

The /v1/ext endpoint in the ML Client REST API only allows for loading one module at a time, and thus loading hundreds of modules or more can take minutes. This isn't too painful for initializing an empty modules database, but it's unacceptable during a code-test cycle.

To address this, ml-gradle keeps track of when it last loaded each module. This is done via a properties file in the "build" directory of the project (so that the properties file is not in version control). The path of the file is build/ml-last-installed-timestamp.properties. When ml-gradle tries to load a module, it first checks to see if the module's last-modified timestamp is greater than what is recorded in the properties file. If so, the module is loaded, and the properties file is updated.