Package org.opensaml.saml.metadata.resolver.impl

# Class FileBackedHTTPMetadataResolver

java.lang.Object
net.shibboleth.shared.component.AbstractInitializableComponent
net.shibboleth.shared.component.AbstractIdentifiedInitializableComponent
net.shibboleth.shared.component.AbstractIdentifiableInitializableComponent
org.opensaml.saml.metadata.resolver.impl.AbstractMetadataResolver
org.opensaml.saml.metadata.resolver.impl.AbstractBatchMetadataResolver
org.opensaml.saml.metadata.resolver.impl.AbstractReloadingMetadataResolver
org.opensaml.saml.metadata.resolver.impl.HTTPMetadataResolver
org.opensaml.saml.metadata.resolver.impl.FileBackedHTTPMetadataResolver

All Implemented Interfaces:
  `Iterable<EntityDescriptor>`, `Component`, `DestructableComponent`, `IdentifiableComponent`, `IdentifiedComponent`, `InitializableComponent`, `Resolver<EntityDescriptor,CriteriaSet>`, `IterableMetadataSource`, `BatchMetadataResolver`, `MetadataResolver`, `RefreshableMetadataResolver`, `RemoteMetadataResolver`

public class FileBackedHTTPMetadataResolver extends HTTPMetadataResolver
An HTTP metadata provider that caches a copy of the retrieved metadata to disk so that, in the event that the metadata may not be pulled from the URL, it may be pulled from disk using the most recently fetched data.

If the backup file does not already exist, it will be created by saving the byte[] retrieved in the HTTP fetch.

If `isInitializeFromBackupFile()` is true, then initialization will attempt to load metadata first from the backup file on disk, if it exists. If successful then the next refresh after initialization, which will attempt the full HTTP fetch, will be scheduled for the interval indicated by `getBackupFileInitNextRefreshDelay()`. This can help prevent large metadata batches from slowing down the synchronous resolver start up process, deferring the more expensive HTTP fetch operation to the asynchronous background refresh thread.

## Nested Class Summary

## Nested classes/interfaces inherited from class org.opensaml.saml.metadata.resolver.impl.AbstractBatchMetadataResolver

`AbstractBatchMetadataResolver.BatchEntityBackingStore`

## Nested classes/interfaces inherited from class org.opensaml.saml.metadata.resolver.impl.AbstractMetadataResolver

`AbstractMetadataResolver.EntityBackingStore`

## Field Summary

Fields
Modifier and Type
Field
Description
`private Duration`
`backupFileInitNextRefreshDelay`
Duration after which to schedule next refresh, when initialized from backup file.
`private boolean`
`initializedFromBackupFile`
Flag indicating whether metadata load during init was from backup file.
`private boolean`
`initializeFromBackupFile`
Flag indicating whether initialization should first attempt to load metadata from backup file.
`private boolean`
`initializing`
Flag used to track state of whether currently initializing or not.
`private final org.slf4j.Logger`
`log`
Class logger.
`private File`
`metadataBackupFile`
File containing the backup of the metadata.

### Fields inherited from class org.opensaml.saml.metadata.resolver.impl.AbstractReloadingMetadataResolver

`METRIC_TIMER_REFRESH`

## Constructor Summary

