org.pipservices.rpc.clients

Class RestClient

java.lang.Object

org.pipservices.rpc.clients.RestClient

All Implemented Interfaces:

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

Direct Known Subclasses:

CommandableHttpClient

public class RestClient
extends Object
implements org.pipservices.commons.run.IOpenable, org.pipservices.commons.config.IConfigurable, org.pipservices.commons.refer.IReferenceable

Abstract client that calls remove endpoints using HTTP/REST protocol.

### Configuration parameters ###

• base_route: base route for remote URI
• 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
• options:
  • retries: number of retries (default: 3)
  • connect_timeout: connection timeout in milliseconds (default: 10 sec)
  • timeout: invocation timeout in milliseconds (default: 10 sec)

### 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

### Example ###

 
 class MyRestClient extends RestClient implements IMyClient {
    ...
 
    public MyData getData(String correlationId, String id) {
        Timing timing = this.instrument(correlationId, 'myclient.get_data');
        MyData result = this.execute(MyData.class, correlationId, HttpMethod.POST, "/get_data", new MyData(id));
        timing.endTiming();
        return result;        
    }
    ...
 }
 
 MyRestClient client = new MyRestClient();
 client.configure(ConfigParams.fromTuples(
     "connection.protocol", "http",
     "connection.host", "localhost",
     "connection.port", 8080
 ));
 
 MyData data = client.getData("123", "1");
 ...
 
 

Field Summary

Fields

Modifier and Type	Field and Description
protected String	_baseRoute The base route.
protected javax.ws.rs.client.Client	_client The HTTP client.
protected HttpConnectionResolver	_connectionResolver The connection resolver.
protected org.pipservices.components.count.CompositeCounters	_counters The performance counters.
protected org.pipservices.components.log.CompositeLogger	_logger The logger.
protected org.pipservices.commons.config.ConfigParams	_options The configuration options.
protected int	_retries The number of retries.
protected String	_url The remote service uri which is calculated on open.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RestClient() Creates a new instance of the client.
protected	RestClient(String baseRoute) Creates a new instance of the client.

Method Summary

Modifier and Type	Method and Description
protected String	addCorrelationId(String route, String correlationId) Adds a correlation id (correlation_id) to invocation parameter map.
protected String	addFilterParams(String route, org.pipservices.commons.data.FilterParams filter) Adds filter parameters (with the same name as they defined) to invocation parameter map.
protected String	addPagingParams(String route, org.pipservices.commons.data.PagingParams paging) Adds paging parameters (skip, take, total) to invocation parameter map.
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	execute(Class<T> type, String correlationId, String method, String route, Object requestEntity) Executes a remote method via HTTP/REST protocol.
protected <T> T	execute(javax.ws.rs.core.GenericType<T> type, String correlationId, String method, String route, Object requestEntity) Executes a remote method via HTTP/REST protocol.
protected javax.ws.rs.core.Response	executeRequest(String correlationId, String method, URI uri, String mediaType, javax.ws.rs.client.Entity<?> body)
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.
void	setReferences(org.pipservices.commons.refer.IReferences references) Sets references to dependent components.

Methods inherited from class java.lang.Object

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

Field Detail

_connectionResolver

protected HttpConnectionResolver _connectionResolver

The connection resolver.

_logger

protected org.pipservices.components.log.CompositeLogger _logger

The logger.

_counters

protected org.pipservices.components.count.CompositeCounters _counters

The performance counters.

_options

protected org.pipservices.commons.config.ConfigParams _options

The configuration options.

_baseRoute

protected String _baseRoute

The base route.

_retries

protected int _retries

The number of retries.

_url

protected String _url

The remote service uri which is calculated on open.

_client

protected javax.ws.rs.client.Client _client

The HTTP client.

Constructor Detail

RestClient

protected RestClient()

Creates a new instance of the client.

RestClient

protected RestClient(String baseRoute)

Creates a new instance of the client.

Parameters:

baseRoute - a base route for remote service.

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

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.

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.

addCorrelationId

protected String addCorrelationId(String route,
                                  String correlationId)

Adds a correlation id (correlation_id) to invocation parameter map.

Parameters:

route - invocation parameters.

correlationId - (optional) a correlation id to be added.

Returns:

invocation parameters with added correlation id.

addFilterParams

protected String addFilterParams(String route,
                                 org.pipservices.commons.data.FilterParams filter)

Adds filter parameters (with the same name as they defined) to invocation parameter map.

Parameters:

route - invocation parameters.

filter - (optional) filter parameters

Returns:

invocation parameters with added filter parameters.

addPagingParams

protected String addPagingParams(String route,
                                 org.pipservices.commons.data.PagingParams paging)

Adds paging parameters (skip, take, total) to invocation parameter map.

Parameters:

route - invocation parameters.

paging - (optional) paging parameters

Returns:

invocation parameters with added paging parameters.

executeRequest

protected javax.ws.rs.core.Response executeRequest(String correlationId,
                                                   String method,
                                                   URI uri,
                                                   String mediaType,
                                                   javax.ws.rs.client.Entity<?> body)
                                            throws org.pipservices.commons.errors.ApplicationException

Throws:

org.pipservices.commons.errors.ApplicationException

execute

protected <T> T execute(Class<T> type,
                        String correlationId,
                        String method,
                        String route,
                        Object requestEntity)
                 throws org.pipservices.commons.errors.ApplicationException

Executes a remote method via HTTP/REST protocol.

Parameters:

type - the class type of data.

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

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

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

requestEntity - request body object.

Returns:

result object.

Throws:

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

execute

protected <T> T execute(javax.ws.rs.core.GenericType<T> type,
                        String correlationId,
                        String method,
                        String route,
                        Object requestEntity)
                 throws org.pipservices.commons.errors.ApplicationException

Executes a remote method via HTTP/REST protocol.

Parameters:

type - the generic class type of data.

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

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

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

requestEntity - request body object.

Returns:

result object.

Throws:

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