Package org.eclipse.jetty.server.session

Interface SessionCache

  • All Superinterfaces:
    LifeCycle
    All Known Implementing Classes:
    AbstractSessionCache, DefaultSessionCache, NullSessionCache
    public interface SessionCache
extends LifeCycle
    SessionCache A working set of Session objects for a context. Ideally, multiple requests for the same session id in the same context will always share the same Session object from the SessionCache, but it would be possible for implementations of SessionCache to create a fresh object for each request. The SessionData pertaining to the Session objects is obtained from/written to a SessionDataStore. The SessionDataStore is the authoritative source of session data:
    • if the session data is not present in the SessionDataStore the session does not exist.
    • if the session data is present in the SessionDataStore but its expiry time has passed then the session is deemed to have expired and is therefore invalid
    A SessionCache can passivate a valid Session to the SessionDataStore and evict it from the cache according to various strategies:
    • whenever the last request exits a Session
    • whenever the Session has not been accessed for a configurable number of seconds
    . Eviction can save memory, and can also help mitigate some of the problems of a non-sticky load balancer by forcing the session data to be re-read from the SessionDataStore more frequently.

    • Method Detail

      • shutdown

        void shutdown()

      • newSession

        Session newSession​(javax.servlet.http.HttpServletRequest request,
                   java.lang.String id,
                   long time,
                   long maxInactiveMs)
        Create an entirely new Session.
        Parameters:
        request - the request
        id - the unique id associated to the session
        time - the timestamp of the session creation
        maxInactiveMs - the max inactive time in milliseconds
        Returns:
        a new Session

      • newSession

        Session newSession​(SessionData data)
        Re-materialize a Session that has previously existed.
        Parameters:
        data - the data associated with the session
        Returns:
        a Session object for the data supplied

      • renewSessionId

        @Deprecated
