uk.co.visalia.brightpearl.apiclient

Class BrightpearlLegacyApiSessionFactory

java.lang.Object

uk.co.visalia.brightpearl.apiclient.BrightpearlLegacyApiSessionFactory

public final class BrightpearlLegacyApiSessionFactory
extends Object

A factory class used to create BrightpearlLegacyApiSessions, which are specific to a Brightpearl account. Sessions may optionally be provided with user credentials; if user credentials are provided, automatic re-authentication is supported.

Each factory instance is specific to a Brightpearl customer account because it requires the account details (datacenter and customer code) to create a session instance for that account. At minimum, the factory must be configured with the account details by calling setAccount(Account), and if configured credentials are to be used, setUserCredentials(uk.co.visalia.brightpearl.apiclient.account.UserCredentials) must also be called.

Factory instances are intended to be persistent and used to create multiple sessions for an account during the lifetime of an application as authentication tokens expire, but when automatic reauth is enabled and sessions are created using credentials, one session may last indefinitely. In any case, only one active session for an account should be used at any time to avoid unexpected behaviour, for example exceeding the expected connection limit, or hitting the request cap despite using a strategy to avoid it. This factory may be wrapped in a facade that caches the active session until it expires to provide this behaviour.

Instances can be constructed in code, and this class can also be used as a Spring bean factory provided that credentials authentication is being used. For example:

 <bean id="brightpearlApiSessionFactory" class="uk.co.visalia.brightpearl.apiclient.BrightpearlLegacyApiSessionFactory">
     <property name="brightpearlApiClient" ref="..."/>
 </bean>

 <bean id="brightpearlApiSession"
     factory-bean="brightpearlApiSessionFactory"
     factory-method="newApiSession"/>
 

Constructor Summary

Constructors

Constructor and Description
BrightpearlLegacyApiSessionFactory()

Method Summary

Methods

Modifier and Type	Method and Description
BrightpearlLegacyApiSession	newApiSession() Creates a new session using configured credentials.
static BrightpearlLegacyApiSessionFactory	newApiSessionFactory() Creates a new session factory instance.
BrightpearlLegacyApiSession	newPreauthenticatedApiSession(String authToken) Creates a new session pre-authenticated with a token generated independently.
void	setAccount(Account account) Set the target Brightpearl customer account for sessions created by this factory.
void	setBrightpearlApiClient(BrightpearlApiClient brightpearlApiClient) Set the underlying BrightpearlApiClient that requests are sent to for execution.
void	setExpiredAuthTokenStrategy(ExpiredAuthTokenStrategy expiredAuthTokenStrategy) Set the strategy to use when credentials authentication is configured and the current auth token expires.
void	setUserCredentials(UserCredentials userCredentials) Set the credentials of an API-enabled user account associated with the customer account.
BrightpearlLegacyApiSessionFactory	withAccount(Account account) Set the target Brightpearl customer account for sessions created by this factory.
BrightpearlLegacyApiSessionFactory	withBrightpearlApiClient(BrightpearlApiClient brightpearlApiClient) Set the underlying BrightpearlApiClient that requests are sent to for execution.
BrightpearlLegacyApiSessionFactory	withExpiredAuthTokenStrategy(ExpiredAuthTokenStrategy expiredAuthTokenStrategy) Set the strategy to use when credentials authentication is configured and the current auth token expires.
BrightpearlLegacyApiSessionFactory	withUserCredentials(UserCredentials userCredentials) Set the credentials of an API-enabled user account associated with the customer account.

Methods inherited from class java.lang.Object

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

Constructor Detail

BrightpearlLegacyApiSessionFactory

public BrightpearlLegacyApiSessionFactory()

Method Detail

newApiSessionFactory

public static BrightpearlLegacyApiSessionFactory newApiSessionFactory()

Creates a new session factory instance.

setBrightpearlApiClient

public void setBrightpearlApiClient(BrightpearlApiClient brightpearlApiClient)

Set the underlying BrightpearlApiClient that requests are sent to for execution. If this method is not called, an instance of the class using all its default settings will be used.

