manifold.json.rt.api

Class Requester<T>

java.lang.Object

manifold.json.rt.api.Requester<T>

Type Parameters:

T - The type corresponding with the HTTP requests made from this class. For instance, this type is returned from GET calls and is also the type of the payload sent for POST, PUT, and PATCH calls. Since DELETE calls do not necessarily send or receive this type, it is not part of the signatures of those methods.

public class Requester<T>
extends java.lang.Object

This class defines methods to simplify making HTTP requests involved with basic REST API calls supporting GET, POST, PUT, PATCH, and DELETE and handles responses in JSON & JSON Schema, YAML, XML, CSV, or plain text. An instance of this class may be used for multiple get/post/etc. requests.

Normally you use this class via the JSON API request(url) method to manage simple HTTP request API calls:

 User user = User.request("http://example.com/users").getOne("/$id");

 // or

 Requester<User> req = User.request("http://example.com/users")
   .withBearerAuthorization("xxx...x"); // eg., using OAuth token
 User user = req.getOne("/$id");
 user.setName("Scott");
 req.putOne("/$id", user);
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Requester.Format

Constructor Summary

Constructors

Constructor and Description
Requester(Endpoint endpoint)
Requester(Endpoint endpoint, java.util.function.Function<java.lang.Object,java.lang.Object> resultCoercer)
Requester(java.lang.String urlBase) Get an instance of Requester from a JSON API type eg., User.request().
Requester(java.lang.String urlBase, java.util.function.Function<java.lang.Object,java.lang.Object> resultCoercer)

Method Summary

