1. Coherence REST APIREST API for Managing Oracle Coherence
  2. Quick Start

Quick Start

Set up your environment and access management data using the REST API by performing the steps described below.

Note:

The quick start steps are specific to managing standalone Coherence. If you are using managed Coherence servers in a WebLogic Server domain, then access management information using the following URL:

http://<admin-host>:<admin-port>/management/coherence/<version>/clusters
  • The version number should be the full five digit number, such as 14.1.1.0.0.
  • The version can also be latest.

All REST resources in the API reference are available for managed Coherence servers.

Prerequisites

Prerequisite More Information

Coherence

Install Coherence and setup a cluster. See Installing Oracle Coherence for Java in Installing Oracle Coherence.

cURL

The examples within this document use the cURL command-line tool to demonstrate how to access the Oracle Coherence management REST API. You can download cURL at http://curl.haxx.se.

Step 1: Enable REST Management

REST management is enabled through an HTTP management server that runs as a proxy on the Coherence cluster. The HTTP management server requires the COHERENCE_HOME\lib\coherence-management.jar library as well as third-party dependencies. The server starts when <http-managed-nodes> element in management-config is set to either all or inherit and the required libraries are found on the classpath. If the libraries are not found, then Coherence log messages indicate that the management libraries are missing and that management over HTTP is not available. The Coherence distribution does not include the third-party libraries.

It is a best practice to manage dependencies using Maven. It is assumed that the latest Oracle Coherence artifacts are installed in your local maven repository using the Oracle Maven Synchronization Plug-in as described in Populating the Maven Repository Manager. To generate a classpath containing third party libraries, run the following Maven command with the provided pom.xml below. Add the generated classpath to start server script. 

mvn dependency:build-classpath

Note:

  • If running with JDK 11, add -P jdk11 to mvn command line to get additional libraries that are no longer part of JDK 11.
  • When copying this pom.xml for your use, update the coherence <version> after <groupId>, to match the coherence patch version that you are using. 
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <artifactId>management</artifactId>
  <groupId>management</groupId>
  <version>14.1.1-0-0</version>
  <name>Coherence Management Over REST dependencies</name>
  <packaging>pom</packaging>
  
  <dependencies>
    <dependency>
      <groupId>com.oracle.coherence</groupId>
      <artifactId>coherence-management</artifactId>
      <version>${project.version}</version>
    </dependency>
  </dependencies>
  
  <profiles>
    <profile>
      <id>jdk11</id>
      <properties>
        <com.sun.xml.bind.version>2.3.0</com.sun.xml.bind.version>
        <javax.activation.version>1.1.1</javax.activation.version>
      </properties>
      <dependencies>
	<dependency>
          <groupId>com.sun.xml.bind</groupId>
          <artifactId>jaxb-core</artifactId>
          <version>${com.sun.xml.bind.version}</version>
        </dependency>
        <dependency>
          <groupId>com.sun.xml.bind</groupId>
          <artifactId>jaxb-impl</artifactId>   
          <version>${com.sun.xml.bind.version}</version>
        </dependency>
        <dependency>
          <groupId>javax.activation</groupId>
          <artifactId>activation</artifactId>
          <version>${javax.activation.version}</version>
        </dependency>
        <dependency>
          <groupId>javax.xml.bind</groupId>
          <artifactId>jaxb-api</artifactId>
          <version>${com.sun.xml.bind.version}</version>
        </dependency>
      </dependencies>
    </profile>
  </profiles>

</project>

All the required libraries are automatically downloaded. To see the complete list of libraries, run the following Maven command:

mvn dependency:list

Note:

To change the management over REST port, see Changing the HTTP Management Server Address in Managing Oracle Coherence.

Step 2: Obtain the Management URL

This step describes how to obtain the management URL when a cluster's dynamic HTTP management server is enabled by configuring management-config child element <http-named-nodes> to inherit.

The Coherence logs indicate the HTTP management server port:

(thread=Proxy:ManagementHttpProxy:HttpAcceptor, member=1): HttpAcceptor now listening for connections on 0:0:0:0:0:0:0:0:30000

You can also query the NameService service on any cluster member using the com.tangosol.discovery.NSLookup class. For example: 

java -cp %COHERENCE_HOME%\lib\coherence.jar com.tangosol.discovery.NSLookup -name management/HTTPManagementURL

