Package com.atlassian.oauth2.client.api.storage

Interface TokenHandler

@PublicApi
public interface TokenHandler

Utilities for working with OAuth 2.0 tokens.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	TokenHandler.ClientTokenCallback<T>	Callback to execute with a ClientToken.
static class	TokenHandler.InvalidTokenException	Indicates that there was a problem with a ClientToken and it couldn't be used for successful authorisation with an OAuth 2.0 resource server.

Method Summary

Modifier and Type	Method	Description
boolean	deleteTokenByValue(String tokenValue)	Delete the OAuth2 Token by the access or refresh token.
<T> T	execute(String clientTokenId, TokenHandler.ClientTokenCallback<T> callback)	Handles the use of ClientToken, automatically applying a refresh before executing the callback if required.
<T> T	execute(String clientTokenId, TokenHandler.ClientTokenCallback<T> callback, Duration margin)	Handles the use of ClientToken, automatically applying a refresh before executing the callback if required.
ClientToken	getRefreshedToken(String clientTokenId)	Refreshes and returns the client token, saving the up to date token to the store.
OAuth2Token	getRefreshedToken(String externalId, String configId, Duration margin)	Fetches the OAuth2 Token for a given resource owner and configuration.
ClientToken	getRefreshedToken(String clientTokenId, Duration margin)	Refreshes if access token is already expired or expires within the margin period.

Method Details

execute

<T> T execute(String clientTokenId,
 TokenHandler.ClientTokenCallback<T> callback)
       throws UnrecoverableTokenException,
RecoverableTokenException

Handles the use of ClientToken, automatically applying a refresh before executing the callback if required.

This method may update the ClientTokenMetadata of the token.

Note that the TokenHandler.ClientTokenCallback may be executed more than once if it throws TokenHandler.InvalidTokenException.

Type Parameters:

T - the result type.

Parameters:

clientTokenId - the id of the token to be used in the execution, or to be refreshed if required

callback - the callback to be executed.

Returns:

the result of the callback

Throws:

UnrecoverableTokenException - thrown if the token is invalid and can't be automatically refreshed

RecoverableTokenException - thrown if the token is invalid but it might be possible to recover

execute

<T> T execute(String clientTokenId,
 TokenHandler.ClientTokenCallback<T> callback,
 Duration margin)
       throws UnrecoverableTokenException,
RecoverableTokenException

Handles the use of ClientToken, automatically applying a refresh before executing the callback if required.

This method may update the ClientTokenMetadata of the token.

Note that the TokenHandler.ClientTokenCallback may be executed more than once if it throws TokenHandler.InvalidTokenException.

Type Parameters:

T - the result type.

Parameters:

clientTokenId - the id of the token to be used in the execution, or to be refreshed if required

callback - the callback to be executed.

margin - only refreshes token if expiry is before now + margin

Returns:

the result of the callback

Throws:

UnrecoverableTokenException - thrown if the token is invalid and can't be automatically refreshed

RecoverableTokenException - thrown if the token is invalid but it might be possible to recover

getRefreshedToken

OAuth2Token getRefreshedToken(@Nonnull
 String externalId,
 @Nonnull
 String configId,
 @Nonnull
 Duration margin)
                       throws UnrecoverableTokenException,
RecoverableTokenException

Fetches the OAuth2 Token for a given resource owner and configuration. If the access token is expired a new one will be automatically refreshed.

Parameters:

externalId - the id for whom the token belongs to

configId - the id of the configuration that the token was generated from

margin - refresh the token if expiry is before now + margin

Returns:

OAuth2Token containing the access token and relevant metadata

Throws:

UnrecoverableTokenException - thrown if the token is invalid and can't be automatically refreshed

RecoverableTokenException - thrown if the token is invalid, but it might be possible to recover

Since:

4.1.0

deleteTokenByValue

boolean deleteTokenByValue(@Nonnull
 String tokenValue)

Delete the OAuth2 Token by the access or refresh token.

Parameters:

tokenValue - The access or refresh token

Returns:

true if the token was deleted, false if the token could not be deleted

Since:

4.1.3

getRefreshedToken

ClientToken getRefreshedToken(String clientTokenId)
                       throws UnrecoverableTokenException,
RecoverableTokenException

Refreshes and returns the client token, saving the up to date token to the store. May update ClientTokenMetadata of the token.

Parameters:

clientTokenId - the id of the token to be refreshed

Returns:

the refreshed token

Throws:

UnrecoverableTokenException - thrown if the token is invalid and can't be automatically refreshed

RecoverableTokenException - thrown if the token is invalid but it might be possible to recover

getRefreshedToken

ClientToken getRefreshedToken(String clientTokenId,
 Duration margin)
                       throws UnrecoverableTokenException,
RecoverableTokenException

Refreshes if access token is already expired or expires within the margin period. Returns the client token, saving the up to date token to the store. If the refreshed token lifetime is shorter than the margin then the refreshed token is returned. It means that in such case returned token will be valid only for part of the margin period. May update ClientTokenMetadata of the token.

Parameters:

clientTokenId - the id of the token to be refreshed if required

margin - only refreshes token if expiry is before now + margin

Returns:

the token, potentially refreshed

Throws:

UnrecoverableTokenException - thrown if the token is invalid and can't be automatically refreshed

RecoverableTokenException - thrown if the token is invalid but it might be possible to recover