Extending the REST Manager API
The REST REpresentational State Transfer. Application Programming Interface An API, or application programming interface, is a set of rules that define how applications or devices can connect to and communicate with each other. A REST API is an API that conforms to the design principles of the REST, or representational state transfer architectural style. Manager API is extensible so that custom methods can be added. Developers can implement a plain Java class with JAX-RS annotations.
Sample Implementation
Follow the instructions below to create a sample extension for the REST Manager API:
- Create a class and annotate it with
com.gigaspaces.manager.rest.CustomManagerResource
. - Create a method for each path you wish to intercept, and annotate it with an HTTP operation (e.g.
@GET
) and a@Path
annotation with the relevant path. - Use JAX-RS parameter annotations (e.g.
@QueryParam
) to map HTTP request parameters to your method. - If you wish to use
Admin
, create an appropriate field and annotate it with JAX-RS@Context
annotation.
For example:
@CustomManagerResource
@Path("/demo")
public class BasicPluggableOperationTest {
@Context Admin admin;
@GET
@Path("/report")
public String report(@QueryParam("hostname") String hostname) {
Machine machine = admin.getMachines().getMachineByHostName(hostname);
return "Custom report: host=" + hostname +
", containers=" + machine.getGridServiceContainers() +
", PU This is the unit of packaging and deployment in the GigaSpaces Data Grid, and is essentially the main GigaSpaces service. The Processing Unit (PU) itself is typically deployed onto the Service Grid. When a Processing Unit is deployed, a Processing Unit instance is the actual runtime entity. instances=" + machine.getProcessingUnitInstances();
}
}
This class maps an HTTP GET
operation in the /demo/report
path to a report
method. It accepts a query parameter, and uses an injected Admin
instance to perform user-defined code (in this case, a custom report). For example, http://localhost:8090/v2/demo/report?hostname=mypc
.
To run the example, compile it and package it into a .jar file, then copy the .jar to $GS_HOME/lib/platform/manager/plugins
and start the GigaSpaces Manager.
Some JAX-RS features are not supported - see JAX-RS Support below for detailed information.
You must declare a new path, not one that already exists in the built-in REST Manager API. For example, @Path("/pus/...")
won't work because path/pus
already exists in the REST Manager API.
Configuration
When the GigaSpaces Manager starts, it scans the $GS_HOME/lib/platform/manager/plugins
for classes in the jar files with the JAX-RS annotations and registers them.
You can override the location using the following system property:
com.gs.manager.rest.plugins.path="pathToJar"
Response
In the example above the method returns a String, and in addition it implicitly returns an HTTP code 200 (OK). If you need to explicitly specify the HTTP result code, use org.openspaces.admin.rest.Response
instead of a String
.
For example:
import org.openspaces.admin.rest.Response
@GET
@Path("/report")
public Response report(@QueryParam("hostname") String hostname) {
Machine machine = admin.getMachines().getMachineByHostName(hostname);
if (machine == null)
return Response.status(javax.ws.rs.core.Response.Status.NOT_FOUND).entity("Host not found").build();
String result = "Custom report: host=" + hostname +
", containers=" + machine.getGridServiceContainers() +
", PU instances=" + machine.getProcessingUnitInstances();
return Response.ok().entity(result).build();
}
Make sure you use org.openspaces.admin.rest.Response
and not JAX-RS Response.
Security
To define security privileges for a custom method, you have to import org.openspaces.admin.rest.PrivilegeRequired
and org.openspaces.admin.rest.RestPrivileges
, and use @PrivilegeRequired
.
The @PrivilegeRequired
annotation accepts a RestPrivileges
enum that corresponds to the Security privileges.
For more information about security, see the Security Guide.
For example:
import org.openspaces.admin.rest.PrivilegeRequired
import org.openspaces.admin.rest.RestPrivileges
@CustomManagerResource
@Path("/secured/")
public class PluggableSecuredContoller {
@Context Admin admin;
@PrivilegeRequired(RestPrivileges.MANAGE_GRID)
@GET
@Path("/getBase")
public String getBase() {
return "hello";
}
}
JAX-RS Support
The JAX-RS
API is used for extension support because it is a well-known standard and commonly used by developers. The sections below list the annotations that are supported, and those that are not supported.
Supported Annotations
The following JAX-RS annotations are supported:
- HTTP operations:
@GET
,@PUT
,@POST
,@DELETE
- Parameters:
@QueryParam
,@PathParam
,@DefaultValue
- Supported types: Java primitive types ("int', "long', etc.) and
String
- Supported types: Java primitive types ("int', "long', etc.) and
- Other:
@Context
- Fields only (No support for constructors or method arguments)
- Supported types:
Admin
Unsupported Annotations
The following JAX-RS annotations are not supported:
- HTTP operations:
@OPTIONS
,@HEAD
- Parameters:
@FormParam
,@HeaderParam
,@CookieParam
,@MatrixParam
- Other:
@Consumes
,@Produces