Package net.shibboleth.oidc.metadata.cache.impl

Class BatchMetadataCache<IdentifierType,MetadataType>

java.lang.Object
net.shibboleth.shared.component.AbstractInitializableComponent
net.shibboleth.shared.component.AbstractIdentifiedInitializableComponent
net.shibboleth.shared.component.AbstractIdentifiableInitializableComponent
net.shibboleth.oidc.metadata.cache.impl.AbstractMetadataCache<IdentifierType,MetadataType>
net.shibboleth.oidc.metadata.cache.impl.BatchMetadataCache<IdentifierType,MetadataType>
Type Parameters:
IdentifierType - the metadata identifier type.
MetadataType - the metadata type.
All Implemented Interfaces:
MetadataCache<MetadataType>, Component, DestructableComponent, IdentifiableComponent, IdentifiedComponent, InitializableComponent
@ThreadSafe public class BatchMetadataCache<IdentifierType,MetadataType> extends AbstractMetadataCache<IdentifierType,MetadataType>
A metadata cache implementation that supports 'refresh-ahead' semantics for batch cache updates. Does not support 'read-through' semantics if an entry does not exist in the cache.

The metadata source could either be an aggregate with more than one metadata entry, or a single source which contains a single metadata entry.

Supports the following:

  • Batch reloading of metadata from the source using the supplied loading strategy. The cache is wiped and reloaded during each successful refresh cycle.

The schedule for batch metadata reloads are based on:

  1. If no expiry is set on the metadata source, or one can not be computed, the max refresh delay is used.
  2. If metadata expiry exists but is less than the min refresh delay, use the min refresh delay.
  3. If metadata expiry exists and is greater than the min, use the metadata expiry.

Does not support:

  1. Manual metadata refresh. Reloads only occur via the scheduled task. Supporting manual refresh would require alterations to remove/cancel existing tasks.

  • Field Details

    • log

      @Nonnull private final org.slf4j.Logger log
      Class logger.

    • maxRefreshDelay

      @NonnullAfterInit @Positive private Duration maxRefreshDelay
      Refresh interval used when metadata does not contain any validUntil or cacheDuration information.

    • minRefreshDelay

      @NonnullAfterInit @Positive private Duration minRefreshDelay
      Floor, in milliseconds, for the refresh interval.

    • loadingStrategy

      @NonnullAfterInit private LoadingStrategy loadingStrategy
      The function to use to load metadata.

    • parsingStrategy

      @NonnullAfterInit private Function<byte[],List<MetadataType>> parsingStrategy
      How to parse the loaded metadata from the loadingStrategy into a usable metadatatype.

    • sourceMetadataExpiryStrategy

      @NonnullAfterInit private Function<byte[],Instant> sourceMetadataExpiryStrategy
      Determine the expiration time of the source batch loaded metadata.

    • sourceMetadataValidPredicate

      @NonnullAfterInit private Predicate<byte[]> sourceMetadataValidPredicate
      Is the raw metadata bytes from the source valid?

    • matchOnIdentifierRequired

      private boolean matchOnIdentifierRequired
      Is a match based on an identifier required? If not, all known metadata will be returned. Defaults to true - a match on identifier is required.

    • readWriteLock

      @Nonnull private final ReadWriteLock readWriteLock
      A lock to use when reading from and loading the cache.

  • Constructor Details

  • Method Details

    • doInitialize

      protected void doInitialize() throws ComponentInitializationException
      Overrides:
      doInitialize in class AbstractMetadataCache<IdentifierType,MetadataType>
      Throws:
      ComponentInitializationException

    • setSourceMetadataValidPredicate

      public void setSourceMetadataValidPredicate(@Nonnull Predicate<byte[]> predicate)
      Set the predicate which determines if the source metadata is valid or not.
      Parameters:
      predicate - the predicate.

    • getSourceMetadataValidPredicate

      @NonnullAfterInit protected Predicate<byte[]> getSourceMetadataValidPredicate()
      Get the predicate which determines if the source metadata is valid or not.
      Returns:
      the predicate.

    • setLoadingStrategy

      public void setLoadingStrategy(@Nonnull LoadingStrategy strategy)
      Set the strategy used to batch load metadata from a source.
      Parameters:
      strategy - the loading strategy.

    • getLoadingStrategy

      @NonnullAfterInit protected LoadingStrategy getLoadingStrategy()
      Get the loading strategy.
      Returns:
      the loading strategy

    • setParsingStrategy

      public void setParsingStrategy(@Nonnull Function<byte[],List<MetadataType>> strategy)
      Set the strategy used to convert raw metadata in bytes to the given metadata type.
      Parameters:
      strategy - the parsing strategy.

    • getParsingStrategy

      @NonnullAfterInit protected Function<byte[],List<MetadataType>> getParsingStrategy()
      Get the parsing strategy.
      Returns:
      the parsing strategy

    • setSourceMetadataExpiryStrategy

      public void setSourceMetadataExpiryStrategy(@Nonnull Function<byte[],Instant> strategy)
      Set a strategy to find the metadata expiry date from a source metadata document as bytes.
      Parameters:
      strategy - the strategy.

    • getSourceMetadataExpiryStrategy

      @NonnullAfterInit protected Function<byte[],Instant> getSourceMetadataExpiryStrategy()
      Get the source metadata expiry strategy.
      Returns:
      the source metadata expiry strategy

    • setMatchOnIdentifierRequired

      public void setMatchOnIdentifierRequired(boolean required)
      Set if a match on identifier is required in order to return results. If false and there are no identifiers in the criteria to match on, all cached entries will be returned.
      Parameters:
      required - does the metadata lookup need to match the given criteria.

    • isMatchOnIdentifierRequired

      protected boolean isMatchOnIdentifierRequired()
      Is a match on identifier required?
      Returns:
      true if it is, false otherwise

    • getBackingStore

      @Nonnull protected BatchBackingStore<IdentifierType,MetadataType> getBackingStore()
      Get the backing store.

      Cast the backing store to the type used by this cache type.

      Overrides:
      getBackingStore in class AbstractMetadataCache<IdentifierType,MetadataType>
      Returns:
      the backing store. Can be null.

    • setMinRefreshDelay

      public void setMinRefreshDelay(@Positive @Nonnull Duration delay)
      Sets the minimum amount of time between refreshes.
      Parameters:
      delay - minimum amount of time between refreshes

    • getMinRefreshDelay

      @NonnullAfterInit protected Duration getMinRefreshDelay()
      Get the minimum amount of time between refreshes.
      Returns:
      the minimum refresh delay

    • setMaxRefreshDelay

      public void setMaxRefreshDelay(@Positive @Nonnull Duration delay)
      Sets the maximum amount of time between refresh intervals.
      Parameters:
      delay - maximum amount of time, in milliseconds, between refresh intervals

    • getMaxRefreshDelay

      @NonnullAfterInit protected Duration getMaxRefreshDelay()
      Get the maximum amount of time between refresh intervals.
      Returns:
      the delay maximum amount of time, in milliseconds, between refresh intervals

    • get

      @Nonnull @NonnullElements public List<MetadataType> get(@Nonnull CriteriaSet criteria) throws MetadataCacheException
      Get the list of metadata matching the given identifier.

      The implementing method is required to be thread safe.

      Acquires a read lock to prevent reading while the cache is loading.

      Parameters:
      criteria - the criteria to use when getting the metadata from the cache or the source.
      Returns:
      a list of metadata matching the criteria.
      Throws:
      MetadataCacheException - on error fetching metadata.

    • createLoadingContext

      private CacheLoadingContext createLoadingContext()
      Create a cache loading context based on the last refresh and last update time of the backing store.
      Returns:
      the cache loading context

    • loadCache

      private void loadCache() throws MetadataCacheException
      Reload the entire backing-store cache using the loading strategy.

      Acquires a write lock to prevent loading while the cache is being read from.

      Throws:
      MetadataCacheException - on loading error.

    • scheduleNextRefresh

      private void scheduleNextRefresh(@Nullable Duration delay)
      Schedules the next refresh. If the given delay is 0 or null, then maxRefreshDelay is used.
      Parameters:
      delay - The delay before the next refresh.

    • computeNextRefreshDelay

      @Nonnull private Duration computeNextRefreshDelay(Instant expectedExpiration)
      Computes the delay until the next refresh time based on the current metadata's expiration time and the refresh interval floor.
      Parameters:
      expectedExpiration - the time when the metadata is expected to expire and needs refreshing
      Returns:
      delay until the next refresh time