default Session renewSessionId​(java.lang.String oldId,
                               java.lang.String newId)
                        throws java.lang.Exception
        Deprecated.
        use renewSessionId(String oldId, String newId, String oldExtendedId, String newExtendedId)
        Change the id of a session. This method has been superceded by the 4 arg renewSessionId method and should no longer be called.
        Parameters:
        oldId - the old id
        newId - the new id
        Returns:
        the changed Session
        Throws:
        java.lang.Exception - if anything went wrong

      • renewSessionId

        default Session renewSessionId​(java.lang.String oldId,
                               java.lang.String newId,
                               java.lang.String oldExtendedId,
                               java.lang.String newExtendedId)
                        throws java.lang.Exception
        Change the id of a Session.
        Parameters:
        oldId - the current session id
        newId - the new session id
        oldExtendedId - the current extended session id
        newExtendedId - the new extended session id
        Returns:
        the Session after changing its id
        Throws:
        java.lang.Exception - if any error occurred

      • add

        void add​(java.lang.String id,
         Session session)
  throws java.lang.Exception
        Adds a new Session, with a never-before-used id, to the cache.
        Parameters:
        id -
        session -
        Throws:
        java.lang.Exception

      • get

        Session get​(java.lang.String id)
     throws java.lang.Exception
        Get an existing Session. If necessary, the cache will load the data for the session from the configured SessionDataStore.
        Parameters:
        id - the session id
        Returns:
        the Session if one exists, null otherwise
        Throws:
        java.lang.Exception - if any error occurred

      • put

        void put​(java.lang.String id,
         Session session)
  throws java.lang.Exception
        Deprecated.
        Finish using a Session. This is called by the SessionHandler once a request is finished with a Session. SessionCache implementations may want to delay writing out Session contents until the last request exits a Session.
        Parameters:
        id - the session id
        session - the current session object
        Throws:
        java.lang.Exception - if any error occurred
        See Also:
        release(java.lang.String,org.eclipse.jetty.server.session.Session)

      • release

        void release​(java.lang.String id,
             Session session)
      throws java.lang.Exception
        Finish using a Session. This is called by the SessionHandler once a request is finished with a Session. SessionCache implementations may want to delay writing out Session contents until the last request exits a Session.
        Parameters:
        id - the session id
        session - the current session object
        Throws:
        java.lang.Exception - if any error occurred

      • commit

        void commit​(Session session)
     throws java.lang.Exception
        Called when a response is about to be committed. The cache can write the session to ensure that the SessionDataStore contains changes to the session that occurred during the lifetime of the request. This can help ensure that if a subsequent request goes to a different server, it will be able to see the session changes via the shared store.
        Throws:
        java.lang.Exception

      • contains

        boolean contains​(java.lang.String id)
          throws java.lang.Exception
        Check to see if a Session is in the cache. Does NOT consult the SessionDataStore.
        Parameters:
        id - the session id
        Returns:
        true if a Session object matching the id is present in the cache, false otherwise
        Throws:
        java.lang.Exception - if any error occurred

      • exists

        boolean exists​(java.lang.String id)
        throws java.lang.Exception
        Check to see if a session exists: WILL consult the SessionDataStore.
        Parameters:
        id - the session id
        Returns:
        true if the session exists, false otherwise
        Throws:
        java.lang.Exception - if any error occurred

      • delete

        Session delete​(java.lang.String id)
        throws java.lang.Exception
        Remove a Session completely: from both this cache and the SessionDataStore.
        Parameters:
        id - the session id
        Returns:
        the Session that was removed, null otherwise
        Throws:
        java.lang.Exception - if any error occurred

      • checkExpiration

        java.util.Set<java.lang.String> checkExpiration​(java.util.Set<java.lang.String> candidates)
        Check a list of session ids that belong to potentially expired sessions. The Session in the cache should be checked, but also the SessionDataStore, as that is the authoritative source of all session information.
        Parameters:
        candidates - the session ids to check
        Returns:
        the set of session ids that have actually expired: this can be a superset of the original candidate list.

      • checkInactiveSession

        void checkInactiveSession​(Session session)
        Check a Session to see if it might be appropriate to evict or expire.
        Parameters:
        session - the session to check

      • setSessionDataStore

        void setSessionDataStore​(SessionDataStore sds)
        A SessionDataStore that is the authoritative source of session information.
        Parameters:
        sds - the SessionDataStore to use

      • setEvictionPolicy

        void setEvictionPolicy​(int policy)
        Sessions in this cache can be:
        • never evicted
        • evicted once the last request exits
        • evicted after a configurable period of inactivity
        Parameters:
        policy - -1 is never evict; 0 is evict-on-exit; and any other positive value is the time in seconds that a session can be idle before it can be evicted.

      • getEvictionPolicy

        int getEvictionPolicy()
        Returns:
        the eviction policy

      • setSaveOnInactiveEviction

        void setSaveOnInactiveEviction​(boolean saveOnEvict)
        Whether or not a a session that is about to be evicted should be saved before being evicted.
        Parameters:
        saveOnEvict - true if the session should be saved before being evicted

      • isSaveOnInactiveEviction

        boolean isSaveOnInactiveEviction()
        Returns:
        true if the session should be saved before being evicted

      • setSaveOnCreate

        void setSaveOnCreate​(boolean saveOnCreate)
        Whether or not a session that is newly created should be immediately saved. If false, a session that is created and invalidated within a single request is never persisted.
        Parameters:
        saveOnCreate - true to immediately save the newly created session

      • isSaveOnCreate

        boolean isSaveOnCreate()
        Returns:
        if true the newly created session will be saved immediately

      • setRemoveUnloadableSessions

        void setRemoveUnloadableSessions​(boolean removeUnloadableSessions)
        If the data for a session exists but is unreadable, the SessionCache can instruct the SessionDataStore to delete it.
        Parameters:
        removeUnloadableSessions - true to delete session which cannot be loaded

      • isRemoveUnloadableSessions

        boolean isRemoveUnloadableSessions()
        Returns:
        if true unloadable session will be deleted

      • setFlushOnResponseCommit

        void setFlushOnResponseCommit​(boolean flushOnResponse)
        If true, a dirty session will be written to the SessionDataStore just before a response is returned to the client. This ensures that subsequent requests to either the same node or a different node see the changed session data.

      • isFlushOnResponseCommit

        boolean isFlushOnResponseCommit()
        Returns:
        true if dirty sessions should be written before the response is committed.

      • setInvalidateOnShutdown

        void setInvalidateOnShutdown​(boolean invalidateOnShutdown)
        If true, all existing sessions in the cache will be invalidated when the server shuts down. Default is false.
        Parameters:
        invalidateOnShutdown -

      • isInvalidateOnShutdown

        boolean isInvalidateOnShutdown()