uk.co.visalia.brightpearl.apiclient

Class BrightpearlApiClient

java.lang.Object

uk.co.visalia.brightpearl.apiclient.BrightpearlApiClient

public final class BrightpearlApiClient
extends Object

Main client class for the Brightpearl API. This supports public and private apps of both types, system and staff. An instance of this class is designed to be shared amongst many apps and accounts if necessary.

An instance is thread-safe assuming the instance of ClientFactory provided is thread-safe, as all implementations provided with this library are. Instances are not specific to any account and can be safely reused for multiple accounts.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	BrightpearlApiClient.ApiSession An authenticated API session configured with a Brightpearl customer account and headers needed to authenticate calls for a single app of any type.

Method Summary

Methods

Modifier and Type	Method and Description
BrightpearlApiClient.ApiSession	createSession(AppAuthorisation authorisation) Creates a session an app and account.
MultiResponse	execute(AppAuthorisation authorisation, MultiRequest multiRequest) Executes a multi message request.
MultiResponse	execute(AppAuthorisation authorisation, MultiRequestBuilder multiRequestBuilder) Convenience method equivalent to execute(AppAuthorisation, MultiRequest), this calls MultiRequestBuilder.build() on the supplied builder for executing the request.
<T> T	execute(AppAuthorisation authorisation, ServiceWriteRequest<T> serviceRequest) Make a POST, PUT or DELETE call to the API.
<T> T	execute(AppAuthorisation authorisation, ServiceWriteRequestBuilder<T> serviceRequestBuilder) Convenience shortcut for execute(AppAuthorisation, ServiceWriteRequest).
String	fetchLegacyAuthToken(Account account, UserCredentials userCredentials) Using Brightpearl account details and user credentials, attempts authentication of the user and returns an auth token if the request was successful.
String	fetchStaffToken(PrivateAppIdentity appIdentity, UserCredentials userCredentials) Using private app details and user credentials, attempts authentication of the user and returns their staff token if they are authorised to use the app.
String	fetchStaffToken(PublicAppIdentity appIdentity, Account account, UserCredentials userCredentials) Using private app details and user credentials, attempts authentication of the user and returns their staff token if they are authorised to use the app.
<T> T	get(AppAuthorisation authorisation, 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(AppAuthorisation authorisation, ServiceReadRequestBuilder<T> serviceRequestBuilder) Convenience shortcut for get(AppAuthorisation, ServiceReadRequest).
Response	getHttpResponse(AppAuthorisation authorisation, 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(AppAuthorisation authorisation, SearchRequestBuilder<T> serviceRequestBuilder) Convenience shortcut for search(AppAuthorisation, ServiceSearchRequest).
<T> SearchResults<T>	search(AppAuthorisation authorisation, 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

fetchLegacyAuthToken

public String fetchLegacyAuthToken(Account account,
                          UserCredentials userCredentials)

Using Brightpearl account details and user credentials, attempts authentication of the user and returns an auth token if the request was successful. If the credentials are invalid, an BrightpearlServiceException will be thrown, with an error code that, in most cases, starts with "GWY".

Parameters:

account - Details of customer account to authenticate with.

userCredentials - Credentials of an API-enabled user in the account.

Returns:

an auth token for the user.

fetchStaffToken

public String fetchStaffToken(PrivateAppIdentity appIdentity,
                     UserCredentials userCredentials)

Using private app details and user credentials, attempts authentication of the user and returns their staff token if they are authorised to use the app. If the credentials are invalid, an BrightpearlServiceException will be thrown, with an error code that, in most cases, starts with "GWY".

Parameters:

appIdentity - Details of a private app, including the Brightpearl customer account.

userCredentials - Credentials of user in the account.

Returns:

a staff token for the user.

fetchStaffToken

public String fetchStaffToken(PublicAppIdentity appIdentity,
                     Account account,
                     UserCredentials userCredentials)

Using private app details and user credentials, attempts authentication of the user and returns their staff token if they are authorised to use the app. If the credentials are invalid, an BrightpearlServiceException will be thrown, with an error code that, in most cases, starts with "GWY".

Parameters:

appIdentity - Details of a public app.

account - A Brightpearl customer's account details.

userCredentials - Credentials of user in the account.

Returns:

a staff token for the user.

createSession

public BrightpearlApiClient.ApiSession createSession(AppAuthorisation authorisation)

Creates a session an app and account.

Returns:

an BrightpearlApiClient.ApiSession instance. This contains a reference to the instance.

execute

public MultiResponse execute(AppAuthorisation authorisation,
                    MultiRequestBuilder multiRequestBuilder)

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

Parameters:

authorisation - App and account authorisation details.

multiRequestBuilder - Multimessage request builder to be executed.

Returns:

a MultiResponse object containing the results.

execute

public MultiResponse execute(AppAuthorisation authorisation,
                    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:

authorisation - App and account authorisation details.

multiRequest - Multimessage request to be executed.

Returns:

a MultiResponse object containing the results.

get

public <T> T get(AppAuthorisation authorisation,
        ServiceReadRequestBuilder<T> serviceRequestBuilder)

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

Type Parameters:

T - Type of expected response.

Parameters:

authorisation - App and account authorisation details.

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(AppAuthorisation authorisation,
        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:

authorisation - App and account authorisation details.

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(AppAuthorisation authorisation,
                          SearchRequestBuilder<T> serviceRequestBuilder)

Convenience shortcut for search(AppAuthorisation, ServiceSearchRequest). Calls build on the supplied builder and makes the call to the API.

Type Parameters:

T - Type of expected response.

Parameters:

authorisation - App and account authorisation details.

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(AppAuthorisation authorisation,
                          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:

authorisation - App and account authorisation details.

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(AppAuthorisation authorisation,
            ServiceWriteRequestBuilder<T> serviceRequestBuilder)

Convenience shortcut for execute(AppAuthorisation, 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:

authorisation - App and account authorisation details.

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(AppAuthorisation authorisation,
            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:

authorisation - App and account authorisation details.

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.

getHttpResponse

public Response getHttpResponse(AppAuthorisation authorisation,
                       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:

authorisation - App and account authorisation details.

serviceRequest - Read request to be sent.

Returns:

Unprocessed HTTP response.