org.opensaml.storage

Class AbstractStorageService

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.storage.AbstractStorageService

All Implemented Interfaces:

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, StorageCapabilities, StorageService

Direct Known Subclasses:

AbstractMapBackedStorageService, JPAStorageService, LDAPStorageService

public abstract class AbstractStorageService
extends net.shibboleth.utilities.java.support.component.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 and Description
private long	cleanupInterval Number of seconds between cleanup checks.
private java.util.TimerTask	cleanupTask Task that cleans up expired records.
private java.util.Timer	cleanupTaskTimer Timer used to schedule cleanup tasks.
private int	contextSize Configurable context size limit.
private java.util.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 and Description
AbstractStorageService()

Method Summary

Modifier and Type	Method and Description
boolean	create(java.lang.Object value) Creates a new record in the store using an annotated object as the source.
boolean	create(java.lang.String context, java.lang.String key, java.lang.Object value, StorageSerializer serializer, java.lang.Long expiration) Creates a new record in the store with an expiration, using a custom serialization process for an arbitrary object.
boolean	delete(java.lang.Object value) Deletes an existing record from the store, using an annotated object as the source.
boolean	deleteWithVersion(long version, java.lang.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.
long	getCleanupInterval() Gets the number of milliseconds between one cleanup and another.
protected java.util.TimerTask	getCleanupTask() Returns a cleanup task function to schedule for background cleanup.
java.util.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.
java.lang.Object	read(java.lang.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(long interval) Sets the number of milliseconds between one cleanup and another.
void	setCleanupTaskTimer(java.util.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(java.lang.Object value) Updates an existing record in the store, using an annotated object as the source.
boolean	update(java.lang.String context, java.lang.String key, java.lang.Object value, StorageSerializer serializer, java.lang.Long expiration) Updates an existing record in the store using a custom serialization strategy.
boolean	updateExpiration(java.lang.Object value) Updates expiration of an existing record in the store, using an annotated object as the source.
java.lang.Long	updateWithVersion(long version, java.lang.Object value) Updates an existing record in the store, if a version matches, using an annotated object as the source.
java.lang.Long	updateWithVersion(long version, java.lang.String context, java.lang.String key, java.lang.Object value, StorageSerializer serializer, java.lang.Long expiration) Updates an existing record in the store, if a version matches, using a custom serialization strategy.

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.storage.StorageService

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

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

getId

Field Detail

cleanupInterval

@Duration
 @NonNegative
private long cleanupInterval

Number of seconds between cleanup checks. Default value: (0)

cleanupTaskTimer

private java.util.Timer cleanupTaskTimer

Timer used to schedule cleanup tasks.

internalTaskTimer

private java.util.Timer internalTaskTimer

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

cleanupTask

private java.util.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 Detail

AbstractStorageService

public AbstractStorageService()

Method Detail

getCleanupInterval

@NonNegative
public long getCleanupInterval()

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

Returns:

number of milliseconds between one cleanup and another

setCleanupInterval

public void setCleanupInterval(@Duration @NonNegative
                               long interval)

Sets the number of milliseconds 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 - number of milliseconds between one cleanup and another

getCleanupTaskTimer

@Nullable
public java.util.Timer getCleanupTaskTimer()

Gets the timer used to schedule cleanup tasks.

Returns:

timer used to schedule cleanup tasks

setCleanupTaskTimer

public void setCleanupTaskTimer(@Nullable
                                java.util.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 java.util.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 net.shibboleth.utilities.java.support.component.ComponentInitializationException

Overrides:

doInitialize in class net.shibboleth.utilities.java.support.component.AbstractIdentifiedInitializableComponent

Throws:

net.shibboleth.utilities.java.support.component.ComponentInitializationException

doDestroy

protected void doDestroy()

Overrides:

doDestroy in class net.shibboleth.utilities.java.support.component.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 boolean create(@Nonnull @NotEmpty
                      java.lang.String context,
                      @Nonnull @NotEmpty
                      java.lang.String key,
                      @Nonnull
                      java.lang.Object value,
                      @Nonnull
                      StorageSerializer serializer,
                      @Nullable @Positive
                      java.lang.Long expiration)
               throws java.io.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

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:

java.io.IOException - if fatal errors occur in the insertion process

create

public boolean create(@Nonnull
                      java.lang.Object value)
               throws java.io.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:

java.io.IOException - if fatal errors occur in the insertion process

read

@Nullable
public java.lang.Object read(@Nonnull
                                       java.lang.Object value)
                                throws java.io.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:

java.io.IOException - if errors occur in the read process

update

public boolean update(@Nonnull @NotEmpty
                      java.lang.String context,
                      @Nonnull @NotEmpty
                      java.lang.String key,
                      @Nonnull
                      java.lang.Object value,
                      @Nonnull
                      StorageSerializer serializer,
                      @Nullable @Positive
                      java.lang.Long expiration)
               throws java.io.IOException

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

Specified by:

update in interface StorageService

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:

java.io.IOException - if errors occur in the update process

updateWithVersion

@Nullable
public java.lang.Long updateWithVersion(@Positive
                                                  long version,
                                                  @Nonnull @NotEmpty
                                                  java.lang.String context,
                                                  @Nonnull @NotEmpty
                                                  java.lang.String key,
                                                  @Nonnull
                                                  java.lang.Object value,
                                                  @Nonnull
                                                  StorageSerializer serializer,
                                                  @Nullable @Positive
                                                  java.lang.Long expiration)
                                           throws java.io.IOException,
                                                  VersionMismatchException

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

Specified by:

updateWithVersion in interface StorageService

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:

java.io.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
                      java.lang.Object value)
               throws java.io.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:

java.io.IOException - if errors occur in the update process

updateWithVersion

@Nullable
public java.lang.Long updateWithVersion(@Positive
                                                  long version,
                                                  @Nonnull
                                                  java.lang.Object value)
                                           throws java.io.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:

java.io.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
                                java.lang.Object value)
                         throws java.io.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:

java.io.IOException - if errors occur in the update process

delete

public boolean delete(@Nonnull
                      java.lang.Object value)
               throws java.io.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:

java.io.IOException - if errors occur in the deletion process

deleteWithVersion

public boolean deleteWithVersion(@Positive
                                 long version,
                                 @Nonnull
                                 java.lang.Object value)
                          throws java.io.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:

java.io.IOException - if errors occur in the deletion process

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