org.opensaml.saml.metadata.resolver.impl

Class AbstractReloadingMetadataResolver

java.lang.Object

net.shibboleth.utilities.java.support.component.AbstractInitializableComponent

net.shibboleth.utilities.java.support.component.AbstractIdentifiedInitializableComponent

net.shibboleth.utilities.java.support.component.AbstractIdentifiableInitializableComponent

org.opensaml.saml.metadata.resolver.impl.AbstractMetadataResolver

org.opensaml.saml.metadata.resolver.impl.AbstractBatchMetadataResolver

org.opensaml.saml.metadata.resolver.impl.AbstractReloadingMetadataResolver

All Implemented Interfaces:

Iterable<EntityDescriptor>, net.shibboleth.utilities.java.support.component.Component, net.shibboleth.utilities.java.support.component.DestructableComponent, net.shibboleth.utilities.java.support.component.IdentifiableComponent, net.shibboleth.utilities.java.support.component.IdentifiedComponent, net.shibboleth.utilities.java.support.component.InitializableComponent, net.shibboleth.utilities.java.support.resolver.Resolver<EntityDescriptor,net.shibboleth.utilities.java.support.resolver.CriteriaSet>, IterableMetadataSource, BatchMetadataResolver, ExtendedBatchMetadataResolver, ExtendedRefreshableMetadataResolver, MetadataResolver, RefreshableMetadataResolver

Direct Known Subclasses:

FilesystemMetadataResolver, HTTPMetadataResolver, ResourceBackedMetadataResolver

public abstract class AbstractReloadingMetadataResolver
extends AbstractBatchMetadataResolver
implements ExtendedRefreshableMetadataResolver

