JEP draft: REST APIs for JMX

OwnerHarsha Wardhana B
Created2016/12/15 14:05
Updated2017/09/06 03:35
TypeFeature
StatusSubmitted
Componentcore-svc / javax.management
ScopeJDK
Discussionserviceability dash dev at openjdk dot java dot net
EffortL
DurationL
Priority4
Reviewed byMikael Vidstedt, Staffan Larsen
Issue8171311

Summary

Provide RESTful web interfaces to MBeans registered in platform MBean server. MBeans will be exposed as resources which can be manipulated via HTTP verbs such as GET and POST.

Goals

Non Goals

Motivation

In order to manipulate MBeans registered in an MBean server, a java client is currently required. Any non-java program needs to spawn a JVM in order to interact with MBean server. A more light weight alternative to retrieve JVM runtime metrics is needed.

REST is the de facto standard for exposing APIs as web services. Exposing the MBeans through a REST API means that they can be accessed in a language/platform-independent, ubiquitous and seamless manner.

Description

JMX Architecture is comprised of three levels:

The REST adapter is a part of the Distributed services level. Connectors mirror the interfaces of agent level services to remote clients, whereas adapters transform agent level services to different protocol. The proposed functionality will transform Agent level services to REST APIs, hence the name "REST adapter".

Lifecycle

REST adapter can be started along with JVM via command-line argument. Hooks will be provided for JCMD to start/shutdown the adapter on-demand.

REST Interfaces

REST APIs are designed to allow self discovery of the URL for resources instead of publishing a separate URL per resource. The existing HTTP server implementation – com.sun.net.httpserver – will be used to host the REST adapter. The adapter will install a URL handler for the base URL. The remainder of the URL will be parsed by the handler and a call will be routed to the MBean server.

Base URL

Non-java clients must be able to learn the REST base URL without writing Java code. Clients, both Java and non-Java must be able to learn the base URL programatically. Hence it will be:

The adapter will choose a random port unless configured otherwise and the base URL can be constructed as http://<IP_ADDR>:<PORT>/jmx/default. The base URL will henceforth be referred to as root.

HTTP Request

HTTP GET

HTTP GET will be used to read attributes. The result will be sent as part of HTTP response as a JSON string. Below is list of the URLs for HTTP GET

root/mbeans

Lists names of all MBeans registered in the MBean server. Once names are retrieved, they can be used for below GET requests

root/<mbean_name>

Get MBeanInfo as a JSON string. This can be used to learn all attributes and operations of a given MBean

root/<mbean_name>/<attribute_name>

Get the attribute value of an MBean as a JSON String.

root/<mbean_name>/?attributes=a,b,c|all

Get multiple attributes for an MBean

root/domains

Get a list of all domains

root/?domain=default

Get the default domain

root/?domain=<domain_name>/mbeans

Get the list of all MBeans belonging to a domain

For example, reading HeapMemoryUsage from MemoryMXBean will follow the below sequence:

{ .... java.lang:type=Memory .... }

{ .... HeapMemoryUsage ..... }

{ value of attribute }

HTTP POST

Unlike HTTP GET, which can only be used to read attributes, HTTP POST requests can be used for all MBean operations. That is, HTTP POST can be used to read/write attributes, as well as execute operations on MBeans. The operation data will be sent in the HTTP request body in the form of a JSON string. The result will be sent as part of HTTP response as a JSON string. The URL for HTTP POST is base url root

HTTP POST Request JSON String follows the below format:

{
	name: <mbean_name>
	read/write/exec: <param_name/exec_name> 
	arguments : { <arguments> }
}

arguments is an optional field to be used for operations which require arguments.

Multiple POST requests can be combined into a single HTTP POST bulk request by providing an array of JSON strings to the POST request:

[
	{
		name: <mbean_name_1>
		read/write/exec: <param_name/exec_name> 
		arguments : { <arguments> }
	},
	{
		name: <mbean_name_2>
		read/write/exec: <param_name/exec_name> 
		arguments : { <arguments> }
	}
]

For example, reading HeapMemoryUsage from the MemoryMXBean will have below request format

{
	name: java.lang:type=Memory
	read: HeapMemoryUsage
}

HTTP Response

The response will be JSON string for both GET and POST requests. If the request succeeds, the response will look something like this:

{
    status: 200;
    request: { original HTTP request }
    response: { result of above request }
}

In case of an error, the response looks like this:

{
    status: 4XX/5XX;
    request: { original HTTP request }
    error: <error message>
}

Serialization : JSON to Java Object mapping and vice versa

A universal JSON string to Java object conversion and vice-versa cannot be done without client-provided mapper functions. MBeans of type MXBeans and OpenMBeans use a closed set of classes and hence the mapper functions can be provided by the adapter itself. For the current implementation only MXBeans and OpenMBeans will be supported to keep the serialization implementation simple. The default implemention does the following mapping between JSON types and Opentype:

java.lang.Boolean

JSON Boolean

boolean[]

JSON Boolean Array

java.lang.Byte, java.lang.Short, java.lang.Integer,java.lang.Long, java.lang.Float, java.lang.Double,
java.math.BigDecimal, java.math.BigInteger

JSON Number

byte[], short[], int[], long[], float[], double[]

JSON Number Array

java.lang.Character, char[], java.lang.String, java.util.Date, javax.management.ObjectName

JSON String

javax.management.openmbean.CompositeData

JSON Object

javax.management.openmbean.TabularData

JSON Array

JSON Parser

The REST adapter will come with a simple and lightweight JSON parser.

Security

The REST adapter will use the same security settings (credentials, SSL Configuration, roles, permissions) as used by the JMX agent.

If authentication is configured for the JMX agent, clients will have to use Basic HTTP authentication where username and password are sent as unencrypted base64 encoded text for every HTTP request. Credentials used will be same as used to authenticate the JMX agent. Use of HTTPS is highly recommended as credentials will otherwise be transported in clear.

If SSL is configured for the default JMX agent, the REST adapter will use HTTPS instead of HTTP. Clients will need to setup certificates for SSL before talking to the JMX agent via HTTPS.

Risks and Assumptions

There are no major risks associated with this feature. The same security control for the existing JMX connector will be reused for this adapter.

Testing

A set of new tests will be needed. Existing tests cannot be reused.

Alternatives

Impact