Modifier and Type	Method and Description
<R> R	delete(java.lang.Object arguments) Same as calling: delete(String, Object, Format) with delete("", arguments, _format)
<R> R	delete(java.lang.String urlSuffix) Same as calling: delete(String, Object, Format) with delete(urlSuffix, null, _format)
<R> R	delete(java.lang.String urlSuffix, java.lang.Object arguments) Same as calling: delete(String, Object, Format) with delete(urlSuffix, arguments, _format)
<R> R	delete(java.lang.String urlSuffix, java.lang.Object arguments, Requester.Format format) Make an HTTP DELETE request to urlBase + urlSuffix.
Endpoint	getEndpoint()
Requester.Format	getFormat()
java.util.Map<java.lang.String,java.lang.String>	getHeaders()
IJsonList<T>	getMany() Uses HTTP GET for the complete list of T JSON API objects as a IJsonList<T>.
IJsonList<T>	getMany(java.lang.Object arguments) Same as calling: getMany(String, Object, Format) with getMany("", arguments, _format)
IJsonList<T>	getMany(java.lang.String urlSuffix) Same as calling: getMany(String, Object, Format) with getMany(urlSuffix, null, _format)
IJsonList<T>	getMany(java.lang.String urlSuffix, java.lang.Object arguments) Same as calling: getMany(String, Object, Format) with getMany(urlSuffix, arguments, _format)
IJsonList<T>	getMany(java.lang.String urlSuffix, java.lang.Object arguments, Requester.Format format) Make an HTTP GET request to urlBase + urlSuffix.
T	getOne() Use HTTP GET for a single T JSON API object specified in the urlSuffix, such as "/108".
T	getOne(java.lang.Object arguments) Same as calling: getOne(String, Object, Format) with getOne("", arguments, _format)
T	getOne(java.lang.String urlSuffix) Use HTTP GET for a single T JSON API object specified in the urlSuffix, such as "/108".
T	getOne(java.lang.String urlSuffix, java.lang.Object arguments) Same as calling: getOne(String, Object, Format) with getOne(urlSuffix, arguments, _format)
T	getOne(java.lang.String urlSuffix, java.lang.Object arguments, Requester.Format format) Make an HTTP GET request to urlBase + urlSuffix.
java.util.Map<java.lang.String,java.lang.String>	getParameters()
java.util.function.Function<T,java.lang.Object>	getRawResponseHandler()
int	getTimeout()
<R> R	patchMany(java.util.List<T> payload) Same as calling: patchMany(String, List, Format) with patchMany("", payload, _format)
<R> R	patchMany(java.lang.String urlSuffix, java.util.List<T> payload) Same as calling: patchMany(String, List, Format) with patchMany(urlSuffix, payload, _format)
<R> R	patchMany(java.lang.String urlSuffix, java.util.List<T> payload, Requester.Format format) Make an HTTP PATCH request to urlBase + urlSuffix.
<R> R	patchOne(java.lang.String urlSuffix, T payload) Same as calling: patchOne(String, Object, Format) with patchOne(urlSuffix, payload, _format)
<R> R	patchOne(java.lang.String urlSuffix, T payload, Requester.Format format) Make an HTTP PATCH request to urlBase + urlSuffix.
<R> R	patchOne(T payload) Same as calling: patchOne(String, Object, Format) with patchOne("", payload, _format)
<R> R	postMany(java.util.List<T> payload) Same as calling: postMany(String, List, Format) with postMany("", payload, _format)
<R> R	postMany(java.lang.String urlSuffix, java.util.List<T> payload) Same as calling: postMany(String, List, Format) with postMany(urlSuffix, payload, _format)
<R> R	postMany(java.lang.String urlSuffix, java.util.List<T> payload, Requester.Format format) Make an HTTP POST request to urlBase + urlSuffix.
<R> R	postOne(java.lang.String urlSuffix, T payload) Same as calling: postOne(String, Object, Format) with postOne(urlSuffix, payload, _format)
<R> R	postOne(java.lang.String urlSuffix, T payload, Requester.Format format) Make an HTTP POST request to urlBase + urlSuffix.
<R> R	postOne(T payload) Same as calling: postOne(String, Object, Format) with postOne("", payload, _format)
<R> R	putMany(java.util.List<T> payload) Same as calling: putMany(String, List, Format) with putMany("", payload, _format)
<R> R	putMany(java.lang.String urlSuffix, java.util.List<T> payload) Same as calling: putMany(String, List, Format) with putMany(urlSuffix, payload, _format)
<R> R	putMany(java.lang.String urlSuffix, java.util.List<T> payload, Requester.Format format) Make an HTTP PUT request to urlBase + urlSuffix.
<R> R	putOne(java.lang.String urlSuffix, T payload) Same as calling: putOne(String, Object, Format) with putOne(urlSuffix, payload, _format)
<R> R	putOne(java.lang.String urlSuffix, T payload, Requester.Format format) Make an HTTP PUT request to urlBase + urlSuffix.
<R> R	putOne(T payload) Same as calling: putOne(String, Object, Format) with putOne("", payload, _format)
Requester<T>	withAuthorization(java.lang.String tokenType, java.lang.String accessToken)
Requester<T>	withBasicAuthorization(java.lang.String username, java.lang.String password) Set the Basic Authorization header using the provided username and password
Requester<T>	withBearerAuthorization(java.lang.String accessToken) Set the Bearer Authorization header using the provided accessToken.
Requester<T>	withCoercer(java.util.function.Function<java.lang.Object,java.lang.Object> resultCoercer)
Requester<T>	withHeader(java.lang.String name, java.lang.String value) Set an HTTP request header name : value pair See	Requester<T>	withParam(java.lang.String name, java.lang.String value) Add a name=value parameter to the request URL.
Requester<T>	withRawResponseHandler(java.util.function.Function<T,java.lang.Object> handler)
Requester<T>	withResponseFormat(Requester.Format format) Set the default format expected in the response.
Requester<T>	withTimeout(int timeout) The connection timeout setting in milliseconds.

Methods inherited from class java.lang.Object

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

Constructor Detail

Requester

public Requester(java.lang.String urlBase)

