org.eclipse.smila.http.client
Interface RestClient

All Known Implementing Classes:

DefaultRestClient, FailoverRestClient, RestClientBase

public interface RestClient

Interface for SMILA HTTP Rest Client helpers. See DefaultRestClient for the standard implementation.

A RestClient always contains an Apache HttpClient to handle the actual HTTP communication. For documentation on classes and interfaces coming directly from these libraries see the following JavaDocs:

• HttpCore
• HttpClient

Note that all resource strings given to the methods must be correctly URL-encoded. For incorrectly encoded resources a IllegalArgumentException is thrown.

Currently, all SMILA APIs return a JSON object as their result (if any), i.e. the result string starts with "{" and ends with "}". Consequently, most RestClient methods return an AnyMap object. If the actual result is not a JSON object but a JSON array ("[...]") or a simple value, when one of these methods is used, the result will be wrapped in an AnyMap object with a single key result. The more generic invoke(...) methods return the original result as is.

Use ResourceHelper to get the correct resource locations. See TaskManagerClientHelper for resources needed by workers that want to communicate with the TaskManager using the HTTP interface. See How to access the REST API with the RestClient for more information.

Method Summary

AnyMap	delete(java.lang.String resource) Do a DELETE request.
AnyMap	get(java.lang.String resource) Do a GET request.
BulkResponse	getBulk(java.lang.String resource, HttpParams methodParams) Do a GET request on a resource that can produce a bulk response (i.e., single line JSON objects, separated by newlines).
java.lang.String	getHostAndPort() Get the base URL of the SMILA server this clients talks to, for example http://localhost:8080.
Any	invoke(HttpMethod method, java.lang.String resource, AnyMap parameters, Attachments attachments, HttpParams httpParams) Generic method to invoke an API resource and set special HttpClient parameters for this call only.
Any	invoke(HttpMethod method, java.lang.String resource, AnySeq parameters, Attachments attachments, HttpParams httpParams) Generic method to invoke an API resource and set special HttpClient parameters for this call only.
Any	invoke(HttpMethod method, java.lang.String resource, java.io.InputStream inputStream, HttpParams httpParams) Invoke an API resource using content from a input stream containing JSON and set special HttpClient parameters for this call only.
Any	invoke(HttpMethod method, java.lang.String resource, java.io.InputStream inputStream, java.lang.String contentType, HttpParams httpParams) Invoke an API resource using content from a input stream containing the specified content type and set special HttpClient parameters for this call only.
AnyMap	post(java.lang.String resource) Do a POST request without parameters.
AnyMap	post(java.lang.String resource, AnyMap parameters) Do a POST request with parameters.
AnyMap	post(java.lang.String resource, AnyMap parameters, Attachments attachments) Do a POST request with parameters and attachments.
AnyMap	post(java.lang.String resource, Record record) Do a POST request with a record (may contain attachments) as input.
AnyMap	put(java.lang.String resource, AnyMap parameters) Do a PUT request with parameters.
AnyMap	put(java.lang.String resource, Record record) Do a PUT request with a record as input, however, only the record metadata is used in the request, as PUT requests cannot contain attachments.
void	setClientParameter(java.lang.String name, java.lang.Object value) Sets a parameter at the underlying Apache HttpClient client object.
void	shutdown() shutdown this client.

Method Detail

getHostAndPort

java.lang.String getHostAndPort()

Get the base URL of the SMILA server this clients talks to, for example http://localhost:8080.

Returns:

the base URL.

setClientParameter

void setClientParameter(java.lang.String name,
                        java.lang.Object value)

Sets a parameter at the underlying Apache HttpClient client object. See org.apache.http.client.params.AllClientPNames for links to names of possible parameters and the expected value types.

Parameters:

name - the HttpClient parameter name.

value - the HttpClient parameter value.

shutdown

void shutdown()

shutdown this client. Currently running requests may be aborted.

get

AnyMap get(java.lang.String resource)
           throws RestException,
                  java.io.IOException

Do a GET request. Query parameters can be added to the resource string after a '?' character.

