net.oauth2.client

Interface TokenProviderJob<T extends AccessToken>

Type Parameters:

T - The AccessToken type

public interface TokenProviderJob<T extends AccessToken>

A Token Provider that continuously provides Access Token. Implementations may use the refresh capabilities of the OAuth infrastructure, if any, or re-fetch a new Access Token with each repetition.

Method Summary

Modifier and Type	Method and Description
java.time.Duration	estimatedRepetitionsDelay() Provides the real estimated delay between two token renew repetitions.
boolean	isActive() Convenience check that returns the active status of this Token Provider Job.
TokenProviderJob<T>	schedule(double delayModifier) Schedules the repeated executions by setting their delay as percentage of the Time-To-Live (TTL) of the Access Token.
ScheduledFuture<?>	start() Starts a token refresh background job after successfully fetching an AccessToken from TokenService.
void	stop(boolean graceful) Stops the asynchronous refreshing job started by this provider (if any)

Method Detail

schedule

TokenProviderJob<T> schedule(double delayModifier)

Schedules the repeated executions by setting their delay as percentage of the Time-To-Live (TTL) of the Access Token. This value is used then to calculate the estimated delay between repetitions (execution interval) of the repeating task for refreshing tokens. The token TTL is specified by its expires_in property in the temporal unit provided by #getEstimatedRepetitionsDelayTemporalUnit() (usually ChronoUnit.SECONDS). The argument must be a double value in the range (0-1] where 1 stands for 100% of the Access Token TTL.

A few notes on fine-tuning the repetitions schedule.

Providing 1 as argument to this method will initiate refresh exactly at the expected moment of expiration. However, calculating this moment cannot be entirely precise because:

1. Tokens provide TTL, but not the exact moment since when this is accounted for. Hence, it's up to the client to approximate this moment on behalf of the token service and that is always at best close to true.
2. Since there is networking involved the networking lag is a variable that can be forecasted but the precision of the forecast cannot be considered 100% reliable.

Therefore, it's a good practice to set the scheduled runs as a percentage close to 1 rather than exactly 1, e.g. 0.9.

The value precision should be calculated with respect to the actual TTL amount of the access token and considering that ultimately it will be rounded to seconds using Math.round. Here is a few examples to give you the idea.

It is quite often the case (without being normative) that the TTL of tokens is 1 hour (3600 seconds). A value of 0.9 set to the schedule will wake up the refresh routine then 6 minutes before the expire time.

Consider the case when a TTL is 1 second, which is highly unlikely, but technically possible. The execution scheduled at 0.9*TTL will be then triggered each 900 milliseconds, which is probably not what you want.

On the other extreme, consider that the TTL is one year (31536K seconds). A schedule triggering refresh each 0.9*TTL then is about 36.5 days before end of TTL, which is probably also not what you intended. You would rather use a value of higher precision, such as 0.99998, which would bring you closer to the end of TTL (~10 minutes beforehand), while leaving enough room to recover from failures and still keeping resource usage at minimum.

Parameters:

delayModifier -

start

ScheduledFuture<?> start()
                  throws IOException

Starts a token refresh background job after successfully fetching an AccessToken from TokenService. There can be only one refreshing job associated with a RefreshingTokenProvider instance. Attempts to start this token provider more than once will throw IllegalStateException.

Returns:

a ScheduledFuture for direct access to the API of the underlying refresh job scheduler service.

Throws:

IOException - if the attempt to fetch an access token to start the refresh job failed

IllegalStateException - if a job has already been started or if fetching a token did not throw an IOException but the token was null.

stop

void stop(boolean graceful)

Stops the asynchronous refreshing job started by this provider (if any)

Parameters:

graceful - false if hard shutdown is required, true otherwise.

isActive

boolean isActive()

Convenience check that returns the active status of this Token Provider Job. A job is active when it has been started successfully and is not done yet. The future returned form the start() operation can be used for the same purpose.

Returns:

the active status of this Token Provider Job

estimatedRepetitionsDelay

java.time.Duration estimatedRepetitionsDelay()

Provides the real estimated delay between two token renew repetitions. The temporal unit of measure of this value is provided by the #getEstimatedRepetitionsDelayTemporalUnit() method.

Note that invoking this method is valid only at a time when the TTL of the access tokens provisioned by the underlying OAuth infrastructure is already known, or an IllegalStateException is thrown.

Returns:

the actual estimated delay of token renew repetitions