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