| /********************************************************************************************************************* |
| * Copyright (c) 2008, 2013 Empolis Information Management GmbH and brox IT Solutions GmbH. All rights reserved. This |
| * program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which |
| * accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html |
| *********************************************************************************************************************/ |
| package org.eclipse.smila.http.client; |
| |
| import java.io.IOException; |
| import java.io.InputStream; |
| |
| import org.apache.http.params.HttpParams; |
| import org.eclipse.smila.datamodel.Any; |
| import org.eclipse.smila.datamodel.AnyMap; |
| import org.eclipse.smila.datamodel.AnySeq; |
| import org.eclipse.smila.datamodel.Record; |
| |
| /** |
| * Interface for SMILA HTTP Rest Client helpers. See {@link org.eclipse.smila.http.client.impl.DefaultRestClient} for |
| * the standard implementation. |
| * <p> |
| * A <tt>RestClient</tt> always contains an <a href="http://hc.apache.org/httpcomponents-client-ga/index.html">Apache |
| * HttpClient</a> to handle the actual HTTP communication. For documentation on classes and interfaces coming directly |
| * from these libraries see the following JavaDocs: |
| * <ul> |
| * <li><a href="http://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/index.html">HttpCore</a> |
| * <li><a href="http://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/index.html">HttpClient</a> |
| * </ul> |
| * <p> |
| * Note that all resource strings given to the methods must be correctly URL-encoded. For incorrectly encoded resources |
| * a {@link IllegalArgumentException} is thrown. |
| * <p> |
| * 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 <tt>RestClient</tt> methods return an {@link AnyMap} object. If the actual result |
| * is <em>not</em> 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 {@link AnyMap} object with a single key <tt>result</tt>. The more generic |
| * <tt>invoke(...)</tt> methods return the original result as is. |
| * <p> |
| * Use {@link ResourceHelper} to get the correct resource locations. See {@link TaskManagerClientHelper} for resources |
| * needed by workers that want to communicate with the TaskManager using the HTTP interface. |
| * |
| * See <a href="http://wiki.eclipse.org/SMILA/Documentation/HowTo/How_to_access_the_REST_API_with_the_RestClient">How to |
| * access the REST API with the RestClient</a> for more information. |
| */ |
| public interface RestClient { |
| |
| /** |
| * Get the base URL of the SMILA server this clients talks to, for example <tt>http://localhost:8080</tt>. |
| * |
| * @return the base URL. |
| */ |
| String getHostAndPort(); |
| |
| /** |
| * Sets a parameter at the underlying Apache HttpClient client object. See <a href= |
| * "http://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/params/AllClientPNames.html" |
| * >org.apache.http.client.params.AllClientPNames</a> for links to names of possible parameters and the expected value |
| * types. |
| * |
| * @param name |
| * the HttpClient parameter name. |
| * @param value |
| * the HttpClient parameter value. |
| */ |
| void setClientParameter(final String name, final Object value); |
| |
| /** |
| * Sets authentication parameters at the underlying Apache HttpClient client object. |
| * |
| * @param user |
| * the user name used for authentication. |
| * @param password |
| * the password used for authentication. |
| */ |
| void setAuthParameters(final String user, final String password); |
| |
| /** shutdown this client. Currently running requests may be aborted. */ |
| void shutdown(); |
| |
| /** |
| * Do a GET request. Query parameters can be added to the <tt>resource</tt> string after a '?' character. |
| * |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila</tt>. Can contain additional URL parameters, e.g. |
| * <tt>...?returnDetails=true</tt>. |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| AnyMap get(final String resource) throws RestException, IOException; |
| |
| /** |
| * Do a GET request with parameters. |
| * |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila</tt>. |
| * @param parameters |
| * query parameters for the rest call. |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| AnyMap get(String resource, AnyMap parameters) throws RestException, IOException; |
| |
| /** |
| * 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 <tt>resource</tt> string after a '?' character. |
| * |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila</tt>. Can contain additional URL parameters, e.g. |
| * <tt>...?returnDetails=true</tt>. |
| * @return a {@link 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. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| BulkResponse getBulk(final String resource, final HttpParams methodParams) throws IOException, RestException; |
| |
| /** |
| * 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. |
| * |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila/jobmanager/jobs/$name</tt>. |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| AnyMap post(final String resource) throws RestException, 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. |
| * |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila/jobmanager/jobs/$name</tt>. |
| * @param parameters |
| * a parameter object, definition object, or record metadata. |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| AnyMap post(final String resource, final AnyMap parameters) throws RestException, 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 in string format. |
| * |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila/jobmanager/jobs/$name</tt>. |
| * @param parameters |
| * a parameter object, definition object, or record metadata as a string |
| * @param encoding |
| * the encosing of the parameters string |
| * @param contentType |
| * the contentType of the parameters |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| AnyMap post(final String resource, final String parameters, final String encoding, final String contentType) |
| throws RestException, IOException; |
| |
| /** |
| * Do a POST request with parameters and attachments. Usually, parameters are record metadata and attachments are the |
| * original binary documents. |
| * |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila/job/$name/record</tt>. |
| * @param parameters |
| * a parameter object, usually record metadata. |
| * @param attachments |
| * record attachments. |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| AnyMap post(final String resource, final AnyMap parameters, final Attachments attachments) throws RestException, |
| IOException; |
| |
| /** |
| * Do a POST request with a record (may contain attachments) as input. |
| * |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila/job/$name/record</tt>. |
| * @param record |
| * record metadata and attachments |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| AnyMap post(final String resource, final Record record) throws RestException, IOException; |
| |
| /** |
| * Do a POST request with a record as input. Return body and fill outParam with response header fields |
| * |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila/job/$name/record</tt>. |
| * @param record |
| * record metadata |
| * @param responseHeaderFields |
| * AnyMap which will be populated with the response header fields |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| AnyMap postWithResponseHeader(final String resource, final Record record, AnyMap responseHeaderFields) |
| throws RestException, IOException; |
| |
| /** |
| * Do a PUT request with parameters. For example, the parameters may describe an object to write the ObjectStore. |
| * |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila/store/$name/$id</tt>. |
| * @param parameters |
| * a parameter object, definition object, or record metadata. |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| AnyMap put(final String resource, final AnyMap parameters) throws RestException, 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. |
| * |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila/store/$name/$id</tt>. |
| * @param record |
| * record metadata. Attachments are ignored. |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| AnyMap put(final String resource, final Record record) throws RestException, IOException; |
| |
| /** |
| * Do a DELETE request. Query parameters can be added to the <tt>resource</tt> string after a '?' character. |
| * |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila/store/$name</tt>. Can contain additional URL parameters, e.g. |
| * <tt>...?returnDetails=true</tt>. |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| AnyMap delete(final String resource) throws RestException, IOException; |
| |
| /** |
| * Do a DELETE request with parameters. For example the parameters might describe a record to delete. |
| * |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila/job/$jobname/record</tt>. |
| * @param parameters |
| * a parameter object or record metadata to be attached |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| AnyMap delete(final String resource, final AnyMap parameters) throws RestException, IOException; |
| |
| /** |
| * Generic method to invoke an API resource and set special HttpClient parameters for this call only. See <a href= |
| * "http://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/params/AllClientPNames.html" |
| * >org.apache.http.client.params.AllClientPNames</a> for links to names of possible parameters and the expected value |
| * types. |
| * |
| * @param method |
| * the HTTP method to use |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila/job/$name/record</tt>. Can contain URL parameters for GET and |
| * DELETE calls. |
| * @param parameters |
| * a parameter object, usually record metadata, may be null. |
| * @param attachments |
| * record attachments, may be null. |
| * @param httpParams |
| * HttpClient parameters for this call, may be null. |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| Any invoke(final HttpMethod method, final String resource, final AnyMap parameters, |
| final Attachments attachments, final HttpParams httpParams) throws RestException, IOException; |
| |
| /** |
| * Generic method to invoke an API resource and set special HttpClient parameters for this call only. See <a href= |
| * "http://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/params/AllClientPNames.html" |
| * >org.apache.http.client.params.AllClientPNames</a> for links to names of possible parameters and the expected value |
| * types. |
| * |
| * @param method |
| * the HTTP method to use |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila/job/$name/record</tt>. Can contain URL parameters for GET and |
| * DELETE calls. |
| * @param parameters |
| * a parameter object, usually record metadata, may be null. |
| * @param attachments |
| * record attachments, may be null. |
| * @param httpParams |
| * HttpClient parameters for this call, may be null. |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| Any invoke(final HttpMethod method, final String resource, final AnySeq parameters, |
| final Attachments attachments, final HttpParams httpParams) throws RestException, IOException; |
| |
| /** |
| * Invoke an API resource using content from a input stream containing JSON and set special HttpClient parameters for |
| * this call only. See <a href= |
| * "http://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/params/AllClientPNames.html" |
| * >org.apache.http.client.params.AllClientPNames</a> for links to names of possible parameters and the expected value |
| * types. |
| * |
| * @param method |
| * the HTTP method to use |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila/job/$name/record</tt>. Can contain URL parameters for GET and |
| * DELETE calls. |
| * @param inputStream |
| * an input stream with valid JSON data. |
| * @param httpParams |
| * HttpClient parameters for this call, may be null. |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| Any invoke(final HttpMethod method, final String resource, final InputStream inputStream, |
| final HttpParams httpParams) throws RestException, 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 <a href= |
| * "http://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/params/AllClientPNames.html" |
| * >org.apache.http.client.params.AllClientPNames</a> for links to names of possible parameters and the expected value |
| * types. |
| * |
| * @param method |
| * the HTTP method to use |
| * @param resource |
| * the API resource to call, e.g. <tt>/smila/job/$name/record</tt>. Can contain URL parameters for GET and |
| * DELETE calls. |
| * @param inputStream |
| * an input stream with data of the specified content type |
| * @param contentType |
| * content type of data. |
| * @param httpParams |
| * HttpClient parameters for this call, may be null. |
| * @return the result object, if a JSON result was returned, else <tt>null</tt>. |
| * @throws RestException |
| * on errors reported by the SMILA server. |
| * @throws IOException |
| * on all kinds of communication problems or data conversion errors. |
| */ |
| Any invoke(final HttpMethod method, final String resource, final InputStream inputStream, String contentType, |
| final HttpParams httpParams) throws RestException, IOException; |
| |
| } |
