uk.ac.gate.cloud.client

Class RestClient

java.lang.Object

uk.ac.gate.cloud.client.RestClient

public class RestClient
extends Object

Client responsible for communication with the GATE Cloud API. Handles authentication, and serialization and deserialization of JSON request and response bodies.

Author:

Ian Roberts

Field Summary

Fields

Modifier and Type	Field and Description
static URL	DEFAULT_BASE_URL The standard base URI for the GATE Cloud API.

Constructor Summary

Constructors

Constructor and Description
RestClient(String apiKeyId, String apiPassword) Create a client that uses the default base URL.
RestClient(URL url, String apiKeyId, String apiPassword) Create a client using a specified base URL (for advanced use only - the default URL will work for all normal cases).

Method Summary

Modifier and Type	Method and Description
void	delete(String target) Perform an HTTP DELETE request for the given resource.
<T> T	get(String target, com.fasterxml.jackson.core.type.TypeReference<T> responseType) Perform an HTTP GET request, parsing the JSON response to create a new object.
URL	getBaseUrl()
void	getForUpdate(String target, Object responseObject) Perform an HTTP GET request, parsing the JSON response to update the state of an existing object.
Map<String,List<String>>	getLastHeaders() Returns the response headers that were sent with the most recent successful HTTP response received by this client in this thread.
URL	getRedirect(URL source) Perform an HTTP GET request on a URL whose response is expected to be a 3xx redirection, and return the target redirection URL.
<T> T	post(String target, com.fasterxml.jackson.core.type.TypeReference<T> responseType, Object requestBody) Perform an HTTP POST request, parsing the JSON response to create a new object.
void	postForUpdate(String target, Object responseObject, Object requestBody) Perform an HTTP POST request, parsing the JSON response to update the state of an existing object.
<T> T	request(String target, String method, com.fasterxml.jackson.core.type.TypeReference<T> responseType, Object requestBody, String... extraHeaders) Make an API request and parse the JSON response into a new object.
InputStream	requestForStream(String target, String method, Object requestBody, int gzipThreshold, String... extraHeaders) Make an API request and return the raw data from the response as an InputStream.
void	requestForUpdate(String target, String method, Object responseObject, Object requestBody, String... extraHeaders) Make an API request and parse the JSON response, using the response to update the state of an existing object.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BASE_URL

public static final URL DEFAULT_BASE_URL

The standard base URI for the GATE Cloud API.

Constructor Detail

RestClient

public RestClient(String apiKeyId,
                  String apiPassword)

Create a client that uses the default base URL.

Parameters:

apiKeyId - API key identifier for authentication. If null, no authentication will be used, which means the client can only be used to call public pipelines via the online API.

apiPassword - API key password

RestClient

public RestClient(URL url,
                  String apiKeyId,
                  String apiPassword)

Create a client using a specified base URL (for advanced use only - the default URL will work for all normal cases).

Parameters:

url - API base URL

apiKeyId - API key identifier for authentication

apiPassword - API key password

Method Detail

getBaseUrl

public URL getBaseUrl()

request

public <T> T request(String target,
                     String method,
                     com.fasterxml.jackson.core.type.TypeReference<T> responseType,
                     Object requestBody,
                     String... extraHeaders)
              throws RestClientException

Make an API request and parse the JSON response into a new object.

Parameters:

target - the URL to request (relative URLs will resolve against the base URL).

method - the request method (GET, POST, DELETE, etc.)

responseType - the Java type corresponding to a successful response message for this URL

requestBody - the value to send as the request body. If null, no request body is sent. If an InputStream or a StreamWriteable then its content will be sent as-is and an appropriate Content-Type should be given in the extraHeaders (note that the input stream will not be closed by this method, that is the responsibility of the caller). Otherwise the provided object will be serialized to JSON and sent with the default application/json MIME type.

extraHeaders - any additional HTTP headers, specified as an alternating sequence of header names and values

Returns:

for a successful response, the deserialized response body, or null for a 201 response

Throws:

RestClientException - if an exception occurs during processing, or the server returns a 4xx or 5xx error response (in which case the response JSON message will be available as a JsonNode in the exception).

requestForStream

public InputStream requestForStream(String target,
                                    String method,
                                    Object requestBody,
                                    int gzipThreshold,
                                    String... extraHeaders)
                             throws RestClientException

Make an API request and return the raw data from the response as an InputStream.

Parameters:

target - the URL to request (relative URLs will resolve against the base URL).

method - the request method (GET, POST, DELETE, etc.)

requestBody - the value to send as the request body. If null, no request body is sent. If an InputStream or a StreamWriteable then its content will be sent as-is and an appropriate Content-Type should be given in the extraHeaders (note that the input stream will not be closed by this method, that is the responsibility of the caller). Otherwise the provided object will be serialized to JSON and sent with the default application/json MIME type.

gzipThreshold - size threshold above which the request body should be GZIP compressed. If negative, the request will never be compressed.

extraHeaders - any additional HTTP headers, specified as an alternating sequence of header names and values

Returns:

for a successful response, the response stream, or null for a 201 response

Throws:

RestClientException - if an exception occurs during processing, or the server returns a 4xx or 5xx error response (in which case the response JSON message will be available as a JsonNode in the exception).

requestForUpdate

public void requestForUpdate(String target,
                             String method,
                             Object responseObject,
                             Object requestBody,
                             String... extraHeaders)
                      throws RestClientException

Make an API request and parse the JSON response, using the response to update the state of an existing object.

Parameters:

target - the URL to request (relative URLs will resolve against the base URL).

method - the request method (GET, POST, DELETE, etc.)

responseObject - the Java object to update from a successful response message for this URL

requestBody - the value to send as the request body. If null, no request body is sent. If an InputStream or a StreamWriteable then its content will be sent as-is and an appropriate Content-Type should be given in the extraHeaders (note that the input stream will not be closed by this method, that is the responsibility of the caller). Otherwise the provided object will be serialized to JSON and sent with the default application/json MIME type.

extraHeaders - any additional HTTP headers, specified as an alternating sequence of header names and values

Throws:

RestClientException - if an exception occurs during processing, or the server returns a 4xx or 5xx error response (in which case the response JSON message will be available as a JsonNode in the exception).

get

public <T> T get(String target,
                 com.fasterxml.jackson.core.type.TypeReference<T> responseType)
          throws RestClientException

Perform an HTTP GET request, parsing the JSON response to create a new object.

Parameters:

target - the URL to request (relative URLs will resolve against the base URL).

responseType - the Java type corresponding to a successful response message for this URL

Returns:

for a successful response, the deserialized response body, or null for a 201 response

Throws:

RestClientException - if an exception occurs during processing, or the server returns a 4xx or 5xx error response (in which case the response JSON message will be available as a JsonNode in the exception).

getForUpdate

public void getForUpdate(String target,
                         Object responseObject)
                  throws RestClientException

Perform an HTTP GET request, parsing the JSON response to update the state of an existing object.

Parameters:

target - the URL to request (relative URLs will resolve against the base URL).

responseObject - the Java object to update from a successful response message for this URL

Throws:

RestClientException - if an exception occurs during processing, or the server returns a 4xx or 5xx error response (in which case the response JSON message will be available as a JsonNode in the exception).

post

public <T> T post(String target,
                  com.fasterxml.jackson.core.type.TypeReference<T> responseType,
                  Object requestBody)
           throws RestClientException

Perform an HTTP POST request, parsing the JSON response to create a new object.

Parameters:

target - the URL to request (relative URLs will resolve against the base URL).

responseType - the Java type corresponding to a successful response message for this URL

requestBody - the value to send as the request body. If null, no request body is sent. If an InputStream or a StreamWriteable then its content will be sent as-is and an appropriate Content-Type should be given in the extraHeaders (note that the input stream will not be closed by this method, that is the responsibility of the caller). Otherwise the provided object will be serialized to JSON and sent with the default application/json MIME type.

Returns:

for a successful response, the deserialized response body, or null for a 201 response

Throws:

RestClientException - if an exception occurs during processing, or the server returns a 4xx or 5xx error response (in which case the response JSON message will be available as a JsonNode in the exception).

postForUpdate

public void postForUpdate(String target,
                          Object responseObject,
                          Object requestBody)
                   throws RestClientException

Perform an HTTP POST request, parsing the JSON response to update the state of an existing object.

Parameters:

target - the URL to request (relative URLs will resolve against the base URL).

responseObject - the Java object to update from a successful response message for this URL

requestBody - the value to send as the request body. If null, no request body is sent. If an InputStream or a StreamWriteable then its content will be sent as-is and an appropriate Content-Type should be given in the extraHeaders (note that the input stream will not be closed by this method, that is the responsibility of the caller). Otherwise the provided object will be serialized to JSON and sent with the default application/json MIME type.

Throws:

RestClientException - if an exception occurs during processing, or the server returns a 4xx or 5xx error response (in which case the response JSON message will be available as a JsonNode in the exception).

delete

public void delete(String target)
            throws RestClientException

Perform an HTTP DELETE request for the given resource.

Parameters:

target - the URL to request (relative URLs will resolve against the base URL).

Throws:

RestClientException - if an exception occurs during processing, or the server returns a 4xx or 5xx error response (in which case the response JSON message will be available as a JsonNode in the exception).

getRedirect

public URL getRedirect(URL source)
                throws RestClientException

Perform an HTTP GET request on a URL whose response is expected to be a 3xx redirection, and return the target redirection URL.

Parameters:

source - the URL to request (relative URLs will resolve against the base URL).

Returns:

the URL returned by the "Location" header of the redirection response.

Throws:

RestClientException - if an exception occurs during processing, or the server returns a 4xx or 5xx error response (in which case the response JSON message will be available as a JsonNode in the exception), or if the response was not a 3xx redirection.

getLastHeaders

public Map<String,List<String>> getLastHeaders()

Returns the response headers that were sent with the most recent successful HTTP response received by this client in this thread.

Returns:

the headers, as a map where the keys are HTTP header names and the values are the list (usually singleton) of values for that header.