To ease the interaction with the rest end point, we provided a java client for this Cluster Management Service. You will need to have geode-management.jar in your class path.
Below is a typical usage of the the CMS java client.
public static void main(String[] args) { // use the ClusterManagementServiceBuilder to build the service client (*1) ClusterManagementService cms = ClusterManagementServiceBuilder.setHost("localhost").setPort(7070).build(); // create a region, or any type that extends AbstractConfiguration (*2) Region regionConfig = new Region(); regionConfig.setName(REGION_IN_SINGLE_GROUP); regionConfig.setGroup("group1"); regionConfig.setType(RegionType.PARTITION); try { // feed this configuration object into the service client. You can use it to create/delete/list/get etc. (*3) ClusterManagementRealizationResult result = cms.create(config); // use the result (*4) } catch (ClusterManagementExcpetion e) { // error handling (*5) } }
You can use this java client when authoring server side code as well. The only difference is you will need to use a different builder to get the service object and inject it with the server cache:
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 = GeodeClusterManagementServiceBuilder.setCache(context.getCache()).build(); ........ } }
*1: Build the Service can
There are bunch of other connection properties you can set using the builder, like username/password, SSL context or auth tokens if the management rest api is using token based authentication. See the javadoc of `ClusterManagementServiceBuilder` for detail.
*2: Configuration Objects
You will need to use a configuration object in order to interact with the cluster configuration service. For example, if you want to get a list of regions in the cluster, you can create a Region configuration object and give it to the "list" method of the service, this configuration object can have some filters like "id" or "group" attributes in order to narrow down your search. If you want to create a region, you need to create a Region object and set the necessary attributes and give it to the "create" method of the service. Please check the package "org.apache.geode.management.configuration" for a list of configuration objects that you can use for the cluster management service.
*3: Cluster Operations
The cluster management service can perform the following list of operations given the configuration objects:
- create: returns ClusterManagementRealizationResult
- delete: returns ClusterManagementRealizationResult
- list: returns ClusterManagementListResult
- get: returns returns ClusterManagementGetResult
- update (not implemented yet): returns ClusterManagementRealizationResult
Besides affecting cluster management, you can also use cluster management service to perform some operations on the cluster. Given an Operation object, you can do the following:
- start : start the operation (the operation is typically long-running)
- get: get the status of the long running operation given the type and the id
- getFuture: get the future of the long running operation for the result
- list: get the list of the such operations that are currently running
*4: Examine the Results
Please see the java doc of the various result object.
*5: Error Handling
Unsuccessful operations would throw ClusterManagementException. This exception contains a status code that indicates what type of error you get:
statusCode | description |
---|---|
OK | operation is successful, configuration is persisted and realized on servers |
FAIL_TO_PERSIST | configuration is realized on servers, but some error occurred when persisting the configuration. the "statusMessage" should tell you exactly why. Normally this means some developer error. when this happened, developer needs to revert the changes or try making the same call again to try to persist it again. |
ERROR | operation is not successful. this includes precondition is not met (either service is not running or no servers available, or the configuration encountered some error when trying to be realized on one member (configuration is not fully realized on all applicable members). |
ENTITY_NOT_FOUND | entity you are trying modify/delete does not exist |
ENTITY_EXISTS | entity you are trying to create already exists |
UNAUTHORIZED | in a secured cluster, you are not authorized to do this operation |
UNAUTHENTICATED | in a secured cluster, you are not authenticated |
ILLEGAL_ARGUMENT | the configuration object you passed in for this operation is not valid. |