Package org.opensaml.storage

Class AbstractStorageService

java.lang.Object

net.shibboleth.shared.component.AbstractInitializableComponent

net.shibboleth.shared.component.AbstractIdentifiedInitializableComponent

net.shibboleth.shared.component.AbstractIdentifiableInitializableComponent

org.opensaml.storage.AbstractStorageService

All Implemented Interfaces:

Component, DestructableComponent, IdentifiableComponent, IdentifiedComponent, InitializableComponent, StorageCapabilities, StorageService

Direct Known Subclasses:

AbstractMapBackedStorageService

public abstract class AbstractStorageService
extends AbstractIdentifiableInitializableComponent
implements StorageService, StorageCapabilities

Abstract base class for StorageService implementations.

The base class handles support for a background cleanup task, and handles calling of custom object serializers.

Field Summary

Fields

Modifier and Type	Field	Description
private Duration	cleanupInterval	Time between cleanup checks.
private TimerTask	cleanupTask	Task that cleans up expired records.
private Timer	cleanupTaskTimer	Timer used to schedule cleanup tasks.
private int	contextSize	Configurable context size limit.
private Timer	internalTaskTimer	Timer used to schedule cleanup tasks if no external one set.
private int	keySize	Configurable key size limit.
private int	valueSize	Configurable value size limit.

Constructor Summary

Constructors

Constructor	Description
AbstractStorageService()	Constructor.

Method Summary

Modifier and Type	Method	Description
boolean	create(Object value)	Creates a new record in the store using an annotated object as the source.
<T> boolean	create(String context, String key, T value, StorageSerializer<T> serializer, Long expiration)	Creates a new record in the store with an expiration, using a custom serialization process for an arbitrary object.
boolean	delete(Object value)	Deletes an existing record from the store, using an annotated object as the source.
boolean	deleteWithVersion(long version, Object value)	Deletes an existing record from the store, using an annotated object as the source, if it currently has a specified version.
protected void	doDestroy()
protected void	doInitialize()
StorageCapabilities	getCapabilities()	Returns the capabilities of the underlying store.
Duration	getCleanupInterval()	Gets the time between one cleanup and another.
protected TimerTask	getCleanupTask()	Returns a cleanup task function to schedule for background cleanup.
Timer	getCleanupTaskTimer()	Gets the timer used to schedule cleanup tasks.
int	getContextSize()	Gets max size of context labels in characters.
int	getKeySize()	Gets max size of keys in characters.
long	getValueSize()	Gets max size of values in characters.
Object	read(Object value)	Returns an existing record from the store, if one exists, and uses it to update the annotated fields of a target object.
void	setCleanupInterval(Duration interval)	Sets the time between one cleanup and another.
void	setCleanupTaskTimer(Timer timer)	Sets the timer used to schedule cleanup tasks.
void	setContextSize(int size)	Set the context size limit.
void	setKeySize(int size)	Set the key size limit.
void	setValueSize(int size)	Set the value size limit.
boolean	update(Object value)	Updates an existing record in the store, using an annotated object as the source.
<T> boolean	update(String context, String key, T value, StorageSerializer<T> serializer, Long expiration)	Updates an existing record in the store using a custom serialization strategy.
boolean	updateExpiration(Object value)	Updates expiration of an existing record in the store, using an annotated object as the source.
Long	updateWithVersion(long version, Object value)	Updates an existing record in the store, if a version matches, using an annotated object as the source.
<T> Long	updateWithVersion(long version, String context, String key, T value, StorageSerializer<T> serializer, Long expiration)	Updates an existing record in the store, if a version matches, using a custom serialization strategy.

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 org.opensaml.storage.StorageCapabilities

isClustered, isServerSide

Methods inherited from interface org.opensaml.storage.StorageService

create, delete, deleteContext, deleteWithVersion, read, read, reap, update, updateContextExpiration, updateExpiration, updateWithVersion

Field Details

cleanupInterval

@Nonnull
private Duration cleanupInterval

Time between cleanup checks. Default value: (0)

cleanupTaskTimer

@Nullable
private Timer cleanupTaskTimer

Timer used to schedule cleanup tasks.

internalTaskTimer

@Nullable
private Timer internalTaskTimer

Timer used to schedule cleanup tasks if no external one set.

cleanupTask

@Nullable
private TimerTask cleanupTask

Task that cleans up expired records.

contextSize

@Positive
private int contextSize

Configurable context size limit.

keySize

@Positive
private int keySize

Configurable key size limit.

valueSize

@Positive
private int valueSize

Configurable value size limit.

Constructor Details

AbstractStorageService

public AbstractStorageService()

Constructor.

Method Details

getCleanupInterval

@Nonnull
public Duration getCleanupInterval()

Gets the time between one cleanup and another. A value of 0 indicates that no cleanup will be performed.

Returns:

time between one cleanup and another

setCleanupInterval

public void setCleanupInterval(@Nonnull
 Duration interval)

Sets the time between one cleanup and another. A value of 0 indicates that no cleanup will be performed. This setting cannot be changed after the service has been initialized.

Parameters:

interval - time between one cleanup and another

getCleanupTaskTimer

@Nullable
public Timer getCleanupTaskTimer()

Gets the timer used to schedule cleanup tasks.

Returns:

timer used to schedule cleanup tasks

setCleanupTaskTimer

public void setCleanupTaskTimer(@Nullable
 Timer timer)

Sets the timer used to schedule cleanup tasks. This setting can not be changed after the service has been initialized.

Parameters:

timer - timer used to schedule configuration reload tasks

getCleanupTask

@Nullable
protected TimerTask getCleanupTask()

Returns a cleanup task function to schedule for background cleanup.

The default implementation does not supply one.

Returns:

a task object, or null

setContextSize

public void setContextSize(@Positive
 int size)

Set the context size limit.

Parameters:

size - limit on context size in characters

setKeySize

public void setKeySize(@Positive
 int size)

Set the key size limit.

Parameters:

size - size limit on key size in characters

setValueSize

public void setValueSize(@Positive
 int size)

Set the value size limit.

Parameters:

size - size limit on value size in characters

doInitialize

protected void doInitialize()
                     throws ComponentInitializationException

Overrides:

doInitialize in class AbstractIdentifiedInitializableComponent

Throws:

ComponentInitializationException

doDestroy

protected void doDestroy()

Overrides:

doDestroy in class AbstractInitializableComponent

getCapabilities

@Nonnull
public StorageCapabilities getCapabilities()

Returns the capabilities of the underlying store.

Specified by:

getCapabilities in interface StorageService

Returns:

interface to access the service's capabilities

getContextSize

public int getContextSize()

Gets max size of context labels in characters.

Specified by:

getContextSize in interface StorageCapabilities

Returns:

max size of context labels in characters

getKeySize

public int getKeySize()

Gets max size of keys in characters.

Specified by:

getKeySize in interface StorageCapabilities

Returns:

max size of keys in characters

getValueSize

public long getValueSize()

Gets max size of values in characters.

Specified by:

getValueSize in interface StorageCapabilities

Returns:

max size of values in characters

create

public <T> boolean create(@Nonnull @NotEmpty
 String context,
 @Nonnull @NotEmpty
 String key,
 @Nonnull
 T value,
 @Nonnull
 StorageSerializer<T> serializer,
 @Nullable @Positive
 Long expiration)
                   throws IOException

Creates a new record in the store with an expiration, using a custom serialization process for an arbitrary object.

Specified by:

create in interface StorageService

Type Parameters:

T - type of record

Parameters:

context - a storage context label

key - a key unique to context

value - object to store

serializer - custom serializer for the object

expiration - expiration for record, or null

Returns:

true iff record was inserted, false iff a duplicate was found

Throws:

IOException - if fatal errors occur in the insertion process

create

public boolean create(@Nonnull
 Object value)
               throws IOException

Creates a new record in the store using an annotated object as the source.

The individual parameters for the creation are extracted from the object using the annotations in the org.opensaml.storage.annotation package. If any are missing, or a field inaccessible, a runtime exception of some kind will occur.

Specified by:

create in interface StorageService

Parameters:

value - object to store

Returns:

true iff record was inserted, false iff a duplicate was found

Throws:

IOException - if fatal errors occur in the insertion process

read

@Nullable
public Object read(@Nonnull
 Object value)
            throws IOException

Returns an existing record from the store, if one exists, and uses it to update the annotated fields of a target object.

The context and key to look up are obtained from the target object, and the value and expiration are written back, using the annotations in the org.opensaml.storage.annotation package. If any are missing, or a field inaccessible, a runtime exception of some kind will occur.

Specified by:

read in interface StorageService

Parameters:

value - object to look up and populate

Returns:

the updated object passed into the method, or null if no record was found

Throws:

IOException - if errors occur in the read process

update

public <T> boolean update(@Nonnull @NotEmpty
 String context,
 @Nonnull @NotEmpty
 String key,
 @Nonnull
 T value,
 @Nonnull
 StorageSerializer<T> serializer,
 @Nullable @Positive
 Long expiration)
                   throws IOException

Updates an existing record in the store using a custom serialization strategy.

Specified by:

update in interface StorageService

Type Parameters:

T - type of record

Parameters:

context - a storage context label

key - a key unique to context

value - updated value

serializer - custom serializer

expiration - expiration for record, or null

Returns:

true if the update succeeded, false if the record does not exist

Throws:

IOException - if errors occur in the update process

updateWithVersion

@Nullable
public <T> Long updateWithVersion(@Positive
 long version,
 @Nonnull @NotEmpty
 String context,
 @Nonnull @NotEmpty
 String key,
 @Nonnull
 T value,
 @Nonnull
 StorageSerializer<T> serializer,
 @Nullable @Positive
 Long expiration)
                           throws IOException,
VersionMismatchException

Updates an existing record in the store, if a version matches, using a custom serialization strategy.

Specified by:

updateWithVersion in interface StorageService

Type Parameters:

T - type of record

Parameters:

version - only update if the current version matches this value

context - a storage context label

key - a key unique to context

value - updated value

serializer - custom serializer

expiration - expiration for record, or null

Returns:

the version of the record after update, null if no record exists

Throws:

IOException - if errors occur in the update process

VersionMismatchException - if the record has already been updated to a newer version

update

public boolean update(@Nonnull
 Object value)
               throws IOException

Updates an existing record in the store, using an annotated object as the source.

The individual parameters for the update are extracted from the object using the annotations in the org.opensaml.storage.annotation package. If any are missing, or a field inaccessible, a runtime exception of some kind will occur.

Specified by:

update in interface StorageService

Parameters:

value - object to update from

Returns:

true if the update succeeded, false if the record does not exist

Throws:

IOException - if errors occur in the update process

updateWithVersion

@Nullable
public Long updateWithVersion(@Positive
 long version,
 @Nonnull
 Object value)
                       throws IOException,
VersionMismatchException

Updates an existing record in the store, if a version matches, using an annotated object as the source.

The individual parameters for the update are extracted from the object using the annotations in the org.opensaml.storage.annotation package. If any are missing, or a field inaccessible, a runtime exception of some kind will occur.

Specified by:

updateWithVersion in interface StorageService

Parameters:

version - only update if the current version matches this value

value - object to update from

Returns:

the version of the record after update, null if no record exists

Throws:

IOException - if errors occur in the update process

VersionMismatchException - if the record has already been updated to a newer version

updateExpiration

public boolean updateExpiration(@Nonnull
 Object value)
                         throws IOException

Updates expiration of an existing record in the store, using an annotated object as the source.

The individual parameters for the update are extracted from the object using the annotations in the org.opensaml.storage.annotation package. If any are missing, or a field inaccessible, a runtime exception of some kind will occur.

Specified by:

updateExpiration in interface StorageService

Parameters:

value - object to update from

Returns:

true if the update succeeded, false if the record does not exist

Throws:

IOException - if errors occur in the update process

delete

public boolean delete(@Nonnull
 Object value)
               throws IOException

Deletes an existing record from the store, using an annotated object as the source.

The individual parameters for the deletion are extracted from the object using the annotations in the org.opensaml.storage.annotation package. If any are missing, or a field inaccessible, a runtime exception of some kind will occur.

Specified by:

delete in interface StorageService

Parameters:

value - object to delete

Returns:

true iff the record existed and was deleted

Throws:

IOException - if errors occur in the deletion process

deleteWithVersion

public boolean deleteWithVersion(@Positive
 long version,
 @Nonnull
 Object value)
                          throws IOException,
VersionMismatchException

Deletes an existing record from the store, using an annotated object as the source, if it currently has a specified version.

The individual parameters for the deletion are extracted from the object using the annotations in the org.opensaml.storage.annotation package. If any are missing, or a field inaccessible, a runtime exception of some kind will occur.

Specified by:

deleteWithVersion in interface StorageService

Parameters:

version - record version to delete

value - object to delete

Returns:

true iff the record existed and was deleted

Throws:

IOException - if errors occur in the deletion process

VersionMismatchException - if the record has already been updated to a newer version