uk.co.visalia.brightpearl.apiclient

Class BrightpearlLegacyApiSession

java.lang.Object

uk.co.visalia.brightpearl.apiclient.BrightpearlLegacyApiSession

public final class BrightpearlLegacyApiSession
extends Object

For use with Brightpearl's old method of authentication - staff tokens access using staff email address and password. These tokens are not specific to any developer or app, so the new method of using app credentials should be used in preference.

This class provides a simple interface for calls to a single account, and management of API sessions including automatic reauthentication if required. A session may be created with email and password credentials, which supports automatic reauth, or with a pre-fetched authentication token, which gives a session that is valid until the token expires.

An instance is specific to an account and uses internal synchronization to delay requests for that account from other threads while one thread is attempting authentication. If automatic reauth is enabled, the same applies when a request fails due to the token expiring - the thread that first receives a 401 response from Brightpearl will attempt to re-auth, while other threads block and wait for the result. This prevents further wasted calls with an auth token known to be invalid.

If a user's password has been changed, the BrightpearlApiSession instance cannot be recovered without changing it back again. The only recourse is to discard the session and start a new one.

Calls are passed to BrightpearlApiClient for execution and parsing.

Method Summary

Methods

Modifier and Type	Method and Description
String	authenticate() Authenticates this session.
MultiResponse	execute(MultiRequest multiRequest) Executes a multimessage and returns the parsed responses and error messages.
MultiResponse	execute(MultiRequestBuilder multiRequestBuilder) Executes a multimessage and returns the parsed responses and error messages.
<T> T	execute(ServiceWriteRequest<T> request) Executes a write (PUT, POST, DELETE) request and returns the parsed response if the request was successful.
<T> T	execute(ServiceWriteRequestBuilder<T> requestBuilder) Executes a write (PUT, POST, DELETE) request and returns the parsed response if the request was successful.
<T> T	get(ServiceReadRequest<T> request) Executes a GET or OPTIONs request and returns the parsed response if the request was successful.
<T> T	get(ServiceReadRequestBuilder<T> requestBuilder) Executes a GET or OPTIONs request and returns the parsed response if the request was successful.
<T> SearchResults<T>	search(SearchRequestBuilder<T> requestBuilder) Executes a search request and returns the parsed response if the request was successful.
<T> SearchResults<T>	search(ServiceSearchRequest<T> request) Executes a search request and returns the parsed response if the request was successful.

Methods inherited from class java.lang.Object

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

Method Detail

authenticate

public String authenticate()

Authenticates this session. For use in sessions using user credentials, and not pre-authenticated sessions that were created with an auth token. The token is stored in the session and also returned.

It is not necessary to manually authenticate before using the session; the first request made will prompt authentication if necessary. However, this will block requests from other threads so in systems that may experience high load immediately once started - or once added to a load balancer - manually authenticating during startup is recommended.

Returns:

The new auth token.

get

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

Executes a GET or OPTIONs request and returns the parsed response if the request was successful. Success is defined as a 2xx response code with a response element that could be successfully deserialised to the expected type. If the server returned an error or the response element could not be parsed, a BrightpearlClientException subclass will be thrown.

This is a convenience method that accepts a builder so you don't need to call its ServiceReadRequestBuilder.build() method.

Type Parameters:

T - Type of the expected response.

Parameters:

requestBuilder - a ServiceReadRequestBuilder with all required fields set.

Returns:

a response of the desired type, if the request was successful and the response was deserialised.

See Also:

BrightpearlApiClient.get(uk.co.visalia.brightpearl.apiclient.auth.AppAuthorisation, uk.co.visalia.brightpearl.apiclient.request.ServiceReadRequest)

get

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

Executes a GET or OPTIONs request and returns the parsed response if the request was successful. Success is defined as a 2xx response code with a response element that could be successfully deserialised to the expected type. If the server returned an error or the response element could not be parsed, a BrightpearlClientException subclass will be thrown.

Type Parameters:

T - Type of the expected response.

Parameters:

request - a ServiceReadRequest with all required fields set.

Returns:

a response of the desired type, if the request was successful and the response was deserialised.

See Also:

BrightpearlApiClient.get(uk.co.visalia.brightpearl.apiclient.auth.AppAuthorisation, uk.co.visalia.brightpearl.apiclient.request.ServiceReadRequest)

search

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

Executes a search request and returns the parsed response if the request was successful. Success is defined as a 2xx response code with search results that could be successfully deserialised to the expected type. If the server returned an error or the response element could not be parsed, a BrightpearlClientException subclass will be thrown.

This is a convenience method that accepts a builder so you don't need to call its SearchRequestBuilder.build() method.

Type Parameters:

T - Type of the expected search result.

Parameters:

requestBuilder - a SearchRequestBuilder with all required fields set.

Returns:

a search response containing results of the desired type, if the request was successful and the response was deserialised.

See Also:

BrightpearlApiClient.search(uk.co.visalia.brightpearl.apiclient.auth.AppAuthorisation, uk.co.visalia.brightpearl.apiclient.request.ServiceSearchRequest)

search

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

Executes a search request and returns the parsed response if the request was successful. Success is defined as a 2xx response code with search results that could be successfully deserialised to the expected type. If the server returned an error or the response element could not be parsed, a BrightpearlClientException subclass will be thrown.

Type Parameters:

T - Type of the expected search result.

Parameters:

request - a ServiceSearchRequest with all required fields set.

Returns:

a search response containing results of the desired type, if the request was successful and the response was deserialised.

See Also:

BrightpearlApiClient.search(uk.co.visalia.brightpearl.apiclient.auth.AppAuthorisation, uk.co.visalia.brightpearl.apiclient.request.ServiceSearchRequest)

execute

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

Executes a write (PUT, POST, DELETE) request and returns the parsed response if the request was successful. Success is defined as a 2xx response code with a response that could be successfully deserialised to the expected type. If the server returned an error or the response element could not be parsed, a BrightpearlClientException subclass will be thrown.

This is a convenience method that accepts a builder so you don't need to call its ServiceWriteRequestBuilder.build() method.

Type Parameters:

T - Type of the expected result.

Parameters:

requestBuilder - a ServiceWriteRequestBuilder with all required fields set.

Returns:

a response of the desired type, if the request was successful and the response was deserialised.

See Also:

BrightpearlApiClient.execute(uk.co.visalia.brightpearl.apiclient.auth.AppAuthorisation, uk.co.visalia.brightpearl.apiclient.request.ServiceWriteRequest)

execute

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

Executes a write (PUT, POST, DELETE) request and returns the parsed response if the request was successful. Success is defined as a 2xx response code with a response that could be successfully deserialised to the expected type. If the server returned an error or the response element could not be parsed, a BrightpearlClientException subclass will be thrown.

Type Parameters:

T - Type of the expected result.

Parameters:

request - a ServiceWriteRequest with all required fields set.

Returns:

a response of the desired type, if the request was successful and the response was deserialised.

See Also:

BrightpearlApiClient.execute(uk.co.visalia.brightpearl.apiclient.auth.AppAuthorisation, uk.co.visalia.brightpearl.apiclient.request.ServiceWriteRequest)

execute

public MultiResponse execute(MultiRequestBuilder multiRequestBuilder)

Executes a multimessage and returns the parsed responses and error messages. See the documentation for BrightpearlApiClient.execute(uk.co.visalia.brightpearl.apiclient.auth.AppAuthorisation, MultiRequest) for a full description. This method adds automatic reauthentication and retry when a multimessage is rejected because the auth token is expired.

This is a convenience method that accepts a builder so you don't need to call its MultiRequestBuilder.build() method.

Parameters:

multiRequestBuilder - a MultiRequestBuilder to be executed.

Returns:

results of the request execution.

See Also:

BrightpearlApiClient.execute(uk.co.visalia.brightpearl.apiclient.auth.AppAuthorisation, MultiRequest)

execute

public MultiResponse execute(MultiRequest multiRequest)

Executes a multimessage and returns the parsed responses and error messages. See the documentation for BrightpearlApiClient.execute(uk.co.visalia.brightpearl.apiclient.auth.AppAuthorisation, MultiRequest) for a full description. This method adds automatic reauthentication and retry when a multimessage is rejected because the auth token is expired.

Parameters:

multiRequest - a MultiRequest to be executed.

Returns:

results of the request execution.

See Also:

BrightpearlApiClient.execute(uk.co.visalia.brightpearl.apiclient.auth.AppAuthorisation, MultiRequest)