Get an instance of Requester from a JSON API type eg., User.request(). Requester is a builder type: you can configure the requests you'll make using withXxx() calls to specify an authorization token, response format, custom headers, etc. Then you can make one or more requests with a single instance:

 Requester<User> req = User.request("http://example.com/users")
   .withBearerAuthorization("xxx...x"); // eg., using OAuth token
 User user = req.getOne("/$id");
 user.setName("Scott");
 req.putOne("/$id", user);
 

Parameters:

urlBase - A URL providing HTTP services for T, such as "http://example.com/users"

Requester

public Requester(java.lang.String urlBase,
                 java.util.function.Function<java.lang.Object,java.lang.Object> resultCoercer)

Requester

public Requester(Endpoint endpoint)

Requester

public Requester(Endpoint endpoint,
                 java.util.function.Function<java.lang.Object,java.lang.Object> resultCoercer)

Method Detail

getEndpoint

public Endpoint getEndpoint()

getFormat

public Requester.Format getFormat()

getTimeout

public int getTimeout()

getHeaders

public java.util.Map<java.lang.String,java.lang.String> getHeaders()

getParameters

public java.util.Map<java.lang.String,java.lang.String> getParameters()

withCoercer

public Requester<T> withCoercer(java.util.function.Function<java.lang.Object,java.lang.Object> resultCoercer)

withResponseFormat

public Requester<T> withResponseFormat(Requester.Format format)

Set the default format expected in the response. The response will be parsed according to this setting.

Parameters:

format - Json, Yaml, Xml, Csv, or Plain text. Default is Json.

withHeader

public Requester<T> withHeader(java.lang.String name,
                               java.lang.String value)

Set an HTTP request header name : value pair See

withParam

public Requester<T> withParam(java.lang.String name,
                              java.lang.String value)

Add a name=value parameter to the request URL.

withBasicAuthorization

public Requester<T> withBasicAuthorization(java.lang.String username,
                                           java.lang.String password)

Set the Basic Authorization header using the provided username and password

withBearerAuthorization

public Requester<T> withBearerAuthorization(java.lang.String accessToken)

Set the Bearer Authorization header using the provided accessToken. For instance, if using OAuth, accessToken is the token response from:

 curl -d "grant_type=password&client_id=[...]&client_secret=[...]&username=[...]&password=[...]"
   https://[domain]/[oauth-service]
 

withAuthorization

public Requester<T> withAuthorization(java.lang.String tokenType,
                                      java.lang.String accessToken)

withTimeout

public Requester<T> withTimeout(int timeout)

The connection timeout setting in milliseconds. If the timeout expires before the connection can be established, a {@link java.net.SocketTimeoutException) is thrown. A value of zero is interpreted as an infinite timeout, this is the default setting.

withRawResponseHandler

public Requester<T> withRawResponseHandler(java.util.function.Function<T,java.lang.Object> handler)

Parameters:

handler - An optional handler for processing the raw response as an arbitrary Bindings instance. The handler may return a custom bindings object which overrides the default, type-safe result instance. In any case, the handler can process the response in any way. Note, modifications made to the response persist and, therefore, affect default internal data and error processing.

getRawResponseHandler

public java.util.function.Function<T,java.lang.Object> getRawResponseHandler()

Returns:

The raw response handler or null if one is not assigned.

getOne

public T getOne()

Use HTTP GET for a single T JSON API object specified in the urlSuffix, such as "/108".

Returns:

A single T JSON API object specified in the urlSuffix

Same as calling: getOne(String, Object, Format) with getOne("", null, _format)

getOne

public T getOne(java.lang.String urlSuffix)

Use HTTP GET for a single T JSON API object specified in the urlSuffix, such as "/108".

Parameters:

urlSuffix - A suffix identifying the T JSON API object to getOne

Returns:

A single T JSON API object specified in the urlSuffix

Same as calling: getOne(String, Object, Format) with getOne(urlSuffix, null, _format)

