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