org.opensaml.saml2.metadata.provider
Class AbstractReloadingMetadataProvider

java.lang.Object
  org.opensaml.saml2.metadata.provider.BaseMetadataProvider
      org.opensaml.saml2.metadata.provider.AbstractMetadataProvider
          org.opensaml.saml2.metadata.provider.AbstractObservableMetadataProvider
              org.opensaml.saml2.metadata.provider.AbstractReloadingMetadataProvider

All Implemented Interfaces:

MetadataProvider, ObservableMetadataProvider

Direct Known Subclasses:

FilesystemMetadataProvider, HTTPMetadataProvider, ResourceBackedMetadataProvider

public abstract class AbstractReloadingMetadataProvider
extends AbstractObservableMetadataProvider

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

private class

AbstractReloadingMetadataProvider.RefreshMetadataTask Background task that refreshes metadata.

Nested classes/interfaces inherited from interface org.opensaml.saml2.metadata.provider.ObservableMetadataProvider

ObservableMetadataProvider.Observer

Field Summary

private XMLObject	cachedMetadata Last successfully read in metadata.
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 org.joda.time.DateTime	lastRefresh Last time a refresh cycle occurred.
private org.joda.time.DateTime	lastUpdate Last time the metadata was updated.
private org.slf4j.Logger	log Class logger.
private long	maxRefreshDelay Refresh interval used when metadata does not contain any validUntil or cacheDuration information.
private int	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 AbstractReloadingMetadataProvider.RefreshMetadataTask	refresMetadataTask Current task to refresh metadata.
private Timer	taskTimer Timer used to schedule background metadata update tasks.

Fields inherited from class org.opensaml.saml2.metadata.provider.BaseMetadataProvider

unmarshallerFactory

Constructor Summary

protected	AbstractReloadingMetadataProvider() Constructor.
protected	AbstractReloadingMetadataProvider(Timer backgroundTaskTimer) Constructor.

Method Summary

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.
void	destroy() Destroys the metadata provider and frees any resources current held by it.
protected XMLObject	doGetMetadata() Gets the metadata currently held by the provider.
protected void	doInitialization() Subclasses should override this method to perform any initialization logic necessary.
protected abstract byte[]	fetchMetadata() Fetches metadata from a source.
org.joda.time.DateTime	getExpirationTime() Gets the time when the currently cached metadata expires.
org.joda.time.DateTime	getLastRefresh() Gets the time the last refresh cycle occurred.
org.joda.time.DateTime	getLastUpdate() Gets the time that the currently available metadata was last updated.
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.
int	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 byte[]	inputstreamToByteArray(InputStream ins) Converts an InputStream into a byte array.
protected void	postProcessMetadata(byte[] metadataBytes, Document metadataDom, XMLObject metadata) 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, 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, 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.
void	setMaxRefreshDelay(long delay) Sets the maximum amount of time, in milliseconds, between refresh intervals.
void	setMinRefreshDelay(int 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 XMLObject	unmarshallMetadata(byte[] metadataBytes) Unmarshalls the given metadata bytes.

Methods inherited from class org.opensaml.saml2.metadata.provider.AbstractObservableMetadataProvider

emitChangeEvent, getObservers

Methods inherited from class org.opensaml.saml2.metadata.provider.AbstractMetadataProvider

clearDescriptorIndex, doGetEntitiesDescriptor, doGetEntityDescriptor, doGetRole, doGetRole, filterMetadata, getEntitiesDescriptor, getEntitiesDescriptorByName, getEntityDescriptor, getEntityDescriptorById, getEntityDescriptorById, getMetadata, getParserPool, getRole, getRole, initialize, isFailFastInitialization, isInitialized, isValid, releaseMetadataDOM, setFailFastInitialization, setInitialized, setParserPool, unmarshallMetadata

Methods inherited from class org.opensaml.saml2.metadata.provider.BaseMetadataProvider

getMetadataFilter, requireValidMetadata, setMetadataFilter, setRequireValidMetadata

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.opensaml.saml2.metadata.provider.MetadataProvider

getEntitiesDescriptor, getEntityDescriptor, getMetadata, getMetadataFilter, getRole, getRole, requireValidMetadata, setMetadataFilter, setRequireValidMetadata

Field Detail

log

private final org.slf4j.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.

refresMetadataTask

private AbstractReloadingMetadataProvider.RefreshMetadataTask refresMetadataTask

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

private long maxRefreshDelay

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

minRefreshDelay

private int minRefreshDelay

Floor, in milliseconds, for the refresh interval. Default value: 300000ms

expirationTime

private org.joda.time.DateTime expirationTime

Time when the currently cached metadata file expires.

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.

cachedMetadata

private XMLObject cachedMetadata

Last successfully read in metadata.

Constructor Detail

AbstractReloadingMetadataProvider

protected AbstractReloadingMetadataProvider()

Constructor.

AbstractReloadingMetadataProvider

protected AbstractReloadingMetadataProvider(Timer backgroundTaskTimer)

Constructor.

Parameters:

backgroundTaskTimer - time used to schedule background refresh tasks

Method Detail

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

public org.joda.time.DateTime getLastUpdate()

Gets the time that the currently available metadata was last updated. Note, this may be different than the time retrieved by getLastRefresh() if the metadata was known not to have changed during the last refresh cycle.

Returns:

time when the currently metadata was last update, null if metadata has never successfully been read in

getLastRefresh

public org.joda.time.DateTime getLastRefresh()

Gets the time the last refresh cycle occurred.

Returns:

time the last refresh cycle occurred

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

getMaxRefreshDelay

public long getMaxRefreshDelay()

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

Returns:

maximum amount of time between refresh intervals

setMaxRefreshDelay

public void setMaxRefreshDelay(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

public int getMinRefreshDelay()

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

Returns:

minimum amount of time, in milliseconds, between refreshes

setMinRefreshDelay

public void setMinRefreshDelay(int delay)

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

Parameters:

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

destroy

public void destroy()

Destroys the metadata provider and frees any resources current held by it. Default method is a no-op.

Overrides:

destroy in class AbstractObservableMetadataProvider

doGetMetadata

protected XMLObject doGetMetadata()
                           throws MetadataProviderException

Gets the metadata currently held by the provider. This method should not check if the provider is initialized, if the metadata is valid, etc. All of this is done by the invoker of this method.

Specified by:

doGetMetadata in class AbstractMetadataProvider

Returns:

the metadata currently held by this provider or null if no metadata is available

Throws:

MetadataProviderException - thrown if there is a problem retrieving the metadata

doInitialization

protected void doInitialization()
                         throws MetadataProviderException

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

Overrides:

doInitialization in class AbstractMetadataProvider

Throws:

MetadataProviderException - thrown if there is a problem initializing the provider

refresh

public void refresh()
             throws MetadataProviderException

Refreshes the metadata from its source.

Throws:

MetadataProviderException - thrown is there is a problem retrieving and processing the metadata

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 MetadataProviderException

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:

MetadataProviderException - thrown if there is a problem fetching the metadata

unmarshallMetadata

protected XMLObject unmarshallMetadata(byte[] metadataBytes)
                                throws MetadataProviderException

Unmarshalls the given metadata bytes.

Parameters:

metadataBytes - raw metadata bytes

Returns:

the metadata

Throws:

MetadataProviderException - thrown if the metadata can not be unmarshalled

processCachedMetadata

protected void processCachedMetadata(String metadataIdentifier,
                                     org.joda.time.DateTime refreshStart)
                              throws MetadataProviderException

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:

MetadataProviderException - throw is there is a problem process the cached metadata

processNewMetadata

protected void processNewMetadata(String metadataIdentifier,
                                  org.joda.time.DateTime refreshStart,
                                  byte[] metadataBytes)
                           throws MetadataProviderException

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:

MetadataProviderException - 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,
                                         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 AbstractMetadataProvider.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,
                                         XMLObject metadata)
                                  throws MetadataProviderException

Processes metadata that has been determined to be valid at the time it was fetched. A metadata document is considered be valid if its root element returns true when passed to the AbstractMetadataProvider.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:

MetadataProviderException - thrown if there s a problem processing the metadata

postProcessMetadata

protected void postProcessMetadata(byte[] metadataBytes,
                                   Document metadataDom,
                                   XMLObject metadata)
                            throws MetadataProviderException

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 - raw metadata bytes retrieved via fetchMetadata()

metadataDom - metadata after it has been parsed in to a DOM document

metadata - metadata after it has been run through all registered filters and its DOM released

Throws:

MetadataProviderException - 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 MetadataProviderException

Converts an InputStream into a byte array.

Parameters:

ins - input stream to convert

Returns:

resultant byte array

Throws:

MetadataProviderException - thrown if there is a problem reading the resultant byte array