Interface Store

All Known Implementing Classes:
DataSourceStore, FileStore, StoreBase
public interface Store
A Store is the abstraction of a Catalina component that provides persistent storage and loading of Sessions and their associated user data. Implementations are free to save and load the Sessions to any media they wish, but it is assumed that saved Sessions are persistent across server or context restarts.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addPropertyChangeListener(PropertyChangeListener listener)
    Add a property change listener to this component.
    void
    clear()
    Remove all Sessions from this Store.
    Manager
    getManager()
    Return the Manager instance associated with this Store.
    default ReadWriteLock
    getSessionStoreLock(String sessionId)
    Obtain the session store lock for the session with the given identifier.
    int
    getSize()
    Return the number of Sessions present in this Store.
    String[]
    keys()
    Return an array containing the session identifiers of all Sessions currently saved in this Store.
    Session
    load(String id)
    Load and return the Session associated with the specified session identifier from this Store, without removing it.
    void
    remove(String id)
    Remove the Session with the specified session identifier from this Store, if present.
    void
    removePropertyChangeListener(PropertyChangeListener listener)
    Remove a property change listener from this component.
    void
    save(Session session)
    Save the specified Session into this Store.
    void
    setManager(Manager manager)
    Set the Manager associated with this Store.

  • Method Details

    • getManager

      Manager getManager()
      Return the Manager instance associated with this Store.
      Returns:
      the Manager instance

    • setManager

      void setManager(Manager manager)
      Set the Manager associated with this Store.
      Parameters:
      manager - The Manager which will use this Store.

    • getSize

      int getSize() throws IOException
      Return the number of Sessions present in this Store.
      Returns:
      the number of Sessions
      Throws:
      IOException - if an input/output error occurs

    • addPropertyChangeListener

      void addPropertyChangeListener(PropertyChangeListener listener)
      Add a property change listener to this component.
      Parameters:
      listener - The listener to add

    • keys

      String[] keys() throws IOException
      Return an array containing the session identifiers of all Sessions currently saved in this Store. If there are no such Sessions, a zero-length array is returned.
      Returns:
      the session identifiers
      Throws:
      IOException - if an input/output error occurred

    • load

      Session load(String id) throws ClassNotFoundException, IOException
      Load and return the Session associated with the specified session identifier from this Store, without removing it. If there is no such stored Session, return null.

      Implementations should expect, and correctly handle, concurrent calls to any method but in particular calls to #load(String), #save(Session) and #remove(String) for the same session.

      The session ID is user provided so stores must treat it as untrusted data.

      Parameters:
      id - Session identifier of the session to load
      Returns:
      the loaded Session instance
      Throws:
      ClassNotFoundException - if a deserialization error occurs
      IOException - if an input/output error occurs

    • remove

      void remove(String id) throws IOException
      Remove the Session with the specified session identifier from this Store, if present. If no such Session is present, this method takes no action.

      Implementations should expect, and correctly handle, concurrent calls to any method but in particular calls to #load(String), #save(Session) and #remove(String) for the same session.

      The session ID is user provided so stores must treat it as untrusted data.

      Parameters:
      id - Session identifier of the Session to be removed
      Throws:
      IOException - if an input/output error occurs

    • clear

      void clear() throws IOException
      Remove all Sessions from this Store.
      Throws:
      IOException - if an input/output error occurs

    • removePropertyChangeListener

      void removePropertyChangeListener(PropertyChangeListener listener)
      Remove a property change listener from this component.
      Parameters:
      listener - The listener to remove

    • save

      void save(Session session) throws IOException
      Save the specified Session into this Store. Any previously saved information for the associated session identifier is replaced.

      Implementations should expect, and correctly handle, concurrent calls to any method but in particular calls to #load(String), #save(Session) and #remove(String) for the same session.

      Parameters:
      session - Session to be saved
      Throws:
      IOException - if an input/output error occurs

    • getSessionStoreLock

      default ReadWriteLock getSessionStoreLock(String sessionId)
      Obtain the session store lock for the session with the given identifier.

      Sub-classes of StoreBase use this lock as necessary. External users of the Store must obtain a write lock before changing the session identifier. More generally, external users of the store must obtain a write lock before manipulating the session in any way that changes the mapping from session object to session identifier.

      Implementations of this interface MUST provide an implementation of this method else any change in session identifier, e.g. on authentication, may result in inconsistent data being held in the store.

      Prior to Tomcat 12, the default implementation always returns a new ReadWriteLock which will not provide any concurrency protection. From Tomcat 12, an UnsupportedOperationException is thrown.

      Parameters:
      sessionId - the session identifier
      Returns:
      The lock for the given session identifier