Package com.nimbusds.jose.jwk.source

Class JWKSourceBuilder<C extends SecurityContext>

java.lang.Object

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

public class JWKSourceBuilder<C extends SecurityContext>
extends Object

JWKSource builder.

Supports wrapping of a JWK set source, typically a URL, with the following capabilities:

• caching
• caching with refresh ahead
• rate limiting
• retrial
• fail-over
• health status reporting
• outage tolerance

Version:

2023-12-10

Author:

Thomas Rørvik Skjølberg, Vladimir Dzhuvinov

Field Summary

Fields

Modifier and Type	Field	Description
static long	DEFAULT_CACHE_REFRESH_TIMEOUT	The default refresh timeout of cached JWK sets, in milliseconds.
static long	DEFAULT_CACHE_TIME_TO_LIVE	The default time to live of cached JWK sets, in milliseconds.
static int	DEFAULT_HTTP_CONNECT_TIMEOUT	The default HTTP connect timeout for JWK set retrieval, in milliseconds.
static int	DEFAULT_HTTP_READ_TIMEOUT	The default HTTP read timeout for JWK set retrieval, in milliseconds.
static int	DEFAULT_HTTP_SIZE_LIMIT	The default HTTP entity size limit for JWK set retrieval, in bytes.
static long	DEFAULT_RATE_LIMIT_MIN_INTERVAL	The default rate limiting minimum allowed time interval between two JWK set retrievals, in milliseconds.
static long	DEFAULT_REFRESH_AHEAD_TIME	The default afresh-ahead time of cached JWK sets, in milliseconds.
protected JWKSource<C>	failover

Method Summary

Modifier and Type	Method	Description
JWKSource<C>	build()	Builds the final JWKSource.
JWKSourceBuilder<C>	cache(boolean enable)	Toggles caching of the JWK set.
JWKSourceBuilder<C>	cache(long timeToLive, long cacheRefreshTimeout)	Enables caching of the retrieved JWK set.
JWKSourceBuilder<C>	cache(long timeToLive, long cacheRefreshTimeout, EventListener<CachingJWKSetSource<C>,C> eventListener)	Enables caching of the retrieved JWK set.
JWKSourceBuilder<C>	cacheForever()	Enables caching of the JWK set forever (no expiration).
static <C extends SecurityContext> JWKSourceBuilder<C>	create(JWKSetSource<C> source)	Creates a new JWK source builder wrapping an existing source.
static <C extends SecurityContext> JWKSourceBuilder<C>	create(URL jwkSetURL)	Creates a new JWK source builder using the specified JWK set URL and DefaultResourceRetriever with default timeouts.
static <C extends SecurityContext> JWKSourceBuilder<C>	create(URL jwkSetURL, ResourceRetriever retriever)	Creates a new JWK source builder using the specified JWK set URL and resource retriever.
JWKSourceBuilder<C>	failover(JWKSource<C> failover)	Sets a failover JWK source.
JWKSourceBuilder<C>	healthReporting(HealthReportListener<JWKSetSourceWithHealthStatusReporting<C>,C> listener)	Sets a health report listener.
JWKSourceBuilder<C>	outageTolerant(boolean enable)	Toggles outage tolerance by serving a cached JWK set in case of outage.
JWKSourceBuilder<C>	outageTolerant(long timeToLive)	Enables outage tolerance by serving a non-expiring cached JWK set in case of outage.
JWKSourceBuilder<C>	outageTolerant(long timeToLive, EventListener<OutageTolerantJWKSetSource<C>,C> eventListener)	Enables outage tolerance by serving a non-expiring cached JWK set in case of outage.
JWKSourceBuilder<C>	outageTolerantForever()	Enables outage tolerance by serving a non-expiring cached JWK set in case of outage.
JWKSourceBuilder<C>	rateLimited(boolean enable)	Toggles rate limiting of the JWK set retrieval.
JWKSourceBuilder<C>	rateLimited(long minTimeInterval)	Enables rate limiting of the JWK set retrieval.
JWKSourceBuilder<C>	rateLimited(long minTimeInterval, EventListener<RateLimitedJWKSetSource<C>,C> eventListener)	Enables rate limiting of the JWK set retrieval.
JWKSourceBuilder<C>	refreshAheadCache(boolean enable)	Toggles refresh-ahead caching of the JWK set.
JWKSourceBuilder<C>	refreshAheadCache(long refreshAheadTime, boolean scheduled)	Enables refresh-ahead caching of the JWK set.
JWKSourceBuilder<C>	refreshAheadCache(long refreshAheadTime, boolean scheduled, EventListener<CachingJWKSetSource<C>,C> eventListener)	Enables refresh-ahead caching of the JWK set.
JWKSourceBuilder<C>	retrying(boolean enable)	Enables single retrial to retrieve the JWK set to work around transient network issues.
JWKSourceBuilder<C>	retrying(EventListener<RetryingJWKSetSource<C>,C> eventListener)	Enables single retrial to retrieve the JWK set to work around transient network issues.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_HTTP_CONNECT_TIMEOUT

public static final int DEFAULT_HTTP_CONNECT_TIMEOUT

The default HTTP connect timeout for JWK set retrieval, in milliseconds. Set to 500 milliseconds.

See Also:

Constant Field Values

DEFAULT_HTTP_READ_TIMEOUT

public static final int DEFAULT_HTTP_READ_TIMEOUT

The default HTTP read timeout for JWK set retrieval, in milliseconds. Set to 500 milliseconds.

See Also:

Constant Field Values

DEFAULT_HTTP_SIZE_LIMIT

public static final int DEFAULT_HTTP_SIZE_LIMIT

The default HTTP entity size limit for JWK set retrieval, in bytes. Set to 50 KBytes.

See Also:

Constant Field Values

DEFAULT_CACHE_TIME_TO_LIVE

public static final long DEFAULT_CACHE_TIME_TO_LIVE

The default time to live of cached JWK sets, in milliseconds. Set to 5 minutes.

See Also:

Constant Field Values

DEFAULT_CACHE_REFRESH_TIMEOUT

public static final long DEFAULT_CACHE_REFRESH_TIMEOUT

The default refresh timeout of cached JWK sets, in milliseconds. Set to 15 seconds.

See Also:

Constant Field Values

DEFAULT_REFRESH_AHEAD_TIME

public static final long DEFAULT_REFRESH_AHEAD_TIME

The default afresh-ahead time of cached JWK sets, in milliseconds. Set to 30 seconds.

See Also:

Constant Field Values

DEFAULT_RATE_LIMIT_MIN_INTERVAL

public static final long DEFAULT_RATE_LIMIT_MIN_INTERVAL

The default rate limiting minimum allowed time interval between two JWK set retrievals, in milliseconds.

See Also:

Constant Field Values

failover

protected JWKSource<C extends SecurityContext> failover

Method Detail

create

public static <C extends SecurityContext> JWKSourceBuilder<C> create(URL jwkSetURL)

Creates a new JWK source builder using the specified JWK set URL and DefaultResourceRetriever with default timeouts.

Parameters:

jwkSetURL - The JWK set URL. Must not be null.

create

public static <C extends SecurityContext> JWKSourceBuilder<C> create(URL jwkSetURL,
                                                                     ResourceRetriever retriever)

Creates a new JWK source builder using the specified JWK set URL and resource retriever.

Parameters:

jwkSetURL - The JWK set URL. Must not be null.

retriever - The resource retriever. Must not be null.

create

public static <C extends SecurityContext> JWKSourceBuilder<C> create(JWKSetSource<C> source)

Creates a new JWK source builder wrapping an existing source.

Parameters:

source - The JWK source to wrap. Must not be null.

cache

public JWKSourceBuilder<C> cache(boolean enable)

Toggles caching of the JWK set.

Parameters:

enable - true to cache the JWK set.

Returns:

This builder.

cache

public JWKSourceBuilder<C> cache(long timeToLive,
                                 long cacheRefreshTimeout)

Enables caching of the retrieved JWK set.

Parameters:

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

cacheRefreshTimeout - The cache refresh timeout, in milliseconds.

Returns:

This builder.

cache

public JWKSourceBuilder<C> cache(long timeToLive,
                                 long cacheRefreshTimeout,
                                 EventListener<CachingJWKSetSource<C>,C> eventListener)

Enables caching of the retrieved JWK set.

Parameters:

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

cacheRefreshTimeout - The cache refresh timeout, in milliseconds.

eventListener - The event listener, null if not specified.

Returns:

This builder.

cacheForever

public JWKSourceBuilder<C> cacheForever()

Enables caching of the JWK set forever (no expiration).

Returns:

This builder.

refreshAheadCache

public JWKSourceBuilder<C> refreshAheadCache(boolean enable)

Toggles refresh-ahead caching of the JWK set.

Parameters:

enable - true to enable refresh-ahead caching of the JWK set.

Returns:

This builder.

refreshAheadCache

public JWKSourceBuilder<C> refreshAheadCache(long refreshAheadTime,
                                             boolean scheduled)

Enables refresh-ahead caching of the JWK set.

Parameters:

refreshAheadTime - The refresh ahead time, in milliseconds.

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

Returns:

This builder.

refreshAheadCache

public JWKSourceBuilder<C> refreshAheadCache(long refreshAheadTime,
                                             boolean scheduled,
                                             EventListener<CachingJWKSetSource<C>,C> eventListener)

Enables refresh-ahead caching of the JWK set.

Parameters:

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.

Returns:

This builder.

rateLimited

public JWKSourceBuilder<C> rateLimited(boolean enable)

Toggles rate limiting of the JWK set retrieval.

Parameters:

enable - true to rate limit the JWK set retrieval.

Returns:

This builder.

rateLimited

public JWKSourceBuilder<C> rateLimited(long minTimeInterval)

Enables rate limiting of the JWK set retrieval.

Parameters:

minTimeInterval - The minimum allowed time interval between two JWK set retrievals, in milliseconds.

Returns:

This builder.

rateLimited

public JWKSourceBuilder<C> rateLimited(long minTimeInterval,
                                       EventListener<RateLimitedJWKSetSource<C>,C> eventListener)

Enables rate limiting of the JWK set retrieval.

Parameters:

minTimeInterval - The minimum allowed time interval between two JWK set retrievals, in milliseconds.

eventListener - The event listener, null if not specified.

Returns:

This builder.

failover

public JWKSourceBuilder<C> failover(JWKSource<C> failover)

Sets a failover JWK source.

Parameters:

failover - The failover JWK source, null if none.

Returns:

This builder.

retrying

public JWKSourceBuilder<C> retrying(boolean enable)

Enables single retrial to retrieve the JWK set to work around transient network issues.

Parameters:

enable - true to enable single retrial.

Returns:

This builder.

retrying

public JWKSourceBuilder<C> retrying(EventListener<RetryingJWKSetSource<C>,C> eventListener)

Enables single retrial to retrieve the JWK set to work around transient network issues.

Parameters:

eventListener - The event listener, null if not specified.

Returns:

This builder.

healthReporting

public JWKSourceBuilder<C> healthReporting(HealthReportListener<JWKSetSourceWithHealthStatusReporting<C>,C> listener)

Sets a health report listener.

Parameters:

listener - The health report listener, null if not specified.

Returns:

This builder.

outageTolerant

public JWKSourceBuilder<C> outageTolerant(boolean enable)

Toggles outage tolerance by serving a cached JWK set in case of outage.

Parameters:

enable - true to enable the outage cache.

Returns:

This builder.

outageTolerantForever

public JWKSourceBuilder<C> outageTolerantForever()

Enables outage tolerance by serving a non-expiring cached JWK set in case of outage.

Returns:

This builder.

outageTolerant

public JWKSourceBuilder<C> outageTolerant(long timeToLive)

Enables outage tolerance by serving a non-expiring cached JWK set in case of outage.

Parameters:

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

Returns:

This builder.

outageTolerant

public JWKSourceBuilder<C> outageTolerant(long timeToLive,
                                          EventListener<OutageTolerantJWKSetSource<C>,C> eventListener)

Enables outage tolerance by serving a non-expiring cached JWK set in case of outage.

Parameters:

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

eventListener - The event listener, null if not specified.

Returns:

This builder.

build

public JWKSource<C> build()

Builds the final JWKSource.

Returns:

The final JWKSource.