Parameters:

brightpearlApiClient - custom configured BrightpearlApiClient instance.

setAccount

public void setAccount(Account account)

Set the target Brightpearl customer account for sessions created by this factory.

Parameters:

account - target account.

setUserCredentials

public void setUserCredentials(UserCredentials userCredentials)

Set the credentials of an API-enabled user account associated with the customer account. Credentials are not required if sessions will be created with tokens generated externally.

Parameters:

userCredentials - credentials of an API user.

setExpiredAuthTokenStrategy

public void setExpiredAuthTokenStrategy(ExpiredAuthTokenStrategy expiredAuthTokenStrategy)

Set the strategy to use when credentials authentication is configured and the current auth token expires.

Parameters:

expiredAuthTokenStrategy - auth token expiry strategy.

withBrightpearlApiClient

public BrightpearlLegacyApiSessionFactory withBrightpearlApiClient(BrightpearlApiClient brightpearlApiClient)

Set the underlying BrightpearlApiClient that requests are sent to for execution. If this method is not called, an instance of the class using all its default settings will be used.

Parameters:

brightpearlApiClient - custom configured BrightpearlApiClient instance.

Returns:

builder instance for method chaining.

withAccount

public BrightpearlLegacyApiSessionFactory withAccount(Account account)

Set the target Brightpearl customer account for sessions created by this factory.

Parameters:

account - target account.

Returns:

builder instance for method chaining.

withUserCredentials

public BrightpearlLegacyApiSessionFactory withUserCredentials(UserCredentials userCredentials)

Set the credentials of an API-enabled user account associated with the customer account. Credentials are not required if sessions will be created with tokens generated externally.

Parameters:

userCredentials - credentials of an API user.

Returns:

builder instance for method chaining.

withExpiredAuthTokenStrategy

public BrightpearlLegacyApiSessionFactory withExpiredAuthTokenStrategy(ExpiredAuthTokenStrategy expiredAuthTokenStrategy)

Set the strategy to use when credentials authentication is configured and the current auth token expires.

Parameters:

expiredAuthTokenStrategy - auth token expiry strategy.

Returns:

builder instance for method chaining.

newApiSession

public BrightpearlLegacyApiSession newApiSession()

Creates a new session using configured credentials. An auth token will be generated either when BrightpearlLegacyApiSession.authenticate() is called, or when the first request is made.

Automatic re-authentication is disabled by default and may be enabled by calling setExpiredAuthTokenStrategy(ExpiredAuthTokenStrategy) with ExpiredAuthTokenStrategy.REAUTHENTICATE. With this configuration, the session will detect authentication failures and make one attempt at re-authenticating with the same credentials before retrying the request that failed. Unless the API user's password is changed, which will prevent re-authentication, this allows one ApiSession instance to last indefinitely.

Returns:

a configured and immutable BrightpearlLegacyApiSession.

newPreauthenticatedApiSession

public BrightpearlLegacyApiSession newPreauthenticatedApiSession(String authToken)

Creates a new session pre-authenticated with a token generated independently.

If credentials have been supplied and automatic re-authentication has been enabled by calling setExpiredAuthTokenStrategy(ExpiredAuthTokenStrategy) with ExpiredAuthTokenStrategy.REAUTHENTICATE, a new token can be generated when the provided one expires. With this configuration, the session will detect authentication failures and make one attempt at re-authenticating with the same credentials before retrying the request that failed. Unless the API user's password is changed, which will prevent re-authentication, this allows one ApiSession instance to last indefinitely.

If no credentials are supplied or the strategy is set to ExpiredAuthTokenStrategy.FAIL, the session will last until the first time a request is rejected because the token has expired, which occurs after an undefined period of inactivity.

This method allows you to manually provide an auth token for a single use session, or prime a new long-lived session with a stored token - useful for Android where keeping a session instance alive may be undesirable. Avoid priming a new session with a token that has not been used for 30 minutes, because the first request is guaranteed to fail.

Parameters:

authToken - the initial auth token to be used for this session.

Returns:

an BrightpearlLegacyApiSession instance.