Constructors
Constructor
Description
`FileBackedHTTPMetadataResolver(Timer backgroundTaskTimer, org.apache.hc.client5.http.classic.HttpClient client, String metadataURL, String backupFilePath)`
Constructor.
`FileBackedHTTPMetadataResolver(org.apache.hc.client5.http.classic.HttpClient client, String metadataURL, String backupFilePath)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`protected 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.
`protected void`
`doDestroy()`
`protected byte[]`
`fetchMetadata()`
Gets the metadata document from the remote server.
`Duration`
`getBackupFileInitNextRefreshDelay()`
Get the duration after which to schedule next refresh, when initialized from backup file.
`protected void`
`initMetadataResolver()`
Subclasses should override this method to perform any initialization logic necessary.
`boolean`
`isInitializedFromBackupFile()`
Get the flag indicating whether metadata load during initialization was from backup file.
`boolean`
`isInitializeFromBackupFile()`
Get the flag indicating whether initialization should first attempt to load metadata from backup file, if it exists.
`protected MetadataFilterContext`
`newFilterContext()`
Get a new instance of `MetadataFilterContext` to be used when filtering metadata.
`protected void`
`postProcessMetadata(byte[] metadataBytes, Document metadataDom, XMLObject originalMetadata, XMLObject filteredMetadata)`
Post-processing hook called after new metadata has been unmarshalled, filtered, and the DOM released (from the `XMLObject`) but before the metadata is saved off.
`protected void`
`setBackupFile(String backupFilePath)`
Sets the file used to backup metadata.
`void`
`setBackupFileInitNextRefreshDelay(Duration delay)`
Set the duration after which to schedule next refresh, when initialized from backup file.
`void`
`setInitializeFromBackupFile(boolean flag)`
Set the flag indicating whether initialization should first attempt to load metadata from backup file, if it exists.
`protected void`
`validateBackupFile(File backupFile)`
Validate the basic properties of the specified metadata backup file, for example that it exists and/or can be created; that it is not a directory; and that it is readable and writable.

### Methods inherited from class org.opensaml.saml.metadata.resolver.impl.HTTPMetadataResolver

`buildHttpClientContext, buildHttpGet, getHttpClientSecurityParameters, getMetadataBytesFromResponse, getMetadataIdentifier, getMetadataURI, processConditionalRetrievalHeaders, setHttpClientSecurityParameters`

### Methods inherited from class org.opensaml.saml.metadata.resolver.impl.AbstractReloadingMetadataResolver

`getExpirationTime, getExpirationWarningThreshold, getLastFailureCause, getLastRefresh, getLastSuccessfulRefresh, getLastUpdate, getMaxRefreshDelay, getMinRefreshDelay, getNextRefresh, getRefreshDelayFactor, inputstreamToByteArray, processCachedMetadata, processNewMetadata, processNonExpiredMetadata, processPreExpiredMetadata, refresh, setCacheSourceMetadata, setExpirationWarningThreshold, setMaxRefreshDelay, setMinRefreshDelay, setRefreshDelayFactor, unmarshallMetadata, wasLastRefreshSuccess`

### Methods inherited from class org.opensaml.saml.metadata.resolver.impl.AbstractBatchMetadataResolver

`createNewBackingStore, doResolve, ensureBackingStore, getCachedFilteredMetadata, getCachedOriginalMetadata, getIndexes, getRootValidUntil, indexEntityDescriptor, isCacheSourceMetadata, isResolveViaPredicatesOnly, isRootValid, iterator, lookupByIndexes, preProcessNewMetadata, setIndexes, setResolveViaPredicatesOnly`

### Methods inherited from class org.opensaml.saml.metadata.resolver.impl.AbstractMetadataResolver

`doInitialize, filterMetadata, getActivationCondition, getBackingStore, getCriterionPredicateRegistry, getLogPrefix, getMetadataFilter, getMetricsBaseName, getParserPool, getType, getUnmarshallerFactory, isFailFastInitialization, isRequireValidMetadata, isSatisfyAnyPredicates, isUseDefaultPredicateRegistry, isValid, lookupEntityID, lookupIndexedEntityID, predicateFilterCandidates, preProcessEntitiesDescriptor, preProcessEntityDescriptor, releaseMetadataDOM, removeByEntityID, resolve, resolveSingle, setActivationCondition, setBackingStore, setCriterionPredicateRegistry, setFailFastInitialization, setMetadataFilter, setMetricsBaseName, setParserPool, setRequireValidMetadata, setSatisfyAnyPredicates, setType, setUseDefaultPredicateRegistry, unmarshallMetadata`

