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:

Version:
2025-09-05
Author:
Thomas Rørvik Skjølberg, Vladimir Dzhuvinov

  • Field Details

  • Method Details

    • 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.

    • refreshAheadCache

      public JWKSourceBuilder<C> refreshAheadCache(long refreshAheadTime, EventListener<CachingJWKSetSource<C>,C> eventListener, ExecutorService executorService, boolean shutdownExecutorOnClose, ScheduledExecutorService scheduledExecutorService, boolean shutdownScheduledExecutorOnClose)
      Enables refresh-ahead caching of the JWK set.
      Parameters:
      refreshAheadTime - The refresh ahead time, in milliseconds.
      eventListener - The event listener, null if not specified.
      executorService - The executor service to use for the cache refresh.
      shutdownExecutorOnClose - If true the executor service will be shut down upon closing the source.
      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.
      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.