uk.co.visalia.brightpearl.apiclient

Class BrightpearlApiClient.ApiSession

java.lang.Object

uk.co.visalia.brightpearl.apiclient.BrightpearlApiClient.ApiSession

Enclosing class:

BrightpearlApiClient

public class BrightpearlApiClient.ApiSession
extends Object

An authenticated API session configured with a Brightpearl customer account and headers needed to authenticate calls for a single app of any type. This provides a shortcut to using the methods on the parent BrightpearlApiClient class, each of which requires identity and credentials to be passed to every call.

Method Summary

Methods

Modifier and Type	Method and Description
MultiResponse	execute(MultiRequest multiRequest) Executes a multi message request.
MultiResponse	execute(MultiRequestBuilder multiRequestBuilder) Convenience method equivalent to execute(MultiRequest), this calls MultiRequestBuilder.build() on the supplied builder for executing the request.
<T> T	execute(ServiceWriteRequest<T> serviceRequest) Make a POST, PUT or DELETE call to the API.
<T> T	execute(ServiceWriteRequestBuilder<T> serviceRequestBuilder) Convenience shortcut for execute(uk.co.visalia.brightpearl.apiclient.request.ServiceWriteRequest).
<T> T	get(ServiceReadRequest<T> serviceRequest) Make a GET or OPTIONS call to the API, and extract the expected response entity from the JSON returned.
<T> T	get(ServiceReadRequestBuilder<T> serviceRequestBuilder) Convenience shortcut for get(ServiceReadRequest).
Response	getHttpResponse(AbstractServiceRequest serviceRequest) Executes a request and returns the response as an unparsed string of JSON together with the HTTP status code and headers, exactly as returned by the Client implementation.
<T> SearchResults<T>	search(SearchRequestBuilder<T> serviceRequestBuilder) Convenience shortcut for search(uk.co.visalia.brightpearl.apiclient.request.ServiceSearchRequest).
<T> SearchResults<T>	search(ServiceSearchRequest<T> serviceRequest) Makes a GET call to a search API, and deserialises the response into a SearchResults object that contains meta information, reference data and a list of results.

Methods inherited from class java.lang.Object

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

Method Detail

get

public <T> T get(ServiceReadRequestBuilder<T> serviceRequestBuilder)

Convenience shortcut for get(ServiceReadRequest). Calls build on the supplied builder and makes the call to the API.

Type Parameters:

T - Type of expected response.

Parameters:

serviceRequestBuilder - Builder for read request to be executed.

Returns:

If the request was successful, a response of the expected type.

get

public <T> T get(ServiceReadRequest<T> serviceRequest)

Make a GET or OPTIONS call to the API, and extract the expected response entity from the JSON returned. If a valid cached response is available this will be returned. Subclasses of BrightpearlClientException are thrown if there is a failure, and other runtime exceptions may be thrown by custom implementations of ClientFactory.

Type Parameters:

T - Type of expected response.

Parameters:

serviceRequest - A read request to be made.

Returns:

If the request was successful, a response of the expected type.

search

public <T> SearchResults<T> search(SearchRequestBuilder<T> serviceRequestBuilder)

Convenience shortcut for search(uk.co.visalia.brightpearl.apiclient.request.ServiceSearchRequest). Calls build on the supplied builder and makes the call to the API.

Type Parameters:

T - Type of expected response.

Parameters:

serviceRequestBuilder - Builder for search request to be executed.

Returns:

If the request was successful, a SearchResults object containing parsed results and meta information.

search

public <T> SearchResults<T> search(ServiceSearchRequest<T> serviceRequest)

Makes a GET call to a search API, and deserialises the response into a SearchResults object that contains meta information, reference data and a list of results.

If a valid cached response is available this will be returned. Transport errors and other request failures are thrown as subclasses of BrightpearlClientException unless a custom HTTP client or rate limiter implementation throws a different type.

This method uses the column names returned in the search metadata to populate objects of the requested type with values from each array in the results. Therefore the expected response type declared in the search request should be a flat object (i.e. only primitives, Strings and Dates) with fields either named or annotated with com.google.gson.annotations.SerializedName according to the column names expected. In many cases, the more complex type used for resource GETs will be unsuitable for use with the corresponding resource search.

Type Parameters:

T - Type of expected response.

Parameters:

serviceRequest - The search request to be executed.

Returns:

