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 and 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 and Description
<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.
ClientToken	getRefreshedToken(String clientTokenId, Duration margin) Refreshes if access token is already expired or expires within the margin period.

Method Detail

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

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