org.pipservices.rpc.services

Class RestService

java.lang.Object

org.pipservices.rpc.services.RestService

All Implemented Interfaces:

org.pipservices.commons.config.IConfigurable, org.pipservices.commons.refer.IReferenceable, org.pipservices.commons.refer.IUnreferenceable, org.pipservices.commons.run.IClosable, org.pipservices.commons.run.IOpenable, IRegisterable

Direct Known Subclasses:

CommandableHttpService, HeartbeatRestService, StatusRestService

public abstract class RestService
extends Object
implements org.pipservices.commons.run.IOpenable, org.pipservices.commons.config.IConfigurable, org.pipservices.commons.refer.IReferenceable, org.pipservices.commons.refer.IUnreferenceable, IRegisterable

Abstract service that receives remove calls via HTTP/REST protocol.

### Configuration parameters ###

• base_route: base route for remote URI
• dependencies:
  • endpoint: override for HTTP Endpoint dependency
  • controller: override for Controller dependency
• connection(s):
  • discovery_key: (optional) a key to retrieve the connection from IDiscovery
  • protocol: connection protocol: http or https
  • host: host name or IP address
  • port: port number
  • uri: resource URI or connection string with all parameters in it

### References ###

• *:logger:*:*:1.0 (optional) ILogger components to pass log messages
• *:counters:*:*:1.0 (optional) ICounters components to pass collected measurements
• *:discovery:*:*:1.0 (optional) IDiscovery services to resolve connection
• *:endpoint:http:*:1.0 (optional) HttpEndpoint reference

### Example ###

 
 class MyRestService extends RestService {
    private IMyController _controller;
    ...
    public MyRestService() {
       super();
       this._dependencyResolver.put(
           "controller",
           new Descriptor("mygroup","controller","*","*","1.0")
       );
    }
 
    public void setReferences(IReferences references) {
       super.setReferences(references);
       this._controller = (IMyController)this._dependencyResolver.getRequired("controller");
    }
 
    public void register() {
        ...
    }
 }
 
 MyRestService service = new MyRestService();
 service.configure(ConfigParams.fromTuples(
     "connection.protocol", "http",
     "connection.host", "localhost",
     "connection.port", 8080
 ));
 service.setReferences(References.fromTuples(
    new Descriptor("mygroup","controller","default","default","1.0"), controller
 ));
 
 service.open("123");
 System.out.println("The REST service is running on port 8080");
 
 

Field Summary

Fields

Modifier and Type	Field and Description
protected String	_baseRoute The base route.
protected org.pipservices.components.count.CompositeCounters	_counters The performance counters.
protected org.pipservices.commons.refer.DependencyResolver	_dependencyResolver The dependency resolver.
protected HttpEndpoint	_endpoint The HTTP endpoint that exposes this service.
protected org.pipservices.components.log.CompositeLogger	_logger The logger.
protected com.sun.net.httpserver.HttpServer	_server
protected String	_url

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RestService()

Method Summary

Modifier and Type	Method and Description
void	close(String correlationId) Closes component and frees used resources.
void	configure(org.pipservices.commons.config.ConfigParams config) Configures component by passing configuration parameters.
protected <T> T	getBodyAsJson(Class<T> type, javax.ws.rs.container.ContainerRequestContext request) Gets request body from json string.
protected String	getBodyAsString(javax.ws.rs.container.ContainerRequestContext request) Gets string value of request body.
protected String	getQueryParameter(javax.ws.rs.container.ContainerRequestContext request, String name)
protected org.pipservices.components.count.Timing	instrument(String correlationId, String name) Adds instrumentation to log calls and measure call time.
boolean	isOpen() Checks if the component is opened.
void	open(String correlationId) Opens the component.
protected void	registerResource(org.glassfish.jersey.server.model.Resource resource) Registers resource in this objects Rest service.
protected void	registerRoute(String method, String route, org.glassfish.jersey.process.Inflector<javax.ws.rs.container.ContainerRequestContext,javax.ws.rs.core.Response> action) Registers a route in HTTP endpoint.
protected javax.ws.rs.core.Response	sendCreatedResult(Object result) Creates a callback function that sends newly created object as JSON.
protected javax.ws.rs.core.Response	sendDeleted(Object result) Creates a callback function that sends deleted object as JSON.
protected javax.ws.rs.core.Response	sendEmptyResult() Creates a callback function that sends an empty result with 204 status code.
protected javax.ws.rs.core.Response	sendError(Exception ex) Sends error serialized as ErrorDescription object and appropriate HTTP status code.
protected javax.ws.rs.core.Response	sendResult(Object result) Creates a callback function that sends result as JSON object.
void	setReferences(org.pipservices.commons.refer.IReferences references) Sets references to dependent components.
void	unsetReferences() Unsets (clears) previously set references to dependent components.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.pipservices.rpc.services.IRegisterable

register

Field Detail

_baseRoute

protected String _baseRoute

The base route.

_endpoint

protected HttpEndpoint _endpoint

The HTTP endpoint that exposes this service.

_dependencyResolver

protected org.pipservices.commons.refer.DependencyResolver _dependencyResolver

The dependency resolver.

_logger

protected org.pipservices.components.log.CompositeLogger _logger