Base class for metadata providers that cache and periodically refresh their metadata. This metadata provider periodically checks to see if the read metadata file has changed. The delay between each refresh interval is calculated as follows. If no validUntil or cacheDuration is present then the getMaxRefreshDelay() value is used. Otherwise, the earliest refresh interval of the metadata file is checked by looking for the earliest of all the validUntil attributes and cacheDuration attributes. If that refresh interval is larger than the max refresh delay then getMaxRefreshDelay() is used. If that number is smaller than the min refresh delay then getMinRefreshDelay() is used. Otherwise the calculated refresh delay multiplied by getRefreshDelayFactor() is used. By using this factor, the provider will attempt to be refresh before the cache actually expires, allowing a some room for error and recovery. Assuming the factor is not exceedingly close to 1.0 and a min refresh delay that is not overly large, this refresh will likely occur a few times before the cache expires.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	AbstractReloadingMetadataResolver.RefreshMetadataTask Background task that refreshes metadata.

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 and Description
private boolean	createdOwnTaskTimer Whether we created our own task timer during object construction.
private org.joda.time.DateTime	expirationTime Time when the currently cached metadata file expires.
private long	expirationWarningThreshold Impending expiration warning threshold for metadata refresh, in milliseconds.
private org.joda.time.DateTime	lastRefresh Last time a refresh cycle occurred.
private org.joda.time.DateTime	lastSuccessfulRefresh Last time a successful refresh cycle occurred.
private org.joda.time.DateTime	lastUpdate Last time the metadata was updated.
private Logger	log Class logger.
private long	maxRefreshDelay Refresh interval used when metadata does not contain any validUntil or cacheDuration information.
private long	minRefreshDelay Floor, in milliseconds, for the refresh interval.
private org.joda.time.DateTime	nextRefresh Next time a refresh cycle will occur.
private float	refreshDelayFactor Factor used to compute when the next refresh interval will occur.
private AbstractReloadingMetadataResolver.RefreshMetadataTask	refreshMetadataTask Current task to refresh metadata.
private Timer	taskTimer Timer used to schedule background metadata update tasks.
private boolean	trackRefreshSuccess Internal flag for tracking success during the refresh operation.
private Boolean	wasLastRefreshSuccess Flag indicating whether last refresh cycle was successful.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractReloadingMetadataResolver() Constructor.
protected	AbstractReloadingMetadataResolver(Timer backgroundTaskTimer) Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected long	computeNextRefreshDelay(org.joda.time.DateTime 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 abstract byte[]	fetchMetadata() Fetches metadata from a source.
org.joda.time.DateTime	getExpirationTime() Gets the time when the currently cached metadata expires.
long	getExpirationWarningThreshold() Gets the impending expiration warning threshold used at refresh time.
org.joda.time.DateTime	getLastRefresh()
org.joda.time.DateTime	getLastSuccessfulRefresh()
org.joda.time.DateTime	getLastUpdate()
long	getMaxRefreshDelay() Gets the maximum amount of time, in milliseconds, between refresh intervals.
protected abstract String	getMetadataIdentifier() Gets an identifier which may be used to distinguish this metadata in logging statements.
long	getMinRefreshDelay() Gets the minimum amount of time, in milliseconds, between refreshes.
org.joda.time.DateTime	getNextRefresh() Gets the time when the next refresh cycle will occur.
float	getRefreshDelayFactor() Gets the delay factor used to compute the next refresh time.
protected void	initMetadataResolver() Subclasses should override this method to perform any initialization logic necessary.
protected byte[]	inputstreamToByteArray(InputStream ins) Converts an InputStream into a byte array.
private void	logCachedMetadataExpiration(org.joda.time.DateTime now) Check cached metadata for expiration or pending expiration and log appropriately.
protected void	postProcessMetadata(byte[] metadataBytes, Document metadataDom, org.opensaml.core.xml.XMLObject originalMetadata, org.opensaml.core.xml.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	processCachedMetadata(String metadataIdentifier, org.joda.time.DateTime refreshStart) Processes a cached metadata document in order to determine, and schedule, the next time it should be refreshed.
protected void	processNewMetadata(String metadataIdentifier, org.joda.time.DateTime refreshStart, byte[] metadataBytes) Process a new metadata document.
protected void	processNonExpiredMetadata(String metadataIdentifier, org.joda.time.DateTime refreshStart, byte[] metadataBytes, org.opensaml.core.xml.XMLObject metadata) Processes metadata that has been determined to be valid at the time it was fetched.
protected void	processPreExpiredMetadata(String metadataIdentifier, org.joda.time.DateTime refreshStart, byte[] metadataBytes, org.opensaml.core.xml.XMLObject metadata) Processes metadata that has been determined to be invalid (usually because it's already expired) at the time it was fetched.
void	refresh() Refreshes the metadata from its source.
protected void	setCacheSourceMetadata(boolean flag) Set whether to cache the original source metadata document.
void	setExpirationWarningThreshold(long threshold) Sets the impending expiration warning threshold used at refresh time.
void	setMaxRefreshDelay(long delay) Sets the maximum amount of time, in milliseconds, between refresh intervals.
void	setMinRefreshDelay(long delay) Sets the minimum amount of time, in milliseconds, between refreshes.
void	setRefreshDelayFactor(float factor) Sets the delay factor used to compute the next refresh time.
protected org.opensaml.core.xml.XMLObject	unmarshallMetadata(byte[] metadataBytes) Unmarshalls the given metadata bytes.
Boolean	wasLastRefreshSuccess()

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

createNewBackingStore, getBackingStore, getCachedFilteredMetadata, getCachedOriginalMetadata, getIndexes, getRootValidUntil, indexEntityDescriptor, isCacheSourceMetadata, isResolveViaPredicatesOnly, isRootValid, iterator, lookupByIndexes, preProcessNewMetadata, resolve, setIndexes, setResolveViaPredicatesOnly

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

doInitialize, filterMetadata, getCriterionPredicateRegistry, getLogPrefix, getMetadataFilter, getParserPool, getUnmarshallerFactory, isFailFastInitialization, isRequireValidMetadata, isSatisfyAnyPredicates, isUseDefaultPredicateRegistry, isValid, lookupEntityID, lookupIndexedEntityID, predicateFilterCandidates, preProcessEntitiesDescriptor, preProcessEntityDescriptor, releaseMetadataDOM, removeByEntityID, resolveSingle, setBackingStore, setCriterionPredicateRegistry, setFailFastInitialization, setMetadataFilter, setParserPool, setRequireValidMetadata, setSatisfyAnyPredicates, setUseDefaultPredicateRegistry, unmarshallMetadata

Methods inherited from class net.shibboleth.utilities.java.support.component.AbstractIdentifiableInitializableComponent

setId

Methods inherited from class net.shibboleth.utilities.java.support.component.AbstractIdentifiedInitializableComponent

getId

Methods inherited from class net.shibboleth.utilities.java.support.component.AbstractInitializableComponent

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 org.opensaml.saml.metadata.resolver.MetadataResolver

getMetadataFilter, isRequireValidMetadata, setMetadataFilter, setRequireValidMetadata

Methods inherited from interface net.shibboleth.utilities.java.support.resolver.Resolver

resolve, resolveSingle

Methods inherited from interface net.shibboleth.utilities.java.support.component.IdentifiedComponent

getId

Field Detail

log

private final Logger log

Class logger.

taskTimer

private Timer taskTimer

Timer used to schedule background metadata update tasks.

createdOwnTaskTimer

private boolean createdOwnTaskTimer

Whether we created our own task timer during object construction.

refreshMetadataTask

private AbstractReloadingMetadataResolver.RefreshMetadataTask refreshMetadataTask

Current task to refresh metadata.

refreshDelayFactor

private float refreshDelayFactor

Factor used to compute when the next refresh interval will occur. Default value: 0.75

maxRefreshDelay

@Duration
@Positive
private long maxRefreshDelay

Refresh interval used when metadata does not contain any validUntil or cacheDuration information. Default value: 14400000ms (4 hours).

minRefreshDelay

@Duration
@Positive
private long minRefreshDelay

Floor, in milliseconds, for the refresh interval. Default value: 300000ms (5 minutes).

expirationTime

private org.joda.time.DateTime expirationTime

Time when the currently cached metadata file expires.

expirationWarningThreshold

@Duration
@Positive
private long expirationWarningThreshold

Impending expiration warning threshold for metadata refresh, in milliseconds. Default value: 0ms (disabled).

lastUpdate

private org.joda.time.DateTime lastUpdate

Last time the metadata was updated.

lastRefresh

private org.joda.time.DateTime lastRefresh

Last time a refresh cycle occurred.

nextRefresh

private org.joda.time.DateTime nextRefresh

Next time a refresh cycle will occur.

lastSuccessfulRefresh

private org.joda.time.DateTime lastSuccessfulRefresh

Last time a successful refresh cycle occurred.

wasLastRefreshSuccess

private Boolean wasLastRefreshSuccess

Flag indicating whether last refresh cycle was successful.

trackRefreshSuccess

private boolean trackRefreshSuccess

Internal flag for tracking success during the refresh operation.

Constructor Detail

AbstractReloadingMetadataResolver

protected AbstractReloadingMetadataResolver()

Constructor.

AbstractReloadingMetadataResolver

protected AbstractReloadingMetadataResolver(@Nullable
                                 Timer backgroundTaskTimer)

Constructor.

Parameters:

backgroundTaskTimer - time used to schedule background refresh tasks

Method Detail

setCacheSourceMetadata

protected void setCacheSourceMetadata(boolean flag)

Set whether to cache the original source metadata document.

Overrides:

setCacheSourceMetadata in class AbstractBatchMetadataResolver

Parameters:

flag - true if source should be cached, false otherwise

getExpirationTime

public org.joda.time.DateTime getExpirationTime()

Gets the time when the currently cached metadata expires.

Returns:

time when the currently cached metadata expires, or null if no metadata is cached

getLastUpdate

@Nullable
public org.joda.time.DateTime getLastUpdate()

Specified by:

getLastUpdate in interface RefreshableMetadataResolver

getLastRefresh

@Nullable
public org.joda.time.DateTime getLastRefresh()

Specified by:

getLastRefresh in interface RefreshableMetadataResolver

getLastSuccessfulRefresh

@Nullable
public org.joda.time.DateTime getLastSuccessfulRefresh()

Specified by:

getLastSuccessfulRefresh in interface ExtendedRefreshableMetadataResolver

wasLastRefreshSuccess

@Nullable
public Boolean wasLastRefreshSuccess()

Specified by:

wasLastRefreshSuccess in interface ExtendedRefreshableMetadataResolver

getNextRefresh

public org.joda.time.DateTime getNextRefresh()

Gets the time when the next refresh cycle will occur.

Returns:

time when the next refresh cycle will occur

getExpirationWarningThreshold

@Duration
public long getExpirationWarningThreshold()

Gets the impending expiration warning threshold used at refresh time.

Returns:

threshold for logging a warning if live metadata will soon expire

setExpirationWarningThreshold

@Duration
public void setExpirationWarningThreshold(@Duration@Positive
                                          long threshold)

Sets the impending expiration warning threshold used at refresh time.

Parameters:

threshold - the threshold for logging a warning if live metadata will soon expire

getMaxRefreshDelay

@Duration
public long getMaxRefreshDelay()

Gets the maximum amount of time, in milliseconds, between refresh intervals.

Returns:

maximum amount of time between refresh intervals

setMaxRefreshDelay

@Duration
public void setMaxRefreshDelay(@Duration@Positive
                               long delay)

Sets the maximum amount of time, in milliseconds, between refresh intervals.

Parameters:

delay - maximum amount of time, in milliseconds, between refresh intervals

getRefreshDelayFactor

public float getRefreshDelayFactor()

Gets the delay factor used to compute the next refresh time.

Returns:

delay factor used to compute the next refresh time

setRefreshDelayFactor

public void setRefreshDelayFactor(float factor)

Sets the delay factor used to compute the next refresh time. The delay must be between 0.0 and 1.0, exclusive.

Parameters:

factor - delay factor used to compute the next refresh time

getMinRefreshDelay

@Duration
public long getMinRefreshDelay()

Gets the minimum amount of time, in milliseconds, between refreshes.

Returns:

minimum amount of time, in milliseconds, between refreshes

setMinRefreshDelay

@Duration
public void setMinRefreshDelay(@Duration@Positive
                               long delay)

Sets the minimum amount of time, in milliseconds, between refreshes.

Parameters:

delay - minimum amount of time, in milliseconds, between refreshes

doDestroy

protected void doDestroy()

Overrides:

doDestroy in class AbstractMetadataResolver

initMetadataResolver

protected void initMetadataResolver()
                             throws net.shibboleth.utilities.java.support.component.ComponentInitializationException

Subclasses should override this method to perform any initialization logic necessary. Default implementation is a no-op.

Overrides:

initMetadataResolver in class AbstractBatchMetadataResolver

Throws:

net.shibboleth.utilities.java.support.component.ComponentInitializationException - thrown if there is a problem initializing the provider

refresh

public void refresh()
             throws net.shibboleth.utilities.java.support.resolver.ResolverException

Refreshes the metadata from its source.

Specified by:

refresh in interface RefreshableMetadataResolver

Throws:

net.shibboleth.utilities.java.support.resolver.ResolverException - thrown is there is a problem retrieving and processing the metadata

logCachedMetadataExpiration

private void logCachedMetadataExpiration(@Nonnull
                               org.joda.time.DateTime now)

Check cached metadata for expiration or pending expiration and log appropriately.

Parameters:

now - the current date/time

getMetadataIdentifier

protected abstract String getMetadataIdentifier()

Gets an identifier which may be used to distinguish this metadata in logging statements.

Returns:

identifier which may be used to distinguish this metadata in logging statements

fetchMetadata

protected abstract byte[] fetchMetadata()
                                 throws net.shibboleth.utilities.java.support.resolver.ResolverException

Fetches metadata from a source.

Returns:

the fetched metadata, or null if the metadata is known not to have changed since the last retrieval

Throws:

net.shibboleth.utilities.java.support.resolver.ResolverException - thrown if there is a problem fetching the metadata

unmarshallMetadata

protected org.opensaml.core.xml.XMLObject unmarshallMetadata(byte[] metadataBytes)
                                                      throws net.shibboleth.utilities.java.support.resolver.ResolverException

Unmarshalls the given metadata bytes.

Parameters:

metadataBytes - raw metadata bytes

Returns:

the metadata

Throws:

net.shibboleth.utilities.java.support.resolver.ResolverException - thrown if the metadata can not be unmarshalled

processCachedMetadata

protected void processCachedMetadata(String metadataIdentifier,
                         org.joda.time.DateTime refreshStart)
                              throws net.shibboleth.utilities.java.support.resolver.ResolverException

Processes a cached metadata document in order to determine, and schedule, the next time it should be refreshed.

Parameters:

metadataIdentifier - identifier of the metadata source

refreshStart - when the current refresh cycle started

Throws:

net.shibboleth.utilities.java.support.resolver.ResolverException - throw is there is a problem process the cached metadata

processNewMetadata

protected void processNewMetadata(String metadataIdentifier,
                      org.joda.time.DateTime refreshStart,
                      byte[] metadataBytes)
                           throws net.shibboleth.utilities.java.support.resolver.ResolverException

Process a new metadata document. Processing include unmarshalling and filtering metadata, determining the next time is should be refreshed and scheduling the next refresh cycle.

Parameters:

metadataIdentifier - identifier of the metadata source

refreshStart - when the current refresh cycle started

metadataBytes - raw bytes of the new metadata document

Throws:

net.shibboleth.utilities.java.support.resolver.ResolverException - thrown if there is a problem unmarshalling or filtering the new metadata

processPreExpiredMetadata

protected void processPreExpiredMetadata(String metadataIdentifier,
                             org.joda.time.DateTime refreshStart,
                             byte[] metadataBytes,
                             org.opensaml.core.xml.XMLObject metadata)

Processes metadata that has been determined to be invalid (usually because it's already expired) at the time it was fetched. A metadata document is considered be invalid if its root element returns false when passed to the AbstractMetadataResolver.isValid(XMLObject) method.

Parameters:

metadataIdentifier - identifier of the metadata source

refreshStart - when the current refresh cycle started

metadataBytes - raw bytes of the new metadata document

metadata - new metadata document unmarshalled

processNonExpiredMetadata

protected void processNonExpiredMetadata(String metadataIdentifier,
                             org.joda.time.DateTime refreshStart,
                             byte[] metadataBytes,
                             org.opensaml.core.xml.XMLObject metadata)
                                  throws net.shibboleth.utilities.java.support.resolver.ResolverException

Processes metadata that has been determined to be valid at the time it was fetched. A metadata document is considered to be valid if its root element returns true when passed to the AbstractMetadataResolver.isValid(XMLObject) method.

Parameters:

metadataIdentifier - identifier of the metadata source

refreshStart - when the current refresh cycle started

metadataBytes - raw bytes of the new metadata document

metadata - new metadata document unmarshalled

Throws:

net.shibboleth.utilities.java.support.resolver.ResolverException - thrown if there s a problem processing the metadata

postProcessMetadata

protected void postProcessMetadata(byte[] metadataBytes,
                       Document metadataDom,
                       org.opensaml.core.xml.XMLObject originalMetadata,
                       org.opensaml.core.xml.XMLObject filteredMetadata)
                            throws net.shibboleth.utilities.java.support.resolver.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

Parameters:

metadataBytes - original raw metadata bytes retrieved via 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:

net.shibboleth.utilities.java.support.resolver.ResolverException - thrown if there is a problem with the provided data

computeNextRefreshDelay

protected long computeNextRefreshDelay(org.joda.time.DateTime 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 need refreshing

Returns:

delay, in milliseconds, until the next refresh time

inputstreamToByteArray

protected byte[] inputstreamToByteArray(InputStream ins)
                                 throws net.shibboleth.utilities.java.support.resolver.ResolverException

Converts an InputStream into a byte array.

Parameters:

ins - input stream to convert

Returns:

resultant byte array

Throws:

net.shibboleth.utilities.java.support.resolver.ResolverException - thrown if there is a problem reading the resultant byte array