com.databricks.sdk.core.oauth

Class RefreshableTokenSource

java.lang.Object

com.databricks.sdk.core.oauth.RefreshableTokenSource

All Implemented Interfaces:

TokenSource

Direct Known Subclasses:

ClientCredentials, CliTokenSource, DatabricksOAuthTokenSource, EndpointTokenSource, SessionCredentials

public abstract class RefreshableTokenSource
extends Object
implements TokenSource

An OAuth TokenSource which can be refreshed.

This class supports both synchronous and asynchronous token refresh. When async is enabled, stale tokens will trigger a background refresh, while expired tokens will block until a new token is fetched.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	RefreshableTokenSource.TokenState Enum representing the state of the token.

Field Summary

Fields

Modifier and Type	Field and Description
protected Token	token

Constructor Summary

Constructors

Constructor and Description
RefreshableTokenSource() Constructs a new RefreshableTokenSource with no initial token.
RefreshableTokenSource(Token token) Constructor with initial token.

Method Summary

Modifier and Type	Method and Description
Token	getToken() Gets the current token, refreshing if necessary.
protected Token	getTokenAsync() Get the current token, possibly triggering an async refresh if stale.
protected Token	getTokenBlocking() Get the current token, blocking to refresh if expired.
protected RefreshableTokenSource.TokenState	getTokenState(Token t) Determine the state of the current token (fresh, stale, or expired).
protected abstract Token	refresh() Refresh the OAuth token.
protected static Token	retrieveToken(HttpClient hc, String clientId, String clientSecret, String tokenUrl, Map<String,String> params, Map<String,String> headers, AuthParameterPosition position) Helper method implementing OAuth token refresh.
RefreshableTokenSource	withAsyncRefresh(boolean enabled) Enable or disable asynchronous token refresh.
RefreshableTokenSource	withClockSupplier(ClockSupplier clockSupplier) Set the clock supplier for current time.
RefreshableTokenSource	withExpiryBuffer(Duration buffer) Set the expiry buffer.

Methods inherited from class java.lang.Object

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

Field Detail

token

protected volatile Token token

Constructor Detail

RefreshableTokenSource

public RefreshableTokenSource()

Constructs a new RefreshableTokenSource with no initial token.

RefreshableTokenSource

public RefreshableTokenSource(Token token)

Constructor with initial token.

Parameters:

token - The initial token to use.

Method Detail

withClockSupplier

public RefreshableTokenSource withClockSupplier(ClockSupplier clockSupplier)

Set the clock supplier for current time.

Experimental: This method may change or be removed in future releases.

Parameters:

clockSupplier - The clock supplier to use.

Returns:

this instance for chaining

withAsyncRefresh

public RefreshableTokenSource withAsyncRefresh(boolean enabled)

Enable or disable asynchronous token refresh.

Experimental: This method may change or be removed in future releases.

Parameters:

enabled - true to enable async refresh, false to disable

Returns:

this instance for chaining

withExpiryBuffer

public RefreshableTokenSource withExpiryBuffer(Duration buffer)

Set the expiry buffer. If the token's lifetime is less than this buffer, it is considered expired.

Experimental: This method may change or be removed in future releases.

Parameters:

buffer - the expiry buffer duration

Returns:

this instance for chaining

refresh

protected abstract Token refresh()

Refresh the OAuth token. Subclasses must implement this to define how the token is refreshed.

This method may throw an exception if the token cannot be refreshed. The specific exception type depends on the implementation.

Returns:

The newly refreshed Token.

getToken

public Token getToken()

Gets the current token, refreshing if necessary. If async refresh is enabled, may return a stale token while a refresh is in progress.

This method may throw an exception if the token cannot be refreshed, depending on the implementation of refresh().

Specified by:

getToken in interface TokenSource

Returns:

The current valid token

getTokenState

protected RefreshableTokenSource.TokenState getTokenState(Token t)

Determine the state of the current token (fresh, stale, or expired).

Returns:

The token state

getTokenBlocking

protected Token getTokenBlocking()

Get the current token, blocking to refresh if expired.

This method may throw an exception if the token cannot be refreshed, depending on the implementation of refresh().

Returns:

The current valid token

getTokenAsync

protected Token getTokenAsync()

Get the current token, possibly triggering an async refresh if stale. If the token is expired, blocks to refresh.

This method may throw an exception if the token cannot be refreshed, depending on the implementation of refresh().

Returns:

The current valid or stale token

retrieveToken

protected static Token retrieveToken(HttpClient hc,
                                     String clientId,
                                     String clientSecret,
                                     String tokenUrl,
                                     Map<String,String> params,
                                     Map<String,String> headers,
                                     AuthParameterPosition position)

Helper method implementing OAuth token refresh.

Parameters:

hc - The HTTP client to use for the request.

clientId - The client ID to authenticate with.

clientSecret - The client secret to authenticate with.

tokenUrl - The authorization URL for fetching tokens.

params - Additional request parameters.

headers - Additional headers.

position - The position of the authentication parameters in the request.

Returns:

The newly fetched Token.

Throws:

DatabricksException - if the refresh fails

IllegalArgumentException - if the OAuth response contains an error