If the request was successful, a SearchResults object containing parsed results and meta information.

execute

public <T> T execute(ServiceWriteRequestBuilder<T> serviceRequestBuilder)

Convenience shortcut for execute(uk.co.visalia.brightpearl.apiclient.request.ServiceWriteRequest). Calls build on the supplied builder and makes the call to the API.

Type Parameters:

T - Type of expected response. Use Void.class if no response body is expected.

Parameters:

serviceRequestBuilder - Builder for write request to be executed.

Returns:

If the request was successful, a response of the expected type, null if the declared type was Void.

execute

public <T> T execute(ServiceWriteRequest<T> serviceRequest)

Make a POST, PUT or DELETE call to the API. Subclasses of BrightpearlClientException are thrown if there is a failure, and other runtime exceptions may be thrown by custom implementations of ClientFactory.

Type Parameters:

T - Type of expected response. Use Void.class if no response body is expected.

Parameters:

serviceRequest - A write request to be made.

Returns:

If the request was successful, a response of the expected type, null if the declared type was Void.

execute

public MultiResponse execute(MultiRequestBuilder multiRequestBuilder)

Convenience method equivalent to execute(MultiRequest), this calls MultiRequestBuilder.build() on the supplied builder for executing the request.

Parameters:

multiRequestBuilder - Multimessage request builder to be executed.

Returns:

a MultiResponse object containing the results.

execute

public MultiResponse execute(MultiRequest multiRequest)

Executes a multi message request. Multi-messages can decrease latency when sending multiple write requests, and count as only one request for rate limiting purposes. Use MultiRequestBuilder to assemble a multi message.

Errors executing the multi message request itself are thrown as exceptions from this method and generally indicate that none of the individual requests have been executed by Brightpearl, though this cannot be guaranteed. For example if the connection was broken after the request was sent, the result cannot be recovered. Errors in the responses for individual requests are stored in the ServiceResponse corresponding to the request, so they can be handled individually.

The Brightpearl multi message API supports sending messages containing between two and ten and individual requests. This client simplifies the use of this API by supporting any number of individual requests. If the supplied multi message wrapper contains only one request it will be sent direct to the relevant API, and if the wrapper contains more than ten requests it will be split into batches of ten and executed in serial. In both cases this method attempts to mimic the behaviour that would be expected if all the requests had been sent in one multi-message. However there are limitations to be aware of.

Single request: If the MultiRequest supplied contains only one request, it is sent direct to the relevant API. HTTP transport errors are thrown by this method, and the response from the Brightpearl API is returned in a mocked up MultiResponse wrapper with the wrapper status set to 200 if the individual response had status 200, and 207 otherwise.

More than ten requests: The requests are split up into batches of between two and ten (batches of one are avoided for consistency) and sent to the multi message API in sequence. HTTP transport exceptions will only be thrown if the first batch fails with these errors; if a later batch fails with a transport error that batch and all following ones will be aborted (regardless of the OnFailOption) and their request IDs included in the unprocessedRequestIds field of the response. This is done so that the results of any successful batches can be returned and inspected, and the list of unprocessed IDs handled, but it doesn't match the behaviour of the Brightpearl API. If the status code of a batch is not 200, and the OnFailOption is OnFailOption.STOP, later batches are not sent, otherwise all batches will be run barring transport errors.

A batch of between two and ten requests is guaranteed to be sent as a single multi message, and therefore will avoid behaviour that may not exactly match that provided by Brightpearl. Clients that have complex error recovery requirements should avoid sending less than two or more than ten requests. The MultiMessageUtils.split(MultiRequest) utility may be used to split a request into batches.

Parameters:

multiRequest - Multimessage request to be executed.

Returns:

a MultiResponse object containing the results.

getHttpResponse

public Response getHttpResponse(AbstractServiceRequest serviceRequest)

Executes a request and returns the response as an unparsed string of JSON together with the HTTP status code and headers, exactly as returned by the Client implementation. This method bypasses the detection of failure response codes and error messages in the response body provided by other methods, so does not throw specific exceptions such as BrightpearlAuthException. Rate limiting is supported.

This method may be used to execute all types of request.

An exception will only be thrown for HTTP transport errors, which will usually result in a BrightpearlClientException unless a custom HTTP client implementation throws a different type.

Parameters:

serviceRequest - Request to be sent.

Returns:

Unprocessed HTTP response.