Debugging module loading

Under the hood, ml-gradle uses the MarkLogic Client API to connect to a MarkLogic REST API server and load modules. So when you run into errors with loading modules, it's often helpful to run a quick test that uses the Client API to confirm that you can connect to your REST API server outside the scope of ml-gradle.

Here's a task that you can customize and run for loading modules via port 8000 (this includes all "asset" modules - i.e. not REST API services, transforms, or options, which must be loaded via your application-specific REST API server):

task testLoadModule {
    doLast {
	// See https://docs.marklogic.com/javadoc/client/com/marklogic/client/DatabaseClientFactory.html
	def host = "localhost"
	def port = 8000
	def database = "example-modules"
	def username = "admin"
	def password = "admin"

	// See https://docs.marklogic.com/javadoc/client/com/marklogic/client/DatabaseClientFactory.SecurityContext.html
	def context = new com.marklogic.client.DatabaseClientFactory.DigestAuthContext(username, password)
	def client = com.marklogic.client.DatabaseClientFactory.newClient(host, port, database, context)
	try {
		client.newDocumentManager().write("/test/module.xqy", new com.marklogic.client.io.StringHandle("<hello>world</hello>"))
	} finally {
		client.release()
	}
    }
}

You can use this as a starting point for any sort of debugging test, such as for loading a service or transform. Just check out the MarkLogic Client API docs to see what calls need to be made.

Checking things are in the right place

First, understand that your code is expected to be found in certain directories, laid out in How modules are loaded.

Configuring SSL

The Java Client SecurityContext javadocs show the methods for configuring an SSL context and hostname verifier on the SecurityContext. You can call these methods to configure an SSL connection to your REST server:

def context = new com.marklogic.client.DatabaseClientFactory.DigestAuthContext(username, password)
// This is one possible implementation of an SSLContext
context.withSslContext(com.marklogic.client.ext.modulesloader.ssl.SimpleX509TrustManager.newSSLContext())
context.withHostnameVerifier(com.marklogic.client.DatabaseClientFactory.SSLHostnameVerifier.ANY)

Authenticating with a certificate

If port 8000 and/or your REST API server (for loading REST extensions like services, transforms, and options) requires authenticating with a certificate, you can use the below task as a starting point for debugging authenticating with that app server. It doesn't load a module; it just evaluates a simple XQuery expression, which should suffice for verifying that you can authenticate correctly.

task testAuthenticateWithCertificate {
  doLast {
    def host = "localhost"
    def port = 8123 // the port of your REST API server
    def certFile = "path/to/cert.p12"
    def certPassword = "not-required"

    // See https://docs.marklogic.com/javadoc/client/com/marklogic/client/DatabaseClientFactory.CertificateAuthContext.html
    def context = new com.marklogic.client.DatabaseClientFactory.CertificateAuthContext(certFile, certPassword)
    def client = com.marklogic.client.DatabaseClientFactory.newClient(host, port, context)
    try {
      println client.newServerEval().xquery("fn:current-dateTime()").evalAs(String.class)
    } finally {
      client.release()
    }
  }
}