| GlassFish Server Open Source Edition 3.1 RESTful API 1.2. Name(s) and e-mail address of Document Author(s)/Supplier:
- Ludovic Champenois: ludovic.champenois@oracle.com
- Jason Lee: jason.d.lee@oracle.com
1.3. Date of This Document: 06/30/2010 2. Project Summary 2.1. Project Description: This project provides a comprehensive, RESTful API for administration a GlassFish installation. The HTTP interface proposed by this one-pager will enable GlassFish management by clients technologies such as browsers (JavaScript), JavaFX, PERL, Ruby etc., in addition to the Java clients it currently supports. This project will expose some GlassFish Admin Commands, as well as GlassFish management and monitoring APIs as HTTP REST urls. 2.2. Risks and Assumptions: In order to provide complete end to end support of the new Admin GUI using the REST APIS, we will have to possibly change some features in key areas like config serverbeans, CLI framework and HK2. Most of the work was done in GlassFish v3, but not that GlassFish 3.1 Admin gui will rely on REST access, we need to track and implement some missing features are we find them for GlassFish 3.1. 3. Problem Summary 3.1. Problem Area: The REST API provides a lightweight, language-agnostic means for the programmatic configuration of the application server. Management and monitoring of GlassFish will no longer be limited to just Java or any particular Java API. This will integrate more cleanly with a GlassFish cloud story where web-centric APIs are available to configure, manage, monitor and administer a running GlassFish cluster environment. 3.2. Justification: Certain classes of applications, including GlassFish's Admin Console, need a way to make administrative changes to the server. Earlier versions of the application server used AMX, a JMX-based (and, thus, Java-centric) solution. This made it difficult at best for non-Java clients to talk to the server. Furthermore, support and continued development of AMX has been halted, so a viable alternative must take its place. 4. Technical Description: 4.0. Details: 4.0.1 Cluster support Since one of the major features of 3.1 is clustering support, the REST API must fully support the new commands and ConfigBeans added to the server to implement clustering. 4.0.2 JMS Support The support for JMS in the REST API is currently very limited when compared to the CLI support. This must be expanded to support the CLI commands currently supported in v3. Comprehensive support for all of the MQ broker commands (e.g., tuning, advanced configuration, etc) is not planned for this release. 4.0.3 Dynamic REST Resource Generation Currently, all REST resources are generated during development by interrogating the HK2 DOM object that represents domain.xml. These resources are then compiled and deployed with REST module. For 3.1, it is desired to move this development-time generation to a run-time discovery and generation, which will allow modules to be added to and removed from the server and still allow REST resources to be available with no additional work from the module developer. For example, the JRuby container is defined in a different java.net project and defines some configbeans for its configuration. This module could be added/removed dynamically in an existing GlassFish installation. Having dynamic resources created at runtime will allow for dynamic exposure of the corresponding REST resources.
The three approaches currently on the table are
- Use ASM to generate the classes
- Generate the source code as we currently do (though at run-time) and use the JDK Compiler APIs to compile the classes
- Leverage internal/"private" Jersey APIs to dynamically register REST endpoints with the container, pointing these endpoints to hard-coded class/methods that will determine the correct behavior based on the request data
The current thinking now is to use ASM, as the generated resources are now extremely minimal and all the behavior is encapsulated in common classes, making the ASM generator easy to maintain if needed. 4.0.4 Authentication tokens The Admin Console will make numerous REST calls on behalf of a user authenticated in the web app. It will be necessary, however, to authenticate each REST call. It is undesirable to store the username and pass in the web app and pass these with each request. The Admin Console team has requested a means by which they can authenticate once, then pass a token with each request to associate it with a previous, successful authentication. See section 4.1.4 for more details. 4.0.5 Mix and Match of ServerBeans and CLI Params. Complete read/write access to all the server configuration is critical. This can be done in many ways :
- pure CRUD layer on top of all the serverbeans
- Mapping of createXXX and deleteXXX CLI commands to REST POST/DELETE verbs
- exposing some DuckType methods via REST
This would require to return either in JSON or XML format a lot of data (usually a collection of Key, Value pairs) that has to be mapped to either serverbeans Attribute Names or CLI @Param parameters. 4.1. Advanced Details: 4.1.1 Introduction to RESTFul HTTP API More sophisticated clients, such as Admin UI, may need fine grained access to configuration. To satisfy the need of such clients, this API will provide direct access to the whole configuration tree. All the backend config beans will be exposed as JAX-RS resources enabling access to their attributes and parent-child relationships. A RESTful web service is based on the following principles:
- Resources and representations. Instead of providing just one endpoint for a particular web service and having that endpoint perform various operations, you provide access to resources. A resource is a single piece of a web application that is made accessible to clients.
- Addressability and connectedness. Resources have their representations, but providing representations of resources would be useless if you could not address them. In REST, every resource must have at least one address, that is, one URI. To address the resource, you simply specify the URI. This concept is called "addressability". By publishing a web application, you introduce many different URIs that are connected to each other. Because of that connectedness, the only URI you need to give to your clients is one URI called the "bootstrap URI".
- Uniform interface. Even if you make resources available through URIs and representations to exchange between the client and server, it still does not allow you to establish communication. You need a communication protocol/interface to use. In a REST architecture, such an interface must be uniform. It means that whatever URI you access, the interface should be the same. For instance, on the World Wide Web no matter what URI (resource address) you enter, your web browser simply uses an HTTP GET method to retrieve a corresponding web page (resource representation) and displays it.
- Statelessness. Statelessness means that a web application is not responsible for keeping any information about the state of its clients. REST does not encompass the concept of HTTP sessions. The client is responsible for tracking its own actions (if it needs to). The service maintains its resources and provides a uniform interface to the clients.
REST operates by leveraging the HTTP verbs specified in the W3C specification, two of which are likely familiar to web developers: GET and POST. Some others verbs used by REST are PUT, PATCH, DELETE, and OPTIONS. GET is usually used for read-only operations, and POST is usually reserved for create operations. The DELETE verb is used to delete a resource, and OPTIONS can be used to interrogate a resource for supported methods, attributes, etc. Updates are a bit trickier, as there two verbs dedicated to this function, PUT and PATCH. While a complete discussion of the beyond the scope of this document, their use can summarized as follows: PUT should be used for updating an entire entity (i.e., the entity is replaced by the one submitted from the client) and PATCH should be used to update a subset of an entity. Discussions on how to handle these verbs is still ongoing. The RESTFul architecture applies well to expose access to the generic @Configured ConfigBeans layer described in HK2 (GlassfishV3Final_hk2_overview#section-GlassfishV3Final_hk2_overview-4.1.4ConfigurationSupport). HK2 Configured objects represent configuration that will be used by the server, it is usually stored in an xml file (like the domain.xml in GlassFish). Such configuration is described using interface definitions that are binding interfaces (like JAXB interfaces) using annotations in the Config module. An interface is annotated with the @Configured annotation, and XML attributes can be described using the @Attribute annotation while XML sub elements are defined with a @Element annotation. @Element can return a single object or a List of objects. Example :
@Configured
public interface SomeConfig extends ConfigBeanProxy {
@Attribute
String getAttributeName();
@Element
SubConfig getSub();
}
GlassFish 3.x backend configuration is mostly described in the admin/config-api module (and for Grizzly configuration, in the Grizzly component). The root of all the ConfigBeans is the "Domain" object that holds a reference to all the configbeans available in the system. What is proposed here is to provide access to RESTFul resources that are mapped to the ConfigBeans so that the content of these ConfigBeans can be accessed, modified, created or deleted using the RESTful concepts. The Jersey implementation (https://jsr311.java.net/) which is available now in the Java EE 6 specification is used via a special Grizzly connector to avoid a dependency to the GlassFish Web container. Having minimal dependencies to GlassFish modules permits one, for example, to be able to manage via REST containers like the Jruby/Rails scripting container without our Web Server. The mapping is as follows: Each @Configured configuration will have a REST resource that exposes the list of @Attribute of this configuration (HTTP GET). Navigation rules using JAX-RS sub-path will be available to navigate from one configuration resource to a child configuration resource or to a List of children. HTTP methods (POST, PUT (and possibly PATCH), and DELETE) on these resources will create, update or delete the corresponding ConfigBeans. An optional redirect to actual AdminCommand is possible to implement these POST, PUT/PATCH, DELETE methods to guarantee the behavior of the actions. DELETE is exposed only on specific resources. For example, the Domain resource should not have a DELETE operation for obvious reasons (catastrophic results will happen). The top level URL for accessing the entire resources is
http://machinename:adminport/management
For example, to get the list of Attributes and child Elements of the Domain ConfigBeans, the following URL will be used:
http://localhost:4848/management/domain
This is the main entry point to access to all the sub configurations. The output will always be as HTML by default (on Safari, Chrome, IE and Firefox). The HTML view has some convenient content to allow for navigation to child resources as well as Create, Update or Delete Forms when possible.
Via the browser, one can also specify easily the type of the representation by adding the .xml or .json or .html extension.
For example:
http://localhost:4848/management/domain.html
http://localhost:4848/management/domain.json
http://localhost:4848/management/domain.xml
will return the appropriate media representation of the resource. Of course, after this extension, one can add the optional parameters if needed. When the child Element is a List of other ConfigBeans, a corresponding resource will be exposed for this collection. To select one element among N inside this Collection, one must specifies the value of a Key attribute (@Attribute annotation supports the definition of a Key). The value of the Key is passed as a sub-path What if the key contains the "/" char? For such resources, we have enabled a property on the Grizzly Adapter to allow encoding of special characters in the URL. For example, the collection of JDBC-RESOURCES can be accessed via:
http://localhost:4848/management/domain/resources/jdbc-resource
There are 2 jdbc-resource children, called "jdbc/*TimerPool" "jdbc/*default" that contain the "/" character in their name which is the unique key field to identify them. To access the "jdbc/__TimerPool" resource, you can use:
http://localhost:4848/management/domain/resources/jdbc-resource/jdbc%2F__TimerPool
It is also possible to add some child resources to a given configbean REST resource, but attaching a GlassFish Command to it. For example the ConfigBean "Domain" is associated to the REST resource "/management/domain" and we can add the 3 CLI commands (uptime, stop, restart) to some corresponding child resource:
http://localhost:4848/management/domain/uptime
http://localhost:4848/management/domain/stop
http://localhost:4848/management/domain/restart
Our generator allows us to specify the type of HTTP method for each of these added commands. It is expected that for CLI commands that do not modify the backend (like for example the "uptime" command), a simple GET can return the result of the command. For CLI commands that modify the state of the backend (as stop or restart do), a POST has to be used to execute the command. The payload of these resources can be in XML, JSON, or APPLICATION_FORM_URLENCODED and should contain all the Command parameters necessary to execute this command on the server side. The returned document from these CLI resources is derived from the corresponding ActionReporter class of the CLI backend. We are currently modifying it so that commands that return structured data (for example, a List<Tuple<String,String>>) will have a parsable XML and JSON output without the need to do command output parsing on the client side. The combination of full access to the GlassFish configbeans and the CLIs that implement transactional, and authoritative complex business logic on the admin backend will provide the necessary set of APIs for a comprehensive server management via HTTP(s) REST access. 4.1.2 Output Formats RESTFul configuration APIs will leverage existing support for XML, HTML and JSON representations. Additional representations can be plugged-in, if there is a requirement. For the supported representations, the output format will be as defined below. As you can see in the following examples, the Domain ConfigBean has log-root, application-root and version as attributes. We can see the values. Default values will be also be shown. The Domain also has children resources: applications, resources, servers, configs and property. Navigating between parent-children resources is very natural using URL sub-paths. JSON format
{"entity":{attributes}, "methods" :[method-metadata] , "resources":[values]}
Where:
- attributes: one or more Attribute value pairs separated by comma(,)
- method-metadata: one or more HTTP method with the list of messageParameters each describing the possible field name, default value, type, field key, and wether the field is optional or not.
- values: one or more child resource urls separated by comma(,).
Having the list of child resources is useful for auto-discovering on the client side the potential sub resources. This also could achieve via the WADL application.wadl file (see section 4.1.5 below), or calling each resource with the HTTP OPTIONS method that would return only the meta-data portion of the resource. Example of a complete resource, the "domain" resource: http://localhost:4848/management/domain.json JSON Output:
{
"entity":{
"logRoot":"${com.sun.aas.instanceRoot}/logs",
"applicationRoot":"${com.sun.aas.instanceRoot}/applications",
"locale":"",
"version":"ludo-private"
},
"methods":{
"method":{
"name":"POST",
"messageParameters":{
"applicationRoot":{"optional":"true", "type":"string", "key":"false"},
"locale":{"optional":"true", "type":"string", "key":"false"},
"logRoot":{"optional":"true", "type":"string", "key":"false"},
"version":{"optional":"true", "type":"string", "key":"false"}
}
},
"method":{
"name":"GET"
}
},
"childResources":[
"http://localhost:4848/management/domain/configs",
"http://localhost:4848/management/domain/resources",
"http://localhost:4848/management/domain/clusters",
"http://localhost:4848/management/domain/nodes",
"http://localhost:4848/management/domain/servers",
"http://localhost:4848/management/domain/property",
"http://localhost:4848/management/domain/applications",
"http://localhost:4848/management/domain/system-applications",
"http://localhost:4848/management/domain/create-instance",
"http://localhost:4848/management/domain/delete-instance",
"http://localhost:4848/management/domain/start-instance",
"http://localhost:4848/management/domain/stop-instance",
"http://localhost:4848/management/domain/host-port",
"http://localhost:4848/management/domain/list-logger-levels",
"http://localhost:4848/management/domain/list-instances",
"http://localhost:4848/management/domain/restart",
"http://localhost:4848/management/domain/rotate-log",
"http://localhost:4848/management/domain/set-log-level",
"http://localhost:4848/management/domain/stop",
"http://localhost:4848/management/domain/uptime",
"http://localhost:4848/management/domain/version"
]
}
XML format
<entity attributes>
<methods>
<method name="POST or PUT or DELETE or PATCH or GET">
<messageParameters>
...n of them
<messageParameters>
</methods>
</methods>
<childResources>
<childResource>resource url</childResource>
...
<childResources>
</entity>
- attributes: name-value pairs separated by space(blank)
- method-metadata: one or more HTTP method with the list of messageParameters each describing the possible field name, default value, type, field key, and wether the field is optional or not.
- resource url: url of the sub-resource
Example http://localhost:4848/management/domain.xml Output:
<entity
logRoot="${com.sun.aas.instanceRoot}/logs"
applicationRoot="${com.sun.aas.instanceRoot}/applications"
locale=""
version="ludo-private">
<methods>
<method name="POST">
<messageParameters>
<applicationRoot optional="true" type="string" key="false"/>
<locale optional="true" type="string" key="false"/>
<logRoot optional="true" type="string" key="false"/>
<version optional="true" type="string" key="false"/>
</messageParameters>
</method>
<method name="GET">
</method>
</methods>
<childResources>
<childResource>http://localhost:4848/management/domain/configs</childResource>
<childResource>http://localhost:4848/management/domain/resources</childResource>
<childResource>http://localhost:4848/management/domain/clusters</childResource>
<childResource>http://localhost:4848/management/domain/nodes</childResource>
<childResource>http://localhost:4848/management/domain/servers</childResource>
<childResource>http://localhost:4848/management/domain/property</childResource>
<childResource>http://localhost:4848/management/domain/applications</childResource>
<childResource>http://localhost:4848/management/domain/system-applications</childResource>
<childResource>http://localhost:4848/management/domain/create-instance</childResource>
<childResource>http://localhost:4848/management/domain/delete-instance</childResource>
<childResource>http://localhost:4848/management/domain/start-instance</childResource>
<childResource>http://localhost:4848/management/domain/stop-instance</childResource>
<childResource>http://localhost:4848/management/domain/host-port</childResource>
<childResource>http://localhost:4848/management/domain/list-logger-levels</childResource>
<childResource>http://localhost:4848/management/domain/list-instances</childResource>
<childResource>http://localhost:4848/management/domain/restart</childResource>
<childResource>http://localhost:4848/management/domain/rotate-log</childResource>
<childResource>http://localhost:4848/management/domain/set-log-level</childResource>
<childResource>http://localhost:4848/management/domain/stop</childResource>
<childResource>http://localhost:4848/management/domain/uptime</childResource>
<childResource>http://localhost:4848/management/domain/version</childResource>
</childResources>
</entity>
HTML format
<html><body>
<h1>type</h1><hr>
<h2>attribute: value</h2>
...
<h1>resources</h1><hr>
<h2>resource url</h2>
...
</body></html>
- type: type of the resource
- attribute: name of the attribute
- value: value of the attribute
- resource url: url of the sub-resource
4.1.3 Log Viewer Resource The server.log of an instance is not managed by a ConfigBean, and is not accessible via CLI, so we have created a specific set of REST resources for viewing its content. The first resource is accessible under
http://localhost:4848/management/domain/view-log
It returns in text the content of the log file (gzipped if the client supports it) until the end od the file. It also returns an HTTP header called "X-Text-Append-Next" which when defined contains the entire URL to call via GET to get the delta content of the log file from the last call. So if you use a client thread looping every 3 seconds and testing the value of the header called
you can get all the new log entries since the last 3 seconds.
An optional start param
http://localhost:4848/management/domain/view-log?start=10000
allows to specify the characters number you want to skip from the start of the file. (If it is larger than the file size, 0 is assumed. Another REST resource returns in JSON or XML format (Only JSON as of today) a structured view of the log file (the same way AMX used to return the log content to the admin gui). The resource is at
http://localhost:4848/management/domain/view-log/details
The JSON output is like:
{
"records": [{
"recordNumber":145,
"loggedDateTimeInMS":1277905336097,
"loggedLevel":"INFO",
"productName":"glassfish3.1",
"loggerName":"null",
"nameValuePairs":"_ThreadID=27;_ThreadName=Thread-1;",
"messageID":"",
"Message":"The Admin Console application is loaded."}
,
{
"recordNumber":144,
"loggedDateTimeInMS":1277905336097,
"loggedLevel":"INFO",
"productName":"glassfish3.1",
"loggerName":"null",
"nameValuePairs":"_ThreadID=27;_ThreadName=Thread-1;",
"messageID":"",
"Message":"Loading __admingui Application done is 8523 ms"}
,
{
"recordNumber":143,
"loggedDateTimeInMS":1277905336095,
"loggedLevel":"INFO",
"productName":"glassfish3.1",
"loggerName":"javax.enterprise.system.container.web.com.sun.enterprise.web",
"nameValuePairs":"_ThreadID=68;_ThreadName=Thread-1;",
"messageID":"WEB0671",
"Message":" Loading application [__admingui] at [/]"}
,
{...
This is an array of log entries, each entry having the following attributes: "recordNumber","loggedDateTimeInMS","loggedLevel","productName","loggerName","nameValuePairs","messageID","Message".
It is possible to refine the query for this array with the following HTTP params (similar again to what AMX log viewer APIs defined):
- "logFileName" with default value of "${com.sun.aas.instanceRoot}/logs/server.log")
- "startIndex" with default value of "-1"
- "searchForward" with default value of "false"
- "maximumNumberOfResults" with default value of "40"
- "fromTime" with default value of "-1" a long value in milliseconds
- "toTime" with default value of "-1" a long value in milliseconds
- "logLevel" with default value of "INFO"
Admin GUI should be able to use this resource as it maps exactly in terms of APIs to the corresponding AMX api used for the log viewer in Admin GUI 3.0. 4.1.4 Security Support
- The REST resources are protected by HTTP Basic Auth. Using Basic Auth should be sufficient if HTTPS is used at transport layer. However, it requires REST client to cache credentials so that it can be passed with each request.
- If it is not acceptable for a REST client to cache credentials, it can use Session Token mechanism. The mechanism works as follows:
- Client requests a session token using GET on http://localhost:4848/management/sessions. Basic auth is used to authenticate the client. A session token is generated and passed to the client
- The client can use this token to authenticate for subsequent requests. The token needs to be sent as a value of cookie named "gfresttoken" for the subsequent requests.
- The client retires the token by using DELETE on http://localhost:4848/management/sessions/\{tokenvalue}
- If a client does not explicitly retire a token, it gets retired after inactivity of 30 mins.
- Investigation is underway to see if we can use HTTP Digest mechanism to authenticate. If we decide to use it, work needs to be done on Jersey Client side for this.
4.1.5 WADL representation Since the GlassFish REST admin backend is a JAX-RS application, the application.wadl Web Application Definition Language file is avaialable at the standard location:
http://localhost:4848/management/application.wadl
It contains the complete meta-data information in XML for all the resources that are available and the resource paths, as well as all the HTTP methods available on each resource. Here is a subset of our current WADL file as generated by the JAX-RS backend for our REST application:
<application xmlns="http://research.sun.com/wadl/2006/10">
<doc xmlns:jersey="http://jersey.java.net/" jersey:generatedBy="Jersey: 1.1.5 01/20/2010 04:04 PM"/>
<resources base="http://localhost:4848/management/">
<resource path="/sessions">
<method id="create" name="POST">
<response>
<representation mediaType="*/*"/>
</response>
</method>
<resource path="{sessionId}/">
<param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="sessionId" style="template" type="xs:string"/>
<method id="delete" name="DELETE">
<response>
<representation mediaType="*/*"/>
</response>
</method>
</resource>
</resource>
<resource path="/domain/">
<method id="get" name="GET">
<request>
<param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="expandLevel" style="query" type="xs:int" default="1"/>
</request>
<response>
<representation mediaType="text/html;qs=2"/>
<representation mediaType="application/json"/>
<representation mediaType="application/xml"/>
<representation mediaType="application/x-www-form-urlencoded"/>
</response>
</method>
<method id="delete" name="DELETE">
<request>
<representation mediaType="application/json"/>
<representation mediaType="application/xml"/>
<representation mediaType="application/x-www-form-urlencoded"/>
<representation mediaType="application/octet-stream"/>
</request>
<response>
<representation mediaType="*/*"/>
</response>
</method>
<method id="options" name="OPTIONS">
<response>
<representation mediaType="application/json"/>
<representation mediaType="text/html;qs=2"/>
<representation mediaType="application/xml"/>
</response>
</method>
<method id="updateEntity" name="POST">
<request>
<representation mediaType="application/json"/>
<representation mediaType="application/xml"/>
<representation mediaType="application/x-www-form-urlencoded"/>
</request>
<response>
<representation mediaType="text/html;qs=2"/>
<representation mediaType="application/json"/>
<representation mediaType="application/xml"/>
</response>
</method>
...
4.1.7 Cluster DAS, and Instances Support While running in a cluster, the REST management adapter will only be available the Domain Administration Server (DAS). Some security changes will have to be implemented at the REST Grizzly adapter. TBD. We need to decide whether the monitoring adapter will be available on all instances or only on DAS. TBD. 4.1.8 Jersey Optimization for local access of REST resources The current main client for the REST admin back end is the GlassFish JSF Admin GUI. Currently, this application is running in the same process as the GlassFish process and the REST application. If performance of Admin GUI accessing the REST resources is an issue, we can implement a layer between the JAX-RS Jersey Client and the Server side to by pass the HTTP traffic in local mode. There are ways with our Jersey implementation to implement that in a transparent way. 4.1.8 Monitoring Support Monitoring HTTP API enables monitoring of GlassFish through HTTP urls. This support enable GlassFish monitoring through new tools and technologies. For example, using these API's cloud computing provider can charge customers based on number of sessions, number of requests etc. This API essentially exposes telemetry objects as HTTP urls. This RESTFul API will provide direct access to the whole monitoring tree. Monitoring Output Formats: Monitoring API supports following output formats XML, HTML and JSON. Additional representations can be plugged-in/provided, if there is a requirement.
For the supported representations the output format will be same as defined for config objects Using this, the output format for specific data types will be: Example 1 Output for Statistic object in JSON format:
{"{statistic}":{
"name"="xyz",
"unit"="xyz",
"description"="xyz",
"start-time"=xyz,
"last-sample-time"=xyz}}
in XML format:
<statistic name="xyz"
unit="xyz" description="xyz"
start-time="xyz"
last-sample-time="xyz">
in HTML format.
<html><body>
<h1>statistic</h1>
<hr>
<h2>name: xyz</h2>
<h2>unit: xyz</h2>
<h2>description: xyz</h2>
<h2>start-time: xyz</h2>
<h2>last-sample-time: xyz</h2>
</body></html>
Example 2 Output for Range Statistic object
JSON
{"range-statistic":
{"high-water-mark"=xyz,
"low-water-mark"=xyz,
"current"=xyz,
"name"="xyz",
"unit"="xyz",
"description"="xyz",
"start-time"=xyz,
"last-sample-time"=xyz}}
XML
<range-statistic high-water-mark="xyz"
low-water-mark="xyz" current="xyz"
name="xyz" unit="xyz"
description="xyz"
start-time="xyz"
last-sample-time="xyz">
HTML
<html><body>
<h1>range-statistic</h1>
<hr>
<h2>high-water-mark: xyz</h2>
<h2>low-water-mark: xyz</h2>
<h2>current: xyz</h2>
<h2>name: xyz</h2>
<h2>unit: xyz</h2>
<h2>description: xyz</h2>
<h2>start-time: xyz</h2>
<h2>last-sample-time: xyz</h2>
</body></html>
Monitoring URL Format: The monitoring URLs can have the following format
http://host:port/monitoring/path
- host: server host
- port: administration port
- path: identifies the resource
Monitoring Methods: Monitoring API will support get and options HTTP methods. GET /monitoring/{path} HTTP/1.1 Get the given object OPTIONS /monitoring/{path} HTTP/1.1 Get meta-data of the resource 4.2. Bug/RFE Number(s): 4.3. In Scope:
- Full support for the new cluster administration commands under development for 3.1
- Limited support for JMS administration
4.4. Out of Scope:
- Comprehensive OpenMQ support
4.5. Interfaces: 4.5.1 Public Interfaces
- the management URL: http://servername:PortNumber/management/
- the set of resources under this url is by nature dynamic, depending on the GlassFish configuration (set of modules installed).
- the output for each ConfigBean resource is depending on the corresponding ConfigBean structure and attributes (defined via the @Attribute HK2 annotation)
- the ouptut of each CLI command resource depends on the list of params of this CLI. The XML and JSON output relies on the corresponding ActionReporter and how the command defines its output via the reporter
- the monitoring URL http://servername:PortNumber/monitoring/
- We are considering unifying both management and monitoring REST services under single context root. Apart from being more natural, this will allow us to handle authentication at single place. Thus we will have http://servername:PortNumber/rest/management/ and http://servername:PortNumber/rest/monitoring/ as the base URLs for management and monitoring respectively.
4.5.2 Private Interfaces None identified at this time 4.5.3 Deprecated/Removed Interfaces: None identified at this time 4.6. Doc Impact: Since the REST API will be the official means by which third parties can administer the server, documentation must be generated detailing how to use the API. 4.7. Admin/Config Impact: The Admin Console will have to be modified to support changes in the REST API. 4.8. HA Impact: Cluster support is a planned feature of the module. 4.9. I18N/L10N Impact: None anticipated 4.10. Packaging, Delivery & Upgrade: 4.10.1. Packaging This proposal will affect only the rest-services.jar already shipped with the server. 4.10.2. Delivery No impact on delivery. The module is already included in the distribution. 4.10.3. Upgrade and Migration: This should not affect any existing instances or clients, as there are no known clients of the API at this point in time. 4.11. Security Impact: The REST API is secured using the same admin realm as the console. Discussions are underway to determine if additional authentication mechanisms need to be added to allow for a more secure Admin Console. 4.12. Compatibility Impact None anticipated. 4.13. Dependencies: 4.13.1 Internal Dependencies
4.13.2 External Dependencies
4.14. Testing Impact: The existing REST infrastructure has no existing tests. Devtests will be created as part of this effort. 5. Reference Documents:
6. Schedule: 6.1. Projected Availability: See Project Page (linked above)
|
