...
1.10.0 Management REST API - experimental
Let's look at some code to see how users can use this service. The below example shows how to create a region using CMS.
Curl (any standard REST client)
Code Block | ||||
---|---|---|---|---|
| ||||
curl [-v] [-u user[:password]] -H "Content-Type: application/json" http://<locator.host>:7070/geode-management/v2/regions -XPOST -d ' { "name": "Foo", "type": "PARTITION", "groups": "optional-group-name" }' Sample to copy/paste: curl -H "Content-Type: application/json" http://localhost:7070/geode-management/v2/regions -XPOST -d '{"name": "Foo","type": "PARTITION"}' curl -H "Content-Type: application/json" http://localhost:7070/geode-management/v2/regions -XPOST -d '{"name": "Foo","type": "PARTITION", "groups": ["g1"]}' |
Java Client
To ease the interaction with the rest end point, we provided a java client version of Cluster Management Service. Here is an example to get an instance of this service and use it in any java client code. You will need to have geode-management.jar in your classpath.
About the definition of Region type , can refer to the following class:
org.apache.geode.cache.configuration.RegionType
Code Block | ||||
---|---|---|---|---|
| ||||
public static void main(String[] args) {
String regionName = args[0];
ClusterManagementService cms = ClusterManagementServiceBuilder.buildWithHostAddress().setHost("localhost", 7070).build();
BasicRegionConfig config = new BasicRegionConfig();
config.setName(regionName);
config.setType(RegionType.PARTITION);
config.setGroup("optional-group-name");
ClusterManagementResult result = cms.create(config);
if (!result.isSuccessful()) {
throw new RuntimeException(
"Failure creating region: " + result.getStatusMessage());
}
}
|
The above example is for interacting with the Cluster Management Service's REST end point which has no ssl nor security turned on. To manage a cluster that has security and SSL enabled, you will need to provide a SSLContext
and credentials when getting the service:
Code Block | ||||
---|---|---|---|---|
| ||||
public static void main(String[] args) {
String regionName = args[0];
SSLContext sslContext = SSLContext.getDefault();
HostnameVerifier hostnameVerifier = new NoopHostnameVerifier();
ClusterManagementService cms = ClusterManagementServiceBuilder.buildWithHostAddress().setHost("localhost", 7070).setSslContext(sslContext).setHostnameVerifier(hostnameVerifiler).setCredentials("username", "password").build();
.....
} |
Note: In the context of Geode client, an instance of the ClusterManagementService
can be retrieved be calling ClusterManagementServiceBuilder.buildWithCache(clientCache).build(),
This will attempt to use any existing security or SSL configuration to determine the CMS REST endpoint.
You can use this java client when authoring server side code as well. Here is how one can use CMS on a server,
Code Block | ||||
---|---|---|---|---|
| ||||
public class MyFunction implements Function<String> {
@Override
public void execute(FunctionContext context) {
//1. Get the service instance. You don't need to provide url or port or ssl information since all that information is deduced by the server automatically.
// but you will need to provide a username/password if the cluster is secured.
ClusterManagementService cms = ClusterManagementServiceBuilder.buildWithCache(context.getCache()).build();
//2. Create the config object, these are just JAXB generated POJOs
BasicRegionConfig regionConfig = new BasicRegionConfig(); //These are JAXB generated configuration objects
regionConfig.setName("ACCOUNTS");
regionConfig.setType(RegionType.REPLICATE);
//3. Invoke create, update, delete or get depending on what you want to do.
ClusterManagementResult result = cms.create(regionConfig);
}
} |
ClusterManagementService Interface
The primary ClusterManagementService
interface is as follows:
Code Block | ||||
---|---|---|---|---|
| ||||
public interface ClusterManagementService {
<T extends CacheElement> ClusterManagementResult<?, ?> create(T config);
<T extends CacheElement> ClusterManagementResult<?, ?> delete(T config);
<T extends CacheElement> ClusterManagementResult<?, ?> update(T config);
<T extends CacheElement & CorrespondWith<R>, R extends RuntimeInfo> ClusterManagementResult<T, R> list(T config);
<T extends CacheElement & CorrespondWith<R>, R extends RuntimeInfo> ClusterManagementResult<T, R> get(T config);
} |
The methods on this interface all interact with simple Java classes that map directly to elements in the Geode cache.xml
file. For example, region actions will use the RegionConfig
class. When creating Geode components, these classes are used as input to the API. When querying Geode, these classes (or subclasses) are returned as the response to those queries. See ClusterManagementResult
below.
ClusterManagementResult
ClusterManagementResult is the result object you get when you invoke a method using cluster management service. Here is an instance of this object in json format:
Code Block | ||||
---|---|---|---|---|
| ||||
{
"memberStatuses" : {
"server-1" : {
"success" : true,
"message" : "success"
}
},
"statusCode" : "OK",
"statusMessage" : "successfully persisted config for cluster",
"successful" : true
} |
Here is an explanation of each of the fields in the result object:
"successful": a boolean value indicating the overall success/failure status of the service call. it will be true if and only if the "statusCode" value is "OK".
"statusCode": a enum field indicating the result status. Here is a list of possible values in this field:
...
"StatusMessage": a detailed message about the result of the operation
"memberStatus": information about the operation status on each server.
Behind the scenes
On the locator side, the configuration service framework will just handle the workflow. It's up to each individual ClusterConfigElement to implement how it needs to be persisted and applied.
...