### Methods inherited from class net.shibboleth.shared.component.AbstractIdentifiableInitializableComponent

`setId`

### Methods inherited from class net.shibboleth.shared.component.AbstractIdentifiedInitializableComponent

`ensureId, getId, ifDestroyedThrowDestroyedComponentException, ifInitializedThrowUnmodifiabledComponentException, ifNotInitializedThrowUninitializedComponentException`

### Methods inherited from class net.shibboleth.shared.component.AbstractInitializableComponent

`checkComponentActive, checkSetterPreconditions, destroy, initialize, isDestroyed, isInitialized`

### Methods inherited from class java.lang.Object

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

### Methods inherited from interface net.shibboleth.shared.component.IdentifiedComponent

`getId`

### Methods inherited from interface java.lang.Iterable

`forEach, spliterator`

### Methods inherited from interface org.opensaml.saml.metadata.resolver.MetadataResolver

`getMetadataFilter, getType, isRequireValidMetadata, setMetadataFilter, setRequireValidMetadata`

### Methods inherited from interface net.shibboleth.shared.resolver.Resolver

`resolve, resolveSingle`

## Field Details

### log

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

### metadataBackupFile

@NonnullAfterInit private File metadataBackupFile
File containing the backup of the metadata.

### initializing

private boolean initializing
Flag used to track state of whether currently initializing or not.

### initializeFromBackupFile

private boolean initializeFromBackupFile
Flag indicating whether initialization should first attempt to load metadata from backup file.

### initializedFromBackupFile

private boolean initializedFromBackupFile
Flag indicating whether metadata load during init was from backup file.

### backupFileInitNextRefreshDelay

@Nonnull private Duration backupFileInitNextRefreshDelay
Duration after which to schedule next refresh, when initialized from backup file.

## Constructor Details

### FileBackedHTTPMetadataResolver

public FileBackedHTTPMetadataResolver(@Nonnull org.apache.hc.client5.http.classic.HttpClient client, @Nonnull String metadataURL, @Nonnull String backupFilePath) throws ResolverException
Constructor.

Parameters:
  `client` - HTTP client used to fetch remote metadata
  `metadataURL` - the URL to fetch the metadata
  `backupFilePath` - the file that will keep a backup copy of the metadata,
Throws:
  `ResolverException` - thrown if the URL is not a valid URL, the metadata can not be retrieved from the URL

### FileBackedHTTPMetadataResolver

public FileBackedHTTPMetadataResolver(@Nullable Timer backgroundTaskTimer, @Nonnull org.apache.hc.client5.http.classic.HttpClient client, @Nonnull String metadataURL, @Nonnull String backupFilePath) throws ResolverException
Constructor.

Parameters:
  `client` - HTTP client used to fetch remote metadata
  `backgroundTaskTimer` - timer used to schedule background metadata refresh tasks
  `metadataURL` - the URL to fetch the metadata
  `backupFilePath` - the file that will keep a backup copy of the metadata,
Throws:
  `ResolverException` - thrown if the URL is not a valid URL, the metadata can not be retrieved from the URL

## Method Details

### isInitializedFromBackupFile

public boolean isInitializedFromBackupFile()
Get the flag indicating whether metadata load during initialization was from backup file.

Returns:
  true if initial load was from backup file, false otherwise

### isInitializeFromBackupFile

public boolean isInitializeFromBackupFile()
Get the flag indicating whether initialization should first attempt to load metadata from backup file, if it exists.

Defaults to: true.

Returns:
  true if should initialize from backup file, false otherwise

### setInitializeFromBackupFile

public void setInitializeFromBackupFile(boolean flag)
Set the flag indicating whether initialization should first attempt to load metadata from backup file, if it exists.

Defaults to: true.

Parameters:
  `flag` - true if should initialize from backup file, false otherwise

### getBackupFileInitNextRefreshDelay

@Nonnull public Duration getBackupFileInitNextRefreshDelay()
Get the duration after which to schedule next refresh, when initialized from backup file.

Defaults to 5s.

Returns:
  the duration

### setBackupFileInitNextRefreshDelay

public void setBackupFileInitNextRefreshDelay(@Nonnull Duration delay)
Set the duration after which to schedule next refresh, when initialized from backup file.

Defaults to 5s.

Parameters:
  `delay` - the next refresh delay

### doDestroy

protected void doDestroy()

Overrides:
  `doDestroy` in class `HTTPMetadataResolver`

### initMetadataResolver

protected void initMetadataResolver() throws ComponentInitializationException
Subclasses should override this method to perform any initialization logic necessary. Default implementation is a no-op.

Overrides:
  `initMetadataResolver` in class `AbstractReloadingMetadataResolver`
Throws:
  `ComponentInitializationException` - thrown if there is a problem initializing the provider

### setBackupFile

protected void setBackupFile(@Nonnull String backupFilePath) throws ResolverException
Sets the file used to backup metadata. The given file path is checked to see if it is a read/writable file if it exists or if can be created if it does not exist.

Parameters:
  `backupFilePath` - path to the backup file
Throws:
  `ResolverException` - thrown if the backup file is not read/writable or creatable

### validateBackupFile

protected void validateBackupFile(@Nonnull File backupFile) throws ResolverException
Validate the basic properties of the specified metadata backup file, for example that it exists and/or can be created; that it is not a directory; and that it is readable and writable.

Parameters:
  `backupFile` - the file to evaluate
Throws:
  `ResolverException` - if file does not pass basic properties required of a metadata backup file

### fetchMetadata

@Nullable protected byte[] fetchMetadata() throws ResolverException
Gets the metadata document from the remote server.

Overrides:
  `fetchMetadata` in class `HTTPMetadataResolver`
Returns:
  the metadata from remote server, or null if the metadata document has not changed since the last retrieval
Throws:
  `ResolverException` - thrown if there is a problem retrieving the metadata from the remote server

### newFilterContext

@Nonnull protected MetadataFilterContext newFilterContext()
Get a new instance of `MetadataFilterContext` to be used when filtering metadata.

This default implementation will just return an empty context. Subclasses would override to add contextual info specific to the implementation.

Overrides:
  `newFilterContext` in class `AbstractMetadataResolver`
Returns:
  the new filter context instance

### computeNextRefreshDelay

@Nonnull protected Duration computeNextRefreshDelay(@Nullable Instant expectedExpiration)
Computes the delay until the next refresh time based on the current metadata's expiration time and the refresh interval floor.

Overrides:
  `computeNextRefreshDelay` in class `AbstractReloadingMetadataResolver`
Parameters:
  `expectedExpiration` - the time when the metadata is expected to expire and need refreshing
Returns:
  delay until the next refresh time

### postProcessMetadata

protected void postProcessMetadata(@Nonnull byte[] metadataBytes, @Nonnull Document metadataDom, @Nonnull XMLObject originalMetadata, @Nullable XMLObject filteredMetadata) throws ResolverException
Post-processing hook called after new metadata has been unmarshalled, filtered, and the DOM released (from the `XMLObject`) but before the metadata is saved off. Any exception thrown by this hook will cause the retrieved metadata to be discarded. The default implementation of this method is a no-op

Overrides:
  `postProcessMetadata` in class `AbstractReloadingMetadataResolver`
Parameters:
  `metadataBytes` - original raw metadata bytes retrieved via `AbstractReloadingMetadataResolver.fetchMetadata()`
  `metadataDom` - original metadata after it has been parsed in to a DOM document
  `originalMetadata` - original metadata prior to being filtered, with its DOM released
  `filteredMetadata` - metadata after it has been run through all registered filters and its DOM released
Throws:
  `ResolverException` - thrown if there is a problem with the provided data