getOne

public T getOne(java.lang.Object arguments)

Same as calling: getOne(String, Object, Format) with getOne("", arguments, _format)

getOne

public T getOne(java.lang.String urlSuffix,
                java.lang.Object arguments)

Same as calling: getOne(String, Object, Format) with getOne(urlSuffix, arguments, _format)

getOne

public T getOne(java.lang.String urlSuffix,
                java.lang.Object arguments,
                Requester.Format format)

Make an HTTP GET request to urlBase + urlSuffix. arguments, if non-null, is sent in the URL as JSON encoded URL arguments.

Parameters:

arguments - A JSON value object, sent in the URL as JSON encoded arguments, nullable

urlSuffix - A suffix, such as "/108", nullable

format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain

Returns:

A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

getMany

public IJsonList<T> getMany()

Uses HTTP GET for the complete list of T JSON API objects as a IJsonList<T>.

Returns:

The complete list of T JSON API objects as a IJsonList<T>

Same as calling: getMany(String, Object, Format) with getMany("", null, _format)

getMany

public IJsonList<T> getMany(java.lang.String urlSuffix)

Same as calling: getMany(String, Object, Format) with getMany(urlSuffix, null, _format)

getMany

public IJsonList<T> getMany(java.lang.Object arguments)

Same as calling: getMany(String, Object, Format) with getMany("", arguments, _format)

getMany

public IJsonList<T> getMany(java.lang.String urlSuffix,
                            java.lang.Object arguments)

Same as calling: getMany(String, Object, Format) with getMany(urlSuffix, arguments, _format)

getMany

public IJsonList<T> getMany(java.lang.String urlSuffix,
                            java.lang.Object arguments,
                            Requester.Format format)

Make an HTTP GET request to urlBase + urlSuffix. arguments, if non-null, is sent in the URL as JSON encoded URL arguments.

Parameters:

arguments - A JSON value object, sent in the URL as JSON encoded arguments, nullable

urlSuffix - A suffix, such as "/108", nullable

format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain

Returns:

A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

postOne

public <R> R postOne(T payload)

Same as calling: postOne(String, Object, Format) with postOne("", payload, _format)

postOne

public <R> R postOne(java.lang.String urlSuffix,
                     T payload)

Same as calling: postOne(String, Object, Format) with postOne(urlSuffix, payload, _format)

postOne

public <R> R postOne(java.lang.String urlSuffix,
                     T payload,
                     Requester.Format format)

Make an HTTP POST request to urlBase + urlSuffix. The payload, if non-null, is sent as JSON encoded text in the request's message body.

Type Parameters:

R - The expected type of the response

Parameters:

payload - A JSON value object, sent as JSON encoded text in the request's message body

urlSuffix - A suffix, such as "/108", nullable

format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain

Returns:

A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

postMany

public <R> R postMany(java.util.List<T> payload)

Same as calling: postMany(String, List, Format) with postMany("", payload, _format)

postMany

public <R> R postMany(java.lang.String urlSuffix,
                      java.util.List<T> payload)

Same as calling: postMany(String, List, Format) with postMany(urlSuffix, payload, _format)

postMany

public <R> R postMany(java.lang.String urlSuffix,
                      java.util.List<T> payload,
                      Requester.Format format)

Make an HTTP POST request to urlBase + urlSuffix. The payload, if non-null, is sent as JSON encoded text in the request's message body.

Type Parameters:

R - The expected type of the response

Parameters:

payload - A JSON value object, sent as JSON encoded text in the request's message body

urlSuffix - A suffix, such as "/108", nullable

format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain

Returns:

A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

putOne

public <R> R putOne(T payload)

Same as calling: putOne(String, Object, Format) with putOne("", payload, _format)

putOne

public <R> R putOne(java.lang.String urlSuffix,
                    T payload)

Same as calling: putOne(String, Object, Format) with putOne(urlSuffix, payload, _format)

