REST Server configuration is done through a ServerConfigurationManager object located in package com.marklogic.client.admin. REST Server configuration deals with the underlying REST instance running in MarkLogic. You can configure REST Server properties, namespace bindings, query options, and transform and resource extensions.

Note that you can only configure aspects of the underlying REST instance with the Java API. MarkLogic Server administration is not exposed in Java, so things such as creating indexes, creating users, creating databases, and assigning roles to users must be done via the MarkLogic Admin Interface or other means (for example, the Admin API or REST Management API). For more information about administering MarkLogic Server, see the Administrator's Guide.

This chapter includes the following sections:

Creating a Server Configuration Manager Object
Reading and Writing Server Configuration Properties
REST Server Properties
Creating New Server-Related Manager Objects
Namespaces
Logging Namespace Operations

Creating a Server Configuration Manager Object

Using a com.marklogic.client.DatabaseClient object, call newServerConfigManager()

DatabaseClient client = DatabaseClientFactory.newClient(...);

// create a manager for server configuration
ServerConfigurationManager configMgr =
                           client.newServerConfigManager();

Your application only needs one active ServerConfigurationManager at any time.

Reading and Writing Server Configuration Properties

Use com.marklogic.client.admin.ServerConfigurationManager to manage server configuration properties. To read the current server configuration values into the ServerConfigurationManager object, do:

configMgr.readConfiguration();

If your application changes these values, they will not persist unless written out to the server. To write the REST Server Configuration values to the server, do:

configMgr.writeConfiguration();

REST Server Properties

com.marklogic.client.admin.ServerConfigurationManager objects have get and set methods for the following server properties:

ContentVersionRequests: Deprecated. Use UpdatePolicy instead.
DefaultDocumentReadTransform: Name of the default transform applied to documents as they are read from the server. For information about document transforms, see Content Transformations.
QueryOptionsValidation: Boolean specifying whether the server validates query options before storing them in configurations. For information about query options, see Query Options.
ServerRequestLogging: Boolean specifying whether the REST Server logs requests to the MarkLogic Server error log (ErrorLog.txt). For performance reasons, you should only enable this when debugging your application. For information about logging, see Logging.
UpdatePolicy: Value from the ServerConfigurationManager.UpdatePolicy enum specifying whether the system tries to detect if a document is fresh or not via use of an opaque numeric identifier and whether to merge or overwrite metadata on update. For more information, see Optimistic Locking.

Creating New Server-Related Manager Objects

Most manager objects described so far handle access to the database and its content, and accordingly are created via a method on a DatabaseClient object. The following managers handle listing, reading, writing, and deleting REST Server data and settings, rather than those of the database. Therefore, these managers are created by factory methods on a ServerConfigurationManager instead of a DatabaseClient.

The ServerConfigurationManager associated managers are:

NamespaceManager: Namespace bindings. For details about namespaces, see Namespaces.
QueryOptionsManager: Query options. For details, about query options, see Query Options.
ResourceExtensionsManager: Resource service extensions. For details about resource service extensions, see Extending the Java API.
TransformExtensionManager: Transform extensions. For details, about transform extensions, see Content Transformations.

Namespaces

Namespaces are similar to Java packages in that they differentiate between potentially ambiguous XML elements. With the Java API, you can define namespace bindings on the REST Server.

In XML and XQuery, element and attribute nodes are always in a namespace, even if it is the empty namespace (sometimes called no namespace) which has the name of the empty string (""). Each non-empty namespace has an associated URI, which is essentially a unique string that identifies the namespace. That string can be bound to a namespace prefix, which is a shorthand string used as an alias for the namespace in path expressions, element QNames, and variable declarations. Namespace operations in the Java Client API are used to define namespace prefixes on the REST Server so the client and server can share identical namespace bindings on XML elements and attributes for use in queries.

Note that a namespace URI can be bound to multiple prefixes, but a prefix can only be bound to one URI.

If you need to use a namespace prefix in a context in which you cannot declare it, use the REST Management API to define the binding in the App Server. For details, see PUT:/manage/v2/servers/[id-or-name]/properties.

For more information about namespaces, see Understanding XML Namespaces in XQuery in the XQuery and XSLT Reference Guide, which provides a detailed description of XML namespaces and their use.

This section includes the following parts:

Namespaces Manager
Getting Server Defined Namespaces
Adding And Updating A Namespace Prefix
Reading Prefixes
Deleting Prefixes

Namespaces Manager

The NamespacesManager interface is deprecated. Use the REST Management API instead. For details, see PUT:/manage/v2/servers/[id-or-name]/properties or GET:/manage/v2/servers/[id-or-name]/properties.

The com.marklogic.admin.NamespacesManager class provides editing for namespaces defined on the REST Server. To use NamespacesManager, the application must authenticate as rest-admin. Since namespaces are based on the REST Server, a new NamespacesManager is defined via com.marklogic.client.admin.ServerConfigManager.

NamespacesManager nsManager =
    client.newServerConfigManager().newNamespacesManager();

Getting Server Defined Namespaces

Use com.marklogic.client.admin.NamespacesManager to get all of the namespaces defined on the REST Server. For example:

nsManager.readAll();

This returns a javax.xml.namespace.NamespaceContext interface that includes all of the REST Server defined namespaces. You can run the following on the NamespaceContext object.

nsContext.getNamespaceURI(prefix-string);
nsContext.getPrefix(URI-string);
nsContext.getPrefixes(URI-string);

getNamespaceURI() returns the URI associated with the given prefix. getPrefix() returns one of the prefixes associated with the given URI. getPrefixes() returns an iterator of all the prefixes associated with the given URI.

In addition, by casting the NamespaceContext to EditableNamespaceContext, you can iterate over the complete set of prefixes and URIs:

EditableNamespaceContext c =(EditableNamespaceContext)nsMgr.readAll();
for (Entry e:c.entrySet()){
  prefix = e.getKey();
  nsURI = e.getValue();
...
}

Adding And Updating A Namespace Prefix

Use com.marklogic.client.admin.NamespacesManager to add a new namespace prefix. For example:

nsManager.addPrefix("ml", "http://marklogic.com/exercises");

The first argument is the prefix, and the second argument is the URI being associated with the prefix.

To update the value of an existing prefix, do the following:

nsManager.updatePrefix("ml", "http://marklogic.com/new_exercises");

Where the first argument is the prefix, and the second argument is the new URI bound to it.

Reading Prefixes

Use com.marklogic.client.admin.NamespacesManager to read, or get, the associated URI value, of a single prefix. For example:

nsManager.readPrefix("ml");

It returns the prefix's associated URI as a string.

In order to read, or get, all of the prefixes associated with a Namespace Manager, do the following:

NamespaceContext context = nsManager.readAll();

NamespaceContext is a standard javax.xml Interface for storing a set of namespace declarations on the client. With a NamespaceContext object, you can:

Get the prefix for any URI for which a prefix-URI binding has been created in this NamespaceServer. The below would return its prefix, say, "ml".
```
context.getPrefix("http://marklogic.com/new_exercises");
```
Get the URI for any prefix for which a prefix-URI binding has been created in this NamespaceServer. The below returns the URI "http://marklogic.com/new_exercises"
```
context.getNamespaceURI("ml");
```
Get all of the prefixes for any URI for which prefix-URI bindings have been created in this NamespaceServer. The below returns all the associated prefixes in an Iterator.
```
context.getPrefixes(http://marklogic.com/new_exercises);
```

Deleting Prefixes

To delete a single prefix from the namespaces manager, do:

nsManager.deletePrefix("ml");

To delete all of the prefixes defined under a NamespaceManager, do:

nsManager.deleteAll();

Logging Namespace Operations

As with all manager objects, you can start and stop logging operations on a NamespacesManager via the startLogging() and stopLogging() methods. For details on how to use the logging facility, see Logging.

MarkLogic Server 11.0 Product DocumentationJava Application Developer's Guide — Chapter 13

MarkLogic Server 11.0 Product Documentation
Java Application Developer's Guide — Chapter 13