Package com.nimbusds.jose.jwk.source

Class RefreshAheadCachingJWKSetSource<C extends SecurityContext>

java.lang.Object

com.nimbusds.jose.jwk.source.JWKSetSourceWrapper<C>

com.nimbusds.jose.jwk.source.CachingJWKSetSource<C>

com.nimbusds.jose.jwk.source.RefreshAheadCachingJWKSetSource<C>

All Implemented Interfaces:

JWKSetSource<C>, Closeable, AutoCloseable

@ThreadSafe
public class RefreshAheadCachingJWKSetSource<C extends SecurityContext>
extends CachingJWKSetSource<C>

Caching JWKSetSource that refreshes the JWK set prior to its expiration. The updates run on a separate, dedicated thread. Updates can be repeatedly scheduled, or (lazily) triggered by incoming requests for the JWK set.

This class is intended for uninterrupted operation under high-load, to avoid a potentially large number of threads blocking when the cache expires (and must be refreshed).

Version:

2025-06-24

Author:

Thomas Rørvik Skjølberg, Vladimir Dzhuvinov

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	RefreshAheadCachingJWKSetSource.RefreshNotScheduledEvent<C extends SecurityContext>	JWK set refresh not scheduled event.
static class	RefreshAheadCachingJWKSetSource.RefreshScheduledEvent<C extends SecurityContext>	New JWK set refresh scheduled event.
static class	RefreshAheadCachingJWKSetSource.ScheduledRefreshCompletedEvent<C extends SecurityContext>	Scheduled JWK set cache refresh completed event.
static class	RefreshAheadCachingJWKSetSource.ScheduledRefreshFailed<C extends SecurityContext>	Scheduled JWK refresh failed event.
static class	RefreshAheadCachingJWKSetSource.ScheduledRefreshInitiatedEvent<C extends SecurityContext>	Scheduled JWK set cache refresh initiated event.
static class	RefreshAheadCachingJWKSetSource.UnableToRefreshAheadOfExpirationEvent<C extends SecurityContext>	Unable to refresh the JWK set cache ahead of expiration event.

Nested classes/interfaces inherited from class com.nimbusds.jose.jwk.source.CachingJWKSetSource

CachingJWKSetSource.RefreshCompletedEvent<C extends SecurityContext>, CachingJWKSetSource.RefreshInitiatedEvent<C extends SecurityContext>, CachingJWKSetSource.RefreshTimedOutEvent<C extends SecurityContext>, CachingJWKSetSource.UnableToRefreshEvent<C extends SecurityContext>, CachingJWKSetSource.WaitingForRefreshEvent<C extends SecurityContext>

Constructor Summary

Constructors

Constructor	Description
RefreshAheadCachingJWKSetSource(JWKSetSource<C> source, long timeToLive, long cacheRefreshTimeout, long refreshAheadTime, boolean scheduled, EventListener<CachingJWKSetSource<C>,C> eventListener)	Creates a new refresh-ahead caching JWK set source.
RefreshAheadCachingJWKSetSource(JWKSetSource<C> source, long timeToLive, long cacheRefreshTimeout, long refreshAheadTime, boolean scheduled, ExecutorService executorService, boolean shutdownExecutorOnClose, EventListener<CachingJWKSetSource<C>,C> eventListener)	Creates a new refresh-ahead caching JWK set source with the specified executor service to run the updates in the background.
RefreshAheadCachingJWKSetSource(JWKSetSource<C> source, long timeToLive, long cacheRefreshTimeout, long refreshAheadTime, ExecutorService executorService, boolean shutdownExecutorOnClose, EventListener<CachingJWKSetSource<C>,C> eventListener, ScheduledExecutorService scheduledExecutorService, boolean shutdownScheduledExecutorOnClose)	Creates a new refresh-ahead caching JWK set source with the specified ExecutorService to run the updates in the background.

Method Summary

Modifier and Type	Method	Description
void	close()
static ExecutorService	createDefaultExecutorService()	Creates a new instance of the default ExecutorService implementation to refresh the cache.
static ScheduledExecutorService	createDefaultScheduledExecutorService()	Creates a new instance of the default ScheduledExecutorService implementation to perform scheduled cache refreshes in the background.
ExecutorService	getExecutorService()	Returns the executor service running the updates in the background.
JWKSet	getJWKSet(JWKSetCacheRefreshEvaluator refreshEvaluator, long currentTime, C context)	Gets the JWK set.
ScheduledExecutorService	getScheduledExecutorService()	Returns the scheduled executor service scheduling the updates.
long	getTimeToLive()	Returns the time to live of the cached JWK set.

Methods inherited from class com.nimbusds.jose.jwk.source.CachingJWKSetSource

getCacheRefreshTimeout

Methods inherited from class com.nimbusds.jose.jwk.source.JWKSetSourceWrapper

getSource

Methods inherited from class java.lang.Object

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

Constructor Details

RefreshAheadCachingJWKSetSource

public RefreshAheadCachingJWKSetSource(JWKSetSource<C> source,
 long timeToLive,
 long cacheRefreshTimeout,
 long refreshAheadTime,
 boolean scheduled,
 EventListener<CachingJWKSetSource<C>,C> eventListener)

Creates a new refresh-ahead caching JWK set source.

Parameters:

source - The JWK set source to decorate. Must not be null.

timeToLive - The time to live of the cached JWK set, in milliseconds.

cacheRefreshTimeout - The cache refresh timeout, in milliseconds.

refreshAheadTime - The refresh ahead time, in milliseconds.

scheduled - true to refresh in a scheduled manner, regardless of requests.

eventListener - The event listener, null if not specified.

RefreshAheadCachingJWKSetSource

public RefreshAheadCachingJWKSetSource(JWKSetSource<C> source,
 long timeToLive,
 long cacheRefreshTimeout,
 long refreshAheadTime,
 boolean scheduled,
 ExecutorService executorService,
 boolean shutdownExecutorOnClose,
 EventListener<CachingJWKSetSource<C>,C> eventListener)

Creates a new refresh-ahead caching JWK set source with the specified executor service to run the updates in the background.

Parameters:

source - The JWK set source to decorate. Must not be null.

timeToLive - The time to live of the cached JWK set, in milliseconds.

cacheRefreshTimeout - The cache refresh timeout, in milliseconds.

refreshAheadTime - The refresh ahead time, in milliseconds.

scheduled - true to refresh in a scheduled manner, regardless of requests.

executorService - The executor service to run the updates in the background.

shutdownExecutorOnClose - If true the executor service will be shut down upon closing the source.

eventListener - The event listener, null if not specified.

RefreshAheadCachingJWKSetSource

public RefreshAheadCachingJWKSetSource(JWKSetSource<C> source,
 long timeToLive,
 long cacheRefreshTimeout,
 long refreshAheadTime,
 ExecutorService executorService,
 boolean shutdownExecutorOnClose,
 EventListener<CachingJWKSetSource<C>,C> eventListener,
 ScheduledExecutorService scheduledExecutorService,
 boolean shutdownScheduledExecutorOnClose)

Creates a new refresh-ahead caching JWK set source with the specified ExecutorService to run the updates in the background. The parameters include an optional ScheduledExecutorService to schedule the updates in the background.

Note about the ScheduledExecutorService: It is assumed that a thread will be available to schedule the update of the cache when needed. If this is not the case then the updates will not be scheduled on-time. This could, in the worst-case scenario, lead to the cache being expired when getJWKSet(JWKSetCacheRefreshEvaluator, long, SecurityContext) is called.

Parameters:

source - The JWK set source to decorate. Must not be null.

timeToLive - The time to live of the cached JWK set, in milliseconds.

cacheRefreshTimeout - The cache refresh timeout, in milliseconds.

refreshAheadTime - The refresh ahead time, in milliseconds.

executorService - The executor service to run the updates in the background.

shutdownExecutorOnClose - If true the executor service will be shut down upon closing the source.

eventListener - The event listener, null if not specified.

scheduledExecutorService - The ScheduledExecutorService to schedule the updates in the background. If null no updates will be scheduled.

shutdownScheduledExecutorOnClose - If true then the ScheduledExecutorService will be shut down upon closing the source.

Method Details

createDefaultExecutorService

public static ExecutorService createDefaultExecutorService()

Creates a new instance of the default ExecutorService implementation to refresh the cache.

createDefaultScheduledExecutorService

public static ScheduledExecutorService createDefaultScheduledExecutorService()

Creates a new instance of the default ScheduledExecutorService implementation to perform scheduled cache refreshes in the background.

getJWKSet

public JWKSet getJWKSet(JWKSetCacheRefreshEvaluator refreshEvaluator,
 long currentTime,
 C context)
                 throws KeySourceException

Description copied from interface: JWKSetSource

Gets the JWK set.

Specified by:

getJWKSet in interface JWKSetSource<C extends SecurityContext>

Overrides:

getJWKSet in class CachingJWKSetSource<C extends SecurityContext>

Parameters:

refreshEvaluator - Controls whether refresh of the JWK set cache (if utilised by the source) is required.

currentTime - The current time, in milliseconds since the Unix epoch.

context - Optional context, null if not required.

Returns:

The JWK set.

Throws:

KeySourceException - If JWK set retrieval failed.

getExecutorService

public ExecutorService getExecutorService()

Returns the executor service running the updates in the background.

Returns:

The executor service.

getScheduledExecutorService

public ScheduledExecutorService getScheduledExecutorService()

Returns the scheduled executor service scheduling the updates.

Returns:

The scheduled executor service.

close

public void close()
           throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Overrides:

close in class JWKSetSourceWrapper<C extends SecurityContext>

Throws:

IOException

getTimeToLive

public long getTimeToLive()

Returns the time to live of the cached JWK set.

Returns:

The time to live, in milliseconds.