The logger.

_counters

protected org.pipservices.components.count.CompositeCounters _counters

The performance counters.

_server

protected com.sun.net.httpserver.HttpServer _server

_url

protected String _url

Constructor Detail

RestService

protected RestService()

Method Detail

configure

public void configure(org.pipservices.commons.config.ConfigParams config)
               throws org.pipservices.commons.errors.ConfigException

Configures component by passing configuration parameters.

Specified by:

configure in interface org.pipservices.commons.config.IConfigurable

Parameters:

config - configuration parameters to be set.

Throws:

org.pipservices.commons.errors.ConfigException - when configuration is wrong.

setReferences

public void setReferences(org.pipservices.commons.refer.IReferences references)
                   throws org.pipservices.commons.refer.ReferenceException,
                          org.pipservices.commons.errors.ConfigException

Sets references to dependent components.

Specified by:

setReferences in interface org.pipservices.commons.refer.IReferenceable

Parameters:

references - references to locate the component dependencies.

Throws:

org.pipservices.commons.refer.ReferenceException - when no found references.

org.pipservices.commons.errors.ConfigException - when configuration is wrong.

unsetReferences

public void unsetReferences()

Unsets (clears) previously set references to dependent components.

Specified by:

unsetReferences in interface org.pipservices.commons.refer.IUnreferenceable

instrument

protected org.pipservices.components.count.Timing instrument(String correlationId,
                                                             String name)

Adds instrumentation to log calls and measure call time. It returns a Timing object that is used to end the time measurement.

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

name - a method name.

Returns:

Timing object to end the time measurement.

isOpen

public boolean isOpen()

Checks if the component is opened.

Specified by:

isOpen in interface org.pipservices.commons.run.IOpenable

Returns:

true if the component has been opened and false otherwise.

open

public void open(String correlationId)
          throws org.pipservices.commons.errors.ApplicationException

Opens the component.

Specified by:

open in interface org.pipservices.commons.run.IOpenable

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

close

public void close(String correlationId)
           throws org.pipservices.commons.errors.ApplicationException

Closes component and frees used resources.

Specified by:

close in interface org.pipservices.commons.run.IClosable

Parameters:

correlationId - (optional) transaction id to trace execution through call chain.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

sendError

protected javax.ws.rs.core.Response sendError(Exception ex)

Sends error serialized as ErrorDescription object and appropriate HTTP status code. If status code is not defined, it uses 500 status code.

Parameters:

ex - an error object to be sent.

Returns:

HTTP response status

sendResult

protected javax.ws.rs.core.Response sendResult(Object result)

Creates a callback function that sends result as JSON object. That callack function call be called directly or passed as a parameter to business logic components. If object is not null it returns 200 status code. For null results it returns 204 status code. If error occur it sends ErrorDescription with approproate status code.

Parameters:

result - a body object to result.

Returns:

execution result.

sendEmptyResult

protected javax.ws.rs.core.Response sendEmptyResult()

Creates a callback function that sends an empty result with 204 status code. If error occur it sends ErrorDescription with approproate status code.

Returns:

HTTP response status with no content.

sendCreatedResult

protected javax.ws.rs.core.Response sendCreatedResult(Object result)

Creates a callback function that sends newly created object as JSON. That callack function call be called directly or passed as a parameter to business logic components. If object is not null it returns 201 status code. For null results it returns 204 status code. If error occur it sends ErrorDescription with approproate status code.

Parameters:

result - a body object to created result

Returns:

execution result.

sendDeleted

protected javax.ws.rs.core.Response sendDeleted(Object result)

Creates a callback function that sends deleted object as JSON. That callack function call be called directly or passed as a parameter to business logic components. If object is not null it returns 200 status code. For null results it returns 204 status code. If error occur it sends ErrorDescription with approproate status code.

Parameters:

result - a body object to deleted result

Returns:

execution result.

getQueryParameter

protected String getQueryParameter(javax.ws.rs.container.ContainerRequestContext request,
                                   String name)

getBodyAsString

protected String getBodyAsString(javax.ws.rs.container.ContainerRequestContext request)
                          throws org.pipservices.commons.errors.ApplicationException

Gets string value of request body.

Parameters:

request - HTTP request

Returns:

string value of data.

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

getBodyAsJson

protected <T> T getBodyAsJson(Class<T> type,
                              javax.ws.rs.container.ContainerRequestContext request)
                       throws org.pipservices.commons.errors.ApplicationException

Gets request body from json string.

Parameters:

type - the class type of result object.

request - HTTP request

Returns:

converted object value

Throws:

org.pipservices.commons.errors.ApplicationException - when error occured.

registerRoute

protected void registerRoute(String method,
                             String route,
                             org.glassfish.jersey.process.Inflector<javax.ws.rs.container.ContainerRequestContext,javax.ws.rs.core.Response> action)

Registers a route in HTTP endpoint.

Parameters:

method - HTTP method: "get", "head", "post", "put", "delete"

route - a command route. Base route will be added to this route

action - an action function that is called when operation is invoked.

registerResource

protected void registerResource(org.glassfish.jersey.server.model.Resource resource)

Registers resource in this objects Rest service.

Parameters:

resource - resource for registration