Cluster MyCluster:      [http://127.0.0.1:30000/management/coherence/cluster]

Step 3: Access Management Information

The following example uses cURL to demonstrate using the REST API. The example gets a list of caches on the cluster and then gets detailed management information for a cache named hello-example.

Request:

curl -i -X GET http://127.0.0.1:30000/management/coherence/cluster/caches

Response:

HTTP/1.1 200 OK
Content-Type: application/json
content-length: 697
connection: keep-alive

{
	"links": [{
		"rel": "parent",
		"href": "http://127.0.0.1:30000/management/coherence/cluster"
	}, {
		"rel": "self",
		"href": "http://127.0.0.1:30000/management/coherence/cluster/caches"
	}, {
		"rel": "canonical",
		"href": "http://127.0.0.1:30000/management/coherence/cluster/caches"
	}],
	"items": [{
		"links": [{
			"rel": "parent",
			"href": "http://127.0.0.1:30000/management/coherence/cluster/caches"
		}, {
			"rel": "self",
			"href": "http://127.0.0.1:30000/management/coherence/cluster/caches/hello-example"
		}, {
			"rel": "canonical",
			"href": "http://127.0.0.1:30000/management/coherence/cluster/caches/hello-example"
		}, {
			"rel": "members",
			"href": "http://127.0.0.1:30000/management/coherence/cluster/caches/hello-example/members"
		}],
		"name": "hello-example"
	}]
}

Request:

curl -i -X GET http://127.0.0.1:30000/management/coherence/cluster/caches/hello-example

Response:

HTTP/1.1 200 OK
Content-Type: application/json
content-length: 1981
connection: keep-alive

{
	"links": [{
		"rel": "parent",
		"href": "http://127.0.0.1:30000/management/coherence/cluster/caches"
	}, {
		"rel": "self",
		"href": "http://127.0.0.1:30000/management/coherence/cluster/caches/hello-example"
	}, {
		"rel": "canonical",
		"href": "http://127.0.0.1:30000/management/coherence/cluster/caches/hello-example"
	}, {
		"rel": "members",
		"href": "http://127.0.0.1:30000/management/coherence/cluster/caches/hello-example/members"
	}],
	"name": "hello-example",
	"totalGetsMillis": 0,
	"description": ["Implementation: com.tangosol.net.cache.LocalCache"],
	"lowUnits": 800,
	"size": 19,
	"totalPuts": 20,
	"totalPutsMillis": 0,
	"refreshTime": ["2018-12-14T17:43:40.642+0000"],
	"requeueThreshold": [0],
	"averageMissMillis": {
		"average": 0.0,
		"count": 1,
		"max": 0.0,
		"min": 0.0,
		"sum": 0.0
	},
	"highUnits": 1000,
	"hitProbability": {
		"average": 0.0,
		"count": 1,
		"max": 0.0,
		"min": 0.0,
		"sum": 0.0
	},
	"totalGets": 0,
	"unitFactor": [1],
	"averageHitMillis": {
		"average": 0.0,
		"count": 1,
		"max": 0.0,
		"min": 0.0,
		"sum": 0.0
	},
	"refreshFactor": [0.0],
	"memoryUnits": {
		"false": 1
	},
	"cachePrunesMillis": 0,
	"batchFactor": [0.0],
	"cacheMissesMillis": 0,
	"averageGetMillis": {
		"average": 0.0,
		"count": 1,
		"max": 0.0,
		"min": 0.0,
		"sum": 0.0
	},
	"averagePutMillis": {
		"average": 0.0,
		"count": 1,
		"max": 0.0,
		"min": 0.0,
		"sum": 0.0
	},
	"persistenceType": ["NONE"],
	"cacheStoreType": ["NONE"],
	"units": 19,
	"cacheHits": 0,
	"cacheMisses": 0,
	"expiryDelay": [0],
	"cacheHitsMillis": 0,
	"cachePrunes": 0,
	"evictionCount": 0,
	"insertCount": 19,
	"listenerKeyCount": 0,
	"nonOptimizedQueryTotalMillis": {
		"count": 1,
		"average": 0.0,
		"min": 0,
		"max": 0,
		"sum": 0
	},
	"listenerRegistrations": 0,
	"listenerFilterCount": [0],
	"nonOptimizedQueryCount": 0,
	"locksGranted": 0,
	"indexTotalUnits": 0,
	"optimizedQueryAverageMillis": {
		"count": 1,
		"average": 0.0,
		"min": 0,
		"max": 0,
		"sum": 0
	},
	"optimizedQueryTotalMillis": {
		"count": 1,
		"average": 0.0,
		"min": 0,
		"max": 0,
		"sum": 0
	},
	"removeCount": 0,
	"locksPending": 0,
	"queryContentionCount": 0,
	"eventsDispatched": 0,
	"optimizedQueryCount": 0,
	"maxQueryDurationMillis": 0,
	"maxQueryThresholdMillis": [30],
	"nonOptimizedQueryAverageMillis": {
		"count": 1,
		"average": 0.0,
		"min": 0,
		"max": 0,
		"sum": 0
	}
}