putOne

public <R> R putOne(java.lang.String urlSuffix,
                    T payload,
                    Requester.Format format)

Make an HTTP PUT request to urlBase + urlSuffix. The payload, if non-null, is sent as JSON encoded text in the request's message body.

Type Parameters:

R - The expected type of the response

Parameters:

payload - A JSON value object, sent as JSON encoded text in the request's message body

urlSuffix - A suffix, such as "/108", nullable

format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain

Returns:

A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

putMany

public <R> R putMany(java.util.List<T> payload)

Same as calling: putMany(String, List, Format) with putMany("", payload, _format)

putMany

public <R> R putMany(java.lang.String urlSuffix,
                     java.util.List<T> payload)

Same as calling: putMany(String, List, Format) with putMany(urlSuffix, payload, _format)

putMany

public <R> R putMany(java.lang.String urlSuffix,
                     java.util.List<T> payload,
                     Requester.Format format)

Make an HTTP PUT request to urlBase + urlSuffix. The payload, if non-null, is sent as JSON encoded text in the request's message body.

Type Parameters:

R - The expected type of the response

Parameters:

payload - A JSON value object, sent as JSON encoded text in the request's message body

urlSuffix - A suffix, such as "/108", nullable

format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain

Returns:

A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

patchOne

public <R> R patchOne(T payload)

Same as calling: patchOne(String, Object, Format) with patchOne("", payload, _format)

patchOne

public <R> R patchOne(java.lang.String urlSuffix,
                      T payload)

Same as calling: patchOne(String, Object, Format) with patchOne(urlSuffix, payload, _format)

patchOne

public <R> R patchOne(java.lang.String urlSuffix,
                      T payload,
                      Requester.Format format)

Make an HTTP PATCH request to urlBase + urlSuffix. The payload, if non-null, is sent as JSON encoded text in the request's message body.

Type Parameters:

R - The expected type of the response

Parameters:

payload - A JSON value object, sent as JSON encoded text in the request's message body

urlSuffix - A suffix, such as "/108", nullable

format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain

Returns:

A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

patchMany

public <R> R patchMany(java.util.List<T> payload)

Same as calling: patchMany(String, List, Format) with patchMany("", payload, _format)

patchMany

public <R> R patchMany(java.lang.String urlSuffix,
                       java.util.List<T> payload)

Same as calling: patchMany(String, List, Format) with patchMany(urlSuffix, payload, _format)

patchMany

public <R> R patchMany(java.lang.String urlSuffix,
                       java.util.List<T> payload,
                       Requester.Format format)

Make an HTTP PATCH request to urlBase + urlSuffix. The payload, if non-null, is sent as JSON encoded text in the request's message body.

Type Parameters:

R - The expected type of the response

Parameters:

payload - A JSON value object, sent as JSON encoded text in the request's message body

urlSuffix - A suffix, such as "/108", nullable

format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain

Returns:

A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

delete

public <R> R delete(java.lang.Object arguments)

Same as calling: delete(String, Object, Format) with delete("", arguments, _format)

delete

public <R> R delete(java.lang.String urlSuffix)

Same as calling: delete(String, Object, Format) with delete(urlSuffix, null, _format)

delete

public <R> R delete(java.lang.String urlSuffix,
                    java.lang.Object arguments)

Same as calling: delete(String, Object, Format) with delete(urlSuffix, arguments, _format)

delete

public <R> R delete(java.lang.String urlSuffix,
                    java.lang.Object arguments,
                    Requester.Format format)

Make an HTTP DELETE request to urlBase + urlSuffix. The payload, if non-null, is sent in the URL as JSON encoded URL arguments.

Type Parameters:

R - The expected type of the response

Parameters:

arguments - A JSON value object, sent in the URL as JSON encoded arguments, nullable

urlSuffix - A suffix, such as "/108", nullable

format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain

Returns:

A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)