Package org.opensaml.storage

# Interface StorageService

All Superinterfaces:
  `Component`, `IdentifiedComponent`

All Known Subinterfaces:
  `EnumeratableStorageService`

All Known Implementing Classes:
  `AbstractMapBackedStorageService`, `AbstractStorageService`, `ClientStorageService`, `MemcachedStorageService`, `MemoryStorageService`

@ThreadSafeAfterInit public interface StorageService extends IdentifiedComponent
Generic data storage facility. Implementations will vary in how much persistence they can supply, and must support a `StorageCapabilities` interface to describe storage limitations.

Storage is divided into "contexts" identified by a string label. Keys need to be unique only within a given context, so multiple components can share a single store safely as long as they use different labels.

The allowable sizes for contexts and keys can vary and be reported by the implementation to callers, but MUST be at least 255 characters.

Expiration is expressed in milliseconds since the beginning of the epoch, or a null can be used to signify no expiration. Implementations MUST persist the expiration in a manner that allows the exact value supplied to be recovered. It is not sufficient to ensure that records expire; the actual value is used in many cases as part of the data set being stored and cannot be perturbed.

## 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.
`boolean`
`create(String context, String key, String value, Long expiration)`
Creates a new record in the store with an expiration.
`<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`
`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.
`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.
`boolean`
`deleteWithVersion(long version, String context, String key)`
Deletes an existing record from the store if it currently has a specified version.
`StorageCapabilities`
`getCapabilities()`
Returns the capabilities of the underlying store.
`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.
`<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.
`void`
`reap(String context)`
Manually trigger a cleanup of expired records.
`boolean`
`update(Object value)`
Updates an existing record in the store, using an annotated object as the source.
`boolean`
`update(String context, String key, String value, Long expiration)`
Updates an existing record in the store.
`<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.
`void`
`updateContextExpiration(String context, Long expiration)`
Updates the expiration time of all records in the context.
`boolean`
`updateExpiration(Object value)`
Updates expiration of an existing record in the store, using an annotated object as the source.
`boolean`
`updateExpiration(String context, String key, Long expiration)`
Updates expiration of an existing record in the store.
`Long`
`updateWithVersion(long version, Object value)`
Updates an existing record in the store, if a version matches, using an annotated object as the source.
`Long`
`updateWithVersion(long version, String context, String key, String value, Long expiration)`
Updates an existing record in the store, if a version matches.
`<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 interface net.shibboleth.shared.component.IdentifiedComponent

`getId`

## Method Details

### getCapabilities

@Nonnull StorageCapabilities getCapabilities()
Returns the capabilities of the underlying store.

Returns:
  interface to access the service's capabilities

### create

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

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

### create

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

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

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.

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 <T> StorageRecord<T> read(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key) throws IOException
Returns an existing record from the store, if one exists.

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

@Nullable 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.

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

### read

@Nonnull <T> Pair<Long,StorageRecord<T>> read(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Positive 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.

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

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

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 Long updateWithVersion(@Positive long version, @Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Nonnull @NotEmpty String value, @Nullable @Positive Long expiration) throws IOException, VersionMismatchException
Updates an existing record in the store, if a version matches.

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

### update

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

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

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

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.

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

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

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

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

### updateExpiration

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.

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

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

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

### deleteWithVersion

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

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

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.

Parameters:
  `value` - object to delete
Returns:
  true iff the record existed and was deleted
Throws:
  `IOException` - if errors occur in the deletion process

### deleteWithVersion

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.

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

### reap

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.

Parameters:
  `context` - a storage context label
Throws:
  `IOException` - if errors occur in the cleanup process

### updateContextExpiration

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

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

### deleteContext

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.

Parameters:
  `context` - a storage context label
Throws:
  `IOException` - if errors occur in the cleanup process