Parameters:

resource - the API resource to call, e.g. /smila. Can contain additional URL parameters, e.g. ...?returnDetails=true.

Returns:

the result object, if a JSON result was returned, else null.

Throws:

RestException - on errors reported by the SMILA server.

java.io.IOException - on all kinds of communication problems or data conversion errors.

getBulk

BulkResponse getBulk(java.lang.String resource,
                     HttpParams methodParams)
                     throws java.io.IOException,
                            RestException

Do a GET request on a resource that can produce a bulk response (i.e., single line JSON objects, separated by newlines). Query parameters can be added to the resource string after a '?' character.

Parameters:

resource - the API resource to call, e.g. /smila. Can contain additional URL parameters, e.g. ...?returnDetails=true.

Returns:

a BulkResponse objects that can be used to iterate over the objects contained in the response. If no result content was returned, an empty iterator will be returned.

Throws:

RestException - on errors reported by the SMILA server.

java.io.IOException - on all kinds of communication problems or data conversion errors.

post

AnyMap post(java.lang.String resource)
            throws RestException,
                   java.io.IOException

Do a POST request without parameters. To add parameters to POST requests, you should not use URL parameters ("...?parameter=value"), but create a parameter object and use the other methods.

Parameters:

resource - the API resource to call, e.g. /smila/jobmanager/jobs/$name.

Returns:

the result object, if a JSON result was returned, else null.

Throws:

RestException - on errors reported by the SMILA server.

java.io.IOException - on all kinds of communication problems or data conversion errors.

post

AnyMap post(java.lang.String resource,
            AnyMap parameters)
            throws RestException,
                   java.io.IOException

Do a POST request with parameters. The parameters may be definitions to be added to the server (e.g. workflow, job) or record metadata to be submitted to a workflow.

Parameters:

resource - the API resource to call, e.g. /smila/jobmanager/jobs/$name.

parameters - a parameter object, definition object, or record metadata.

Returns:

the result object, if a JSON result was returned, else null.

Throws:

RestException - on errors reported by the SMILA server.

java.io.IOException - on all kinds of communication problems or data conversion errors.

post

AnyMap post(java.lang.String resource,
            AnyMap parameters,
            Attachments attachments)
            throws RestException,
                   java.io.IOException

Do a POST request with parameters and attachments. Usually, parameters are record metadata and attachments are the original binary documents.

Parameters:

resource - the API resource to call, e.g. /smila/job/$name/record.

parameters - a parameter object, usually record metadata.

attachments - record attachments.

Returns:

the result object, if a JSON result was returned, else null.

Throws:

RestException - on errors reported by the SMILA server.

java.io.IOException - on all kinds of communication problems or data conversion errors.

post

AnyMap post(java.lang.String resource,
            Record record)
            throws RestException,
                   java.io.IOException

Do a POST request with a record (may contain attachments) as input.

Parameters:

resource - the API resource to call, e.g. /smila/job/$name/record.

record - record metadata and attachments

Returns:

the result object, if a JSON result was returned, else null.

Throws:

RestException - on errors reported by the SMILA server.

java.io.IOException - on all kinds of communication problems or data conversion errors.

put

AnyMap put(java.lang.String resource,
           AnyMap parameters)
           throws RestException,
                  java.io.IOException

Do a PUT request with parameters. For example, the parameters may describe an object to write the ObjectStore.

Parameters:

resource - the API resource to call, e.g. /smila/store/$name/$id.

parameters - a parameter object, definition object, or record metadata.

Returns:

the result object, if a JSON result was returned, else null.

Throws:

RestException - on errors reported by the SMILA server.

java.io.IOException - on all kinds of communication problems or data conversion errors.

put

AnyMap put(java.lang.String resource,
           Record record)
           throws RestException,
                  java.io.IOException

Do a PUT request with a record as input, however, only the record metadata is used in the request, as PUT requests cannot contain attachments.

Parameters:

resource - the API resource to call, e.g. /smila/store/$name/$id.

record - record metadata. Attachments are ignored.

Returns:

the result object, if a JSON result was returned, else null.

Throws:

RestException - on errors reported by the SMILA server.

java.io.IOException - on all kinds of communication problems or data conversion errors.

delete

AnyMap delete(java.lang.String resource)
              throws RestException,
                     java.io.IOException

Do a DELETE request. Query parameters can be added to the resource string after a '?' character.

Parameters:

resource - the API resource to call, e.g. /smile/store/$name. Can contain additional URL parameters, e.g. ...?returnDetails=true.

Returns:

the result object, if a JSON result was returned, else null.

Throws:

RestException - on errors reported by the SMILA server.

java.io.IOException - on all kinds of communication problems or data conversion errors.

invoke

Any invoke(HttpMethod method,
           java.lang.String resource,
           AnyMap parameters,
           Attachments attachments,
           HttpParams httpParams)
           throws RestException,
                  java.io.IOException

Generic method to invoke an API resource and set special HttpClient parameters for this call only. See org.apache.http.client.params.AllClientPNames for links to names of possible parameters and the expected value types.

Parameters:

method - the HTTP method to use

resource - the API resource to call, e.g. /smila/job/$name/record. Can contain URL parameters for GET and DELETE calls.

parameters - a parameter object, usually record metadata, may be null.

attachments - record attachments, may be null.

httpParams - HttpClient parameters for this call, may be null.

Returns:

the result object, if a JSON result was returned, else null.

Throws:

RestException - on errors reported by the SMILA server.

java.io.IOException - on all kinds of communication problems or data conversion errors.

invoke

Any invoke(HttpMethod method,
           java.lang.String resource,
           AnySeq parameters,
           Attachments attachments,
           HttpParams httpParams)
           throws RestException,
                  java.io.IOException

Generic method to invoke an API resource and set special HttpClient parameters for this call only. See org.apache.http.client.params.AllClientPNames for links to names of possible parameters and the expected value types.

Parameters:

method - the HTTP method to use

resource - the API resource to call, e.g. /smila/job/$name/record. Can contain URL parameters for GET and DELETE calls.

parameters - a parameter object, usually record metadata, may be null.

attachments - record attachments, may be null.

httpParams - HttpClient parameters for this call, may be null.

Returns:

the result object, if a JSON result was returned, else null.

Throws:

RestException - on errors reported by the SMILA server.

java.io.IOException - on all kinds of communication problems or data conversion errors.

invoke

Any invoke(HttpMethod method,
           java.lang.String resource,
           java.io.InputStream inputStream,
           HttpParams httpParams)
           throws RestException,
                  java.io.IOException

Invoke an API resource using content from a input stream containing JSON and set special HttpClient parameters for this call only. See org.apache.http.client.params.AllClientPNames for links to names of possible parameters and the expected value types.

Parameters:

method - the HTTP method to use

resource - the API resource to call, e.g. /smila/job/$name/record. Can contain URL parameters for GET and DELETE calls.

inputStream - an input stream with valid JSON data.

httpParams - HttpClient parameters for this call, may be null.

Returns:

the result object, if a JSON result was returned, else null.

Throws:

RestException - on errors reported by the SMILA server.

java.io.IOException - on all kinds of communication problems or data conversion errors.

invoke

Any invoke(HttpMethod method,
           java.lang.String resource,
           java.io.InputStream inputStream,
           java.lang.String contentType,
           HttpParams httpParams)
           throws RestException,
                  java.io.IOException

Invoke an API resource using content from a input stream containing the specified content type and set special HttpClient parameters for this call only. See org.apache.http.client.params.AllClientPNames for links to names of possible parameters and the expected value types.

Parameters:

method - the HTTP method to use

resource - the API resource to call, e.g. /smila/job/$name/record. Can contain URL parameters for GET and DELETE calls.

inputStream - an input stream with data of the specified content type

contentType - content type of data.

httpParams - HttpClient parameters for this call, may be null.

Returns:

the result object, if a JSON result was returned, else null.

Throws:

RestException - on errors reported by the SMILA server.

java.io.IOException - on all kinds of communication problems or data conversion errors.