Package org.opensaml.storage

# Class AbstractMapBackedStorageService

java.lang.Object
net.shibboleth.shared.component.AbstractInitializableComponent
net.shibboleth.shared.component.AbstractIdentifiedInitializableComponent
net.shibboleth.shared.component.AbstractIdentifiableInitializableComponent
org.opensaml.storage.AbstractStorageService
org.opensaml.storage.AbstractMapBackedStorageService

All Implemented Interfaces:
  `Component`, `DestructableComponent`, `IdentifiableComponent`, `IdentifiedComponent`, `InitializableComponent`, `EnumeratableStorageService`, `StorageCapabilities`, `StorageService`

Direct Known Subclasses:
  `ClientStorageService`, `MemoryStorageService`

public abstract class AbstractMapBackedStorageService extends AbstractStorageService implements EnumeratableStorageService
Partial implementation of `StorageService` that stores data in-memory with no persistence using a simple map.

Abstract methods supply the map of data to manipulate and the lock to use, which allows optimizations in cases where locking isn't required or data isn't shared.

## Field Summary

Fields
Modifier and Type
Field
Description
`private final org.slf4j.Logger`
`log`
Class logger.

## Constructor Summary

Constructors
Constructor
Description
`AbstractMapBackedStorageService()`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`create(String context, String key, String value, Long expiration)`
Creates a new record in the store with an expiration.
`boolean`
`delete(String context, String key)`
Deletes an existing record from the store.
`void`
`deleteContext(String context)`
Forcibly removes all records in a given context along with any associated resources devoted to maintaining the context.
`protected boolean`
`deleteImpl(Long version, String context, String key)`
Internal method to implement delete functions.
`boolean`
`deleteWithVersion(long version, String context, String key)`
Deletes an existing record from the store if it currently has a specified version.
`Iterable<String>`
`getContextKeys(String context, String prefix)`
Return an iterable collection of the keys stored in a context.
`protected abstract Map<String,Map<String,MutableStorageRecord<?>>>`
`getContextMap()`
Get the map of contexts to manipulate during operations.
`protected abstract ReadWriteLock`
`getLock()`
Get the shared lock to synchronize access.
`<T> StorageRecord<T>`
`read(String context, String key)`
Returns an existing record from the store, if one exists.
`<T> Pair<Long,StorageRecord<T>>`
`read(String context, String key, long version)`
Returns an existing record from the store, along with its version.
`protected <T> Pair<Long,StorageRecord<T>>`
`readImpl(String context, String key, Long version)`
Internal method to implement read functions.
`void`
`reap(String context)`
Manually trigger a cleanup of expired records.
`protected boolean`
`reapWithLock(Map<String,MutableStorageRecord<?>> dataMap, long expiration)`
Locates and removes expired records from the input map.
`protected void`
`setDirty()`
A callback to indicate that data has been modified.
`boolean`
`update(String context, String key, String value, Long expiration)`
Updates an existing record in the store.
`void`
`updateContextExpiration(String context, Long expiration)`
Updates the expiration time of all records in the context.
`boolean`
`updateExpiration(String context, String key, Long expiration)`
Updates expiration of an existing record in the store.
`protected Long`
`updateImpl(Long version, String context, String key, String value, Long expiration)`
Internal method to implement update functions.
`Long`
`updateWithVersion(long version, String context, String key, String value, Long expiration)`
Updates an existing record in the store, if a version matches.

### Methods inherited from class org.opensaml.storage.AbstractStorageService

`create, create, delete, deleteWithVersion, doDestroy, doInitialize, getCapabilities, getCleanupInterval, getCleanupTask, getCleanupTaskTimer, getContextSize, getKeySize, getValueSize, read, setCleanupInterval, setCleanupTaskTimer, setContextSize, setKeySize, setValueSize, update, update, updateExpiration, updateWithVersion, updateWithVersion`

### 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, create, delete, deleteWithVersion, getCapabilities, read, update, update, updateExpiration, updateWithVersion, updateWithVersion`

## Field Details

### log

@Nonnull private final org.slf4j.Logger log
Class logger.

## Constructor Details

### AbstractMapBackedStorageService

public AbstractMapBackedStorageService()
Constructor.

## Method Details

### create

public boolean create(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Nonnull @NotEmpty String value, @Nullable Long expiration) throws IOException
Creates a new record in the store with an expiration.

Specified by:
  `create` in interface `StorageService`
Parameters:
  `context` - a storage context label
  `key` - a key unique to context
  `value` - value to store
  `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

### read

@Nullable public <T> StorageRecord<T> read(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key) throws IOException
Returns an existing record from the store, if one exists.

Specified by:
  `read` in interface `StorageService`
Type Parameters:
  `T` - type of record
Parameters:
  `context` - a storage context label
  `key` - a key unique to context
Returns:
  the record read back, if present, or null
Throws:
  `IOException` - if errors occur in the read process

### read

@Nonnull public <T> Pair<Long,StorageRecord<T>> read(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, long version) throws IOException
Returns an existing record from the store, along with its version.

The first member of the pair returned will contain the version of the record in the store, or will be null if no record exists. The second member will contain the record read back. If null, the record either didn't exist (if the first member was also null) or the record was the same version as that supplied by the caller.

Specified by:
  `read` in interface `StorageService`
Type Parameters:
  `T` - type of record
Parameters:
  `context` - a storage context label
  `key` - a key unique to context
  `version` - only return record if newer than supplied version
Returns:
  a pair consisting of the version of the record read back, if any, and the record itself
Throws:
  `IOException` - if errors occur in the read process

### update

public boolean update(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Nonnull @NotEmpty String value, @Nullable Long expiration) throws IOException
Updates an existing record in the store.

Specified by:
  `update` in interface `StorageService`
Parameters:
  `context` - a storage context label
  `key` - a key unique to context
  `value` - updated value
  `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 Long updateWithVersion(long version, @Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Nonnull @NotEmpty String value, @Nullable Long expiration) throws IOException, VersionMismatchException
Updates an existing record in the store, if a version matches.

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

### updateExpiration

public boolean updateExpiration(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Nullable Long expiration) throws IOException
Updates expiration of an existing record in the store.

Specified by:
  `updateExpiration` in interface `StorageService`
Parameters:
  `context` - a storage context label
  `key` - a key unique to context
  `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

### deleteWithVersion

public boolean deleteWithVersion(long version, @Nonnull String context, @Nonnull String key) throws IOException, VersionMismatchException
Deletes an existing record from the store if it currently has a specified version.

Specified by:
  `deleteWithVersion` in interface `StorageService`
Parameters:
  `version` - record version to delete
  `context` - a storage context label
  `key` - a key unique to context
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

### delete

public boolean delete(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key) throws IOException
Deletes an existing record from the store.

Specified by:
  `delete` in interface `StorageService`
Parameters:
  `context` - a storage context label
  `key` - a key unique to context
Returns:
  true iff the record existed and was deleted
Throws:
  `IOException` - if errors occur in the deletion process

### updateContextExpiration

public void updateContextExpiration(@Nonnull @NotEmpty String context, @Nullable Long expiration) throws IOException
Updates the expiration time of all records in the context.

Specified by:
  `updateContextExpiration` in interface `StorageService`
Parameters:
  `context` - a storage context label
  `expiration` - a new expiration timestamp, or null
Throws:
  `IOException` - if errors occur in the cleanup process

### deleteContext

public void deleteContext(@Nonnull @NotEmpty String context) throws IOException
Forcibly removes all records in a given context along with any associated resources devoted to maintaining the context.

Specified by:
  `deleteContext` in interface `StorageService`
Parameters:
  `context` - a storage context label
Throws:
  `IOException` - if errors occur in the cleanup process

### reap

public void reap(@Nonnull @NotEmpty String context) throws IOException
Manually trigger a cleanup of expired records. The method MAY return without guaranteeing that cleanup has already occurred.

Specified by:
  `reap` in interface `StorageService`
Parameters:
  `context` - a storage context label
Throws:
  `IOException` - if errors occur in the cleanup process

### getContextKeys

@Nonnull public Iterable<String> getContextKeys(@Nonnull @NotEmpty String context, @Nullable String prefix) throws IOException
Return an iterable collection of the keys stored in a context.

Specified by:
  `getContextKeys` in interface `EnumeratableStorageService`
Parameters:
  `context` - the context to enumerate
  `prefix` - optional prefix to filter keys
Returns:
  keys stored in a context
Throws:
  `IOException` - on error

### getLock

@Nonnull protected abstract ReadWriteLock getLock()
Get the shared lock to synchronize access.

Returns:
  shared lock

### getContextMap

@Nonnull @Live protected abstract Map<String,Map<String,MutableStorageRecord<?>>> getContextMap() throws IOException
Get the map of contexts to manipulate during operations.

This method is guaranteed to be called under cover the lock returned by {`getLock()`.

Returns:
  map of contexts to manipulate
Throws:
  `IOException` - to signal errors

### setDirty

protected void setDirty() throws IOException
A callback to indicate that data has been modified.

This method is guaranteed to be called under cover the lock returned by {`getLock()`.

Throws:
  `IOException` - to signal an error

### readImpl

@Nonnull protected <T> Pair<Long,StorageRecord<T>> readImpl(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Nullable Long version) throws IOException
Internal method to implement read functions.

Type Parameters:
  `T` - type of object
Parameters:
  `context` - a storage context label
  `key` - a key unique to context
  `version` - only return record if newer than optionally supplied version
Returns:
  a pair consisting of the version of the record read back, if any, and the record itself
Throws:
  `IOException` - if errors occur in the read process

### updateImpl

@Nullable protected Long updateImpl(@Nullable Long version, @Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Nullable String value, @Nullable Long expiration) throws IOException, VersionMismatchException
Internal method to implement update functions.

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

### deleteImpl

protected boolean deleteImpl(@Nullable @Positive Long version, @Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key) throws IOException, VersionMismatchException
Internal method to implement delete functions.

Parameters:
  `version` - only update if the current version matches this value
  `context` - a storage context label
  `key` - a key unique to context
Returns:
  true iff the record existed and was deleted
Throws:
  `IOException` - if errors occur in the update process
  `VersionMismatchException` - if the record has already been updated to a newer version

### reapWithLock

protected boolean reapWithLock(@Nonnull Map<String,MutableStorageRecord<?>> dataMap, long expiration)
Locates and removes expired records from the input map.

This method MUST be called while holding a write lock, if locking is required.

Parameters:
  `dataMap` - the map to reap
  `expiration` - time at which to consider records expired
Returns:
  true iff anything was purged