org.opensaml.storage

Interface StorageService

All Superinterfaces:

net.shibboleth.utilities.java.support.component.Component, net.shibboleth.utilities.java.support.component.IdentifiedComponent

All Known Subinterfaces:

RequestScopedStorageService

All Known Implementing Classes:

AbstractMapBackedStorageService, AbstractStorageService, JPAStorageService, LDAPStorageService, MemcachedStorageService, MemoryStorageService, ServletRequestScopedStorageService

@ThreadSafeAfterInit
public interface StorageService
extends net.shibboleth.utilities.java.support.component.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.

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	create(java.lang.String context, java.lang.String key, java.lang.String value, java.lang.Long expiration) Creates a new record in the store with an expiration.
boolean	delete(java.lang.Object value) Deletes an existing record from the store, using an annotated object as the source.
boolean	delete(java.lang.String context, java.lang.String key) Deletes an existing record from the store.
void	deleteContext(java.lang.String context) Forcibly removes all records in a given context along with any associated resources devoted to maintaining the context.
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.
boolean	deleteWithVersion(long version, java.lang.String context, java.lang.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.
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.
StorageRecord	read(java.lang.String context, java.lang.String key) Returns an existing record from the store, if one exists.
net.shibboleth.utilities.java.support.collection.Pair<java.lang.Long,StorageRecord>	read(java.lang.String context, java.lang.String key, long version) Returns an existing record from the store, along with its version.
void	reap(java.lang.String context) Manually trigger a cleanup of expired records.
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	update(java.lang.String context, java.lang.String key, java.lang.String value, java.lang.Long expiration) Updates an existing record in the store.
void	updateContextExpiration(java.lang.String context, java.lang.Long expiration) Updates the expiration time of all records in the context.
boolean	updateExpiration(java.lang.Object value) Updates expiration of an existing record in the store, using an annotated object as the source.
boolean	updateExpiration(java.lang.String context, java.lang.String key, java.lang.Long expiration) Updates expiration of an existing record in the store.
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.
java.lang.Long	updateWithVersion(long version, java.lang.String context, java.lang.String key, java.lang.String value, java.lang.Long expiration) Updates an existing record in the store, if a version matches.

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

getId

Method Detail

getCapabilities

@Nonnull
StorageCapabilities getCapabilities()

Returns the capabilities of the underlying store.

Returns:

interface to access the service's capabilities

create

boolean create(@Nonnull @NotEmpty
               java.lang.String context,
               @Nonnull @NotEmpty
               java.lang.String key,
               @Nonnull @NotEmpty
               java.lang.String value,
               @Nullable @Positive
               java.lang.Long expiration)
        throws java.io.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:

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

create

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.

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

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.

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
StorageRecord read(@Nonnull @NotEmpty
                             java.lang.String context,
                             @Nonnull @NotEmpty
                             java.lang.String key)
                      throws java.io.IOException

Returns an existing record from the store, if one exists.

Parameters:

context - a storage context label

key - a key unique to context

Returns:

the record read back, if present, or null

Throws:

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

read

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

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

read

@Nonnull
net.shibboleth.utilities.java.support.collection.Pair<java.lang.Long,StorageRecord> read(@Nonnull @NotEmpty
                                                                                                  java.lang.String context,
                                                                                                  @Nonnull @NotEmpty
                                                                                                  java.lang.String key,
                                                                                                  @Positive
                                                                                                  long version)
                                                                                           throws java.io.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.

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:

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

update

boolean update(@Nonnull @NotEmpty
               java.lang.String context,
               @Nonnull @NotEmpty
               java.lang.String key,
               @Nonnull @NotEmpty
               java.lang.String value,
               @Nullable @Positive
               java.lang.Long expiration)
        throws java.io.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:

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

updateWithVersion

@Nullable
java.lang.Long updateWithVersion(@Positive
                                           long version,
                                           @Nonnull @NotEmpty
                                           java.lang.String context,
                                           @Nonnull @NotEmpty
                                           java.lang.String key,
                                           @Nonnull @NotEmpty
                                           java.lang.String value,
                                           @Nullable @Positive
                                           java.lang.Long expiration)
                                    throws java.io.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:

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

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

update

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.

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

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

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.

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

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

boolean updateExpiration(@Nonnull @NotEmpty
                         java.lang.String context,
                         @Nonnull @NotEmpty
                         java.lang.String key,
                         @Nullable @Positive
                         java.lang.Long expiration)
                  throws java.io.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:

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

updateExpiration

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.

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

boolean delete(@Nonnull @NotEmpty
               java.lang.String context,
               @Nonnull @NotEmpty
               java.lang.String key)
        throws java.io.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:

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

deleteWithVersion

boolean deleteWithVersion(@Positive
                          long version,
                          @Nonnull @NotEmpty
                          java.lang.String context,
                          @Nonnull @NotEmpty
                          java.lang.String key)
                   throws java.io.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:

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

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

delete

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.

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

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.

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

reap

void reap(@Nonnull @NotEmpty
          java.lang.String context)
   throws java.io.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:

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

updateContextExpiration

void updateContextExpiration(@Nonnull @NotEmpty
                             java.lang.String context,
                             @Nullable
                             java.lang.Long expiration)
                      throws java.io.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:

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

deleteContext

void deleteContext(@Nonnull @NotEmpty
                   java.lang.String context)
            throws java.io.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:

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