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

Class DynamicMetadataCache<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.DynamicMetadataCache<IdentifierType,MetadataType>
Type Parameters:
IdentifierType - the metadata identifier type.
MetadataType - the metadata type.
All Implemented Interfaces:
MetadataCache<MetadataType>, Component, DestructableComponent, IdentifiableComponent, IdentifiedComponent, InitializableComponent
public class DynamicMetadataCache<IdentifierType,MetadataType> extends AbstractMetadataCache<IdentifierType,MetadataType>
A metadata cache implementation that supports 'read-through' semantics. Does not support 'refresh-ahead' semantics for loading about to expire values asynchronously ahead of time.

Supports the following:

  • Read-write locking on individual metadata entries. Including optimistic reads.
  • Synchronous 'read-through' metadata fetching for new metadata.
  • Synchronous 'read-through' metadata fetching for stale (past refresh point) metadata.
  • A background task to remove expired and idle metadata.

This class should only be instantiated through the MetadataCacheBuilder.

  • Field Details

  • Constructor Details

  • Method Details

    • setMinCacheDuration

      public void setMinCacheDuration(@Nonnull Duration duration)
      Set the minimum cache duration for metadata.
      Parameters:
      duration - the minimum cache duration

    • setMaxCacheDuration

      public void setMaxCacheDuration(@Nonnull Duration duration)
      Set the maximum cache duration for metadata.
      Parameters:
      duration - the maximum cache duration

    • setFetchStrategy

      public void setFetchStrategy(@Nonnull Function<CriteriaSet,MetadataType> strategy)
      Set the metadata fetching strategy.
      Parameters:
      strategy - the strategy used to fetch metadata using a 'read-through' semantic.

    • setInitialCleanupTaskDelay

      public void setInitialCleanupTaskDelay(@Nonnull Duration delay)
      Set the initial cleanup task delay.
      Parameters:
      delay - The initialCleanupTaskDelay to set.

    • doDestroy

      protected void doDestroy()
      Overrides:
      doDestroy in class AbstractMetadataCache<IdentifierType,MetadataType>

    • setCleanupTaskInterval

      public void setCleanupTaskInterval(@Nonnull Duration interval)
      Set the interval at which the cleanup task should run.

      Defaults to: 30 minutes.

      Parameters:
      interval - the interval to set

    • setRemoveIdleEntityData

      public void setRemoveIdleEntityData(boolean flag)
      Set the flag indicating whether idle entity data should be removed.
      Parameters:
      flag - true if idle entity data should be removed, false otherwise

    • setMaxIdleEntityData

      public void setMaxIdleEntityData(@Nonnull Duration max)
      Set the maximum idle time for which the resolver will keep data for a given entityID, before it is removed.

      Defaults to: 8 hours.

      Parameters:
      max - the maximum entity data idle time

    • setMetadataExpirationTimeStrategy

      public void setMetadataExpirationTimeStrategy(@Nonnull Function<ExpirationTimeContext<MetadataType>,Instant> strategy)
      Set the metadata expiration time strategy.
      Parameters:
      strategy - the strategy.

    • getMetadataExpirationTimeStrategy

      @NonnullAfterInit protected Function<ExpirationTimeContext<MetadataType>,Instant> getMetadataExpirationTimeStrategy()
      Get the metadata expiration time strategy.
      Returns:
      the expiration time strategy.

    • doInitialize

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

    • initializeMetricsInstrumentation

      private void initializeMetricsInstrumentation()
      Initialize the Metrics-based instrumentation.

    • setMetricsBaseName

      public void setMetricsBaseName(@Nullable String baseName)
      Set the base name for Metrics instrumentation.
      Parameters:
      baseName - the Metrics base name

    • getBackingStore

      @Nonnull protected DynamicBackingStore<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.

    • get

      @Nonnull @NonnullElements public List<MetadataType> get(@Nonnull @NotEmpty CriteriaSet criteria) throws MetadataCacheException
      Description copied from interface: MetadataCache
      Get the list of metadata matching the given identifier.

      The implementing method is required to be thread safe.

      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.

    • fetch

      private void fetch(@Nonnull MetadataManagementData<IdentifierType> mgmtData, @Nonnull IdentifierType identifier, @Nonnull @NotEmpty CriteriaSet criteria) throws MetadataCacheException
      Fetch metadata using the supplied fetch function, then save it to the backing store.
      Parameters:
      mgmtData - the metadata management data.
      identifier - the identifier of the metadata to fetch.
      criteria - the criteria used in determining how to fetch the metadata.
      Throws:
      MetadataCacheException - on error.

    • storeNewMetadata

      private void storeNewMetadata(@Nonnull MetadataManagementData<IdentifierType> mgmtData, @Nonnull MetadataType metadata, @Nonnull IdentifierType expectedIdentifier)
      Process the new metadata as follows:
      1. Apply the metadata filtering strategy configured.
      2. Check the fetched metadata's identifier matches that expected.
      3. Write the metadata to the backing store (cache).
      4. Update the metadata's management information with new refresh information.
      Parameters:
      mgmtData - the management data.
      metadata - the new metadata to process.
      expectedIdentifier - the identifier expected on the new metadata.

    • createExpirationTimeContext

      @Nonnull protected ExpirationTimeContext<MetadataType> createExpirationTimeContext(@Nonnull MetadataType metadata, @Nonnull Instant now)
      Create an expiration time context from the given metadata, the min and max cache durations, and the instant representing 'now'.
      Parameters:
      metadata - the metadata.
      now - the instant representing now.
      Returns:
      an expiration time context.

    • computeRefreshTriggerTime

      @Nonnull private Instant computeRefreshTriggerTime(@Nullable Instant expirationTime, @Nonnull Instant nowDateTime)
      Compute the refresh trigger time.
      Parameters:
      expirationTime - the time at which the metadata effectively expires
      nowDateTime - the current date time instant
      Returns:
      the time after which refresh attempt(s) should be made

    • read

      @Nonnull @NonnullElements private List<MetadataType> read(@Nonnull MetadataManagementData<IdentifierType> mgmtData, @Nonnull IdentifierType identifier) throws MetadataCacheException
      Read metadata from the cache under the lock relating to the Identifier of the metadata to find.

      The first read attempt is optimistic and occurs without acquiring a read lock. The optimistic read is validated to ensure another thread has not acquired a write lock in the meantime. If it has, a read lock is obtained and a further read is attempted - to ensure a consistent state. This should improve efficiency given that metadata reads will out number metadata fetch/writes.

      Parameters:
      mgmtData - the metadata management data.
      identifier - the metadata identifier to use as a key to fetch.
      Returns:
      a list of metadata that matches the given key, an empty list of none are found.
      Throws:
      MetadataCacheException - on error.