General pattern for manager classes

Overview

A manager class is one that's used to talk to a noun-based section of the Management API as documented at http://docs.marklogic.com/REST/management. Each section of the API should have a manager class, and some may have multiple manager classes because the noun represented by the section encompasses several lower-level nouns. For example, the Databases and Forests sections should each have a manager class, while the Security section would have manager classes for users, roles, amps, and the other nouns encompassed by "security".

Note that the managers are completely separate from the app deployer classes. The deployer classes depend on the managers to talk to the Management API; the manager classes have no knowledge of the deployer classes.

Naming and packaging

Each manager class should be named after the singular form of the noun that it represents - e.g. DatabaseManager, ForestManager, HostManager.

Each manager class should be placed in a package under com.marklogic.mgmt that corresponds to the name of the section that it represents. For example, the Databases manager should be located at com.marklogic.mgmt.databases.DatabaseManager.

Implementation

Each manager class should adhere to the following:

• It should extend AbstractManager, which provides some convenience methods
• It should have a single constructor that requires an instance of ManageClient, which wraps an instance of Spring's RestTemplate with convenience methods for talking to the Management API
• It should have as many fine-grained public methods as necessary to cover all endpoints and features provided by its corresponding section of the Management API
• It should use the Logger instance provided by AbstractManager and log helpful messages at the INFO level. Each invocation of the Management API through the ManageClient instance should have a log message before and after it to explain what is about to happen and what just happened. This both helps debugging when something goes wrong and provides good visibility of exactly what the manager is doing.

Testing

A manager class can be tested by extending AbstractMgmtTest, which utilizes the Spring framework for defining MarkLogic connection information and providing an instance of ManageClient. Depending on what the manager does, it can use convenience methods in AbstractMgmtTest for quickly creating a sample REST API application and then deleting it (the test should never leave any "residue" behind).

As an example of a test that doesn't need to create the sample app, ManageHostsTest simply instantiates HostManager with the test-framework-provided instance of ManageClient. Conversely, a test for verifying that a database can be updated would most likely create the sample app to get a database in place and then use DatabaseManager to update the database.

Tests for manager classes should always verify that the expected outcomes of invoking a Management API endpoint are actually met. This often is done by invoking other Management API endpoints to inspect the state of the MarkLogic server.