Package org.jgrapes.http

Class SessionManager

java.lang.Object
org.jgrapes.core.internal.ComponentVertex
org.jgrapes.core.Component
org.jgrapes.http.SessionManager
All Implemented Interfaces:
Iterable<ComponentType>, Channel, ComponentType, Eligible, Manager
Direct Known Subclasses:
InMemorySessionManager
public abstract class SessionManager extends Component
A base class for session managers.

A session manager associates Request events with a Supplier<Optional<Session>> for a Session using Session.class as association identifier (see Session.from(org.jgrapes.core.Associator)). Note that the Optional will never by empty. The return type has been chosen to be in accordance with Associator.associatedGet(Class).

The Request handler has a default priority of 1000.

Managers track requests using a cookie with a given name and path. The path is a prefix that has to be matched by the request, often “/”. If no cookie with the given name (see idName()) is found, a new cookie with that name and the specified path is created. The cookie’s value is the unique session id that is used to lookup the session object.

Session managers provide additional support for web sockets. If a web socket is accepted, the session associated with the request is automatically made available to the IOSubchannel that is subsequently used for the web socket events. This allows handlers for web socket messages to access the session like Request handlers (see onProtocolSwitchAccepted(org.jgrapes.http.events.ProtocolSwitchAccepted, org.jgrapes.io.IOSubchannel)).

See Also:

  • Constructor Details

    • SessionManager

      public SessionManager()
      Creates a new session manager with its channel set to itself and the path set to “/”.

      The manager handles all Request events.

    • SessionManager

      public SessionManager(String path)
      Creates a new session manager with its channel set to itself and the path set to the given path.

      The manager handles all requests that match the given path, using the same rules as browsers do for selecting the cookies that are to be sent.

      Parameters:
      path - the path

    • SessionManager

      public SessionManager(Channel componentChannel)
      Creates a new session manager with its channel set to the given channel and the path to “/”.

      The manager handles all Request events.

      Parameters:
      componentChannel - the component channel

    • SessionManager

      public SessionManager(Channel componentChannel, String path)
      Creates a new session manager with the given channel and path.

      The manager handles all requests that match the given path, using the same rules as browsers do for selecting the cookies that are to be sent.

      Parameters:
      componentChannel - the component channel
      path - the path

    • SessionManager

      public SessionManager(Channel componentChannel, String pattern, int priority, String path)
      Creates a new session manager using the given channel and path.

      The manager handles only requests that match the given pattern. The handler is registered with the given priority.

      This constructor can be used if special handling of top level requests is needed.

      Parameters:
      componentChannel - the component channel
      pattern - the path part of a ResourcePattern
      priority - the priority
      path - the path

  • Method Details

    • path

      public String path()
      Returns the path.
      Returns:
      the string

    • derivePattern

      protected static String derivePattern(String path)
      Derives the resource pattern from the path.
      Parameters:
      path - the path
      Returns:
      the pattern

    • idName

      public String idName()
      The name used for the session id cookie.

      Defaults to “id”.

      Returns:
      the id name

    • setIdName

      public SessionManager setIdName(String idName)
      Parameters:
      idName - the id name to set
      Returns:
      the session manager for easy chaining

    • setMaxSessions

      public SessionManager setMaxSessions(int maxSessions)
      Set the maximum number of sessions.

      If the value is zero or less, an unlimited number of sessions is supported. The default value is 1000.

      If adding a new session would exceed the limit, first all sessions older than absoluteTimeout() are removed. If this doesn’t free a slot, the least recently used session is removed.

      Parameters:
      maxSessions - the maxSessions to set
      Returns:
      the session manager for easy chaining

    • maxSessions

      public int maxSessions()
      Returns:
      the maxSessions

    • setAbsoluteTimeout

      public SessionManager setAbsoluteTimeout(Duration timeout)
      Sets the absolute timeout for a session.

      The absolute timeout is the time after which a session is invalidated (relative to its creation time). Defaults to 9 hours. Zero or less disables the timeout.

      Parameters:
      timeout - the absolute timeout
      Returns:
      the session manager for easy chaining

    • absoluteTimeout

      public Duration absoluteTimeout()
      Returns:
      the absolute session timeout (in seconds)

    • setIdleTimeout

      public SessionManager setIdleTimeout(Duration timeout)
      Sets the idle timeout for a session.

      Defaults to 30 minutes. Zero or less disables the timeout.

      Parameters:
      timeout - the absolute timeout
      Returns:
      the session manager for easy chaining

    • idleTimeout

      public Duration idleTimeout()
      Returns:
      the idle timeout

    • onRequest

      @RequestHandler(dynamic=true) public void onRequest(Request.In event)
      Associates the event with a Session object using Session.class as association identifier.

      Does nothing if a session is already associated or the request has already been fulfilled.

      Parameters:
      event - the event

    • setSessionSupplier

      protected void setSessionSupplier(Associator holder, String sessionId)
      Associated the associator with a session supplier for the given session id and note this as session manager.
      Parameters:
      holder - the channel
      sessionId - the session id

    • addSessionCookie

      protected String addSessionCookie(HttpResponse response, String sessionId)
      Creates a session id and adds the corresponding cookie to the response.
      Parameters:
      response - the response
      Returns:
      the session id

    • hasTimedOut

      protected boolean hasTimedOut(Session session)
      Checks if the absolute or idle timeout has been reached.
      Parameters:
      session - the session
      Returns:
      true, if successful

    • startDiscarding

      protected abstract Optional<Instant> startDiscarding(long absoluteTimeout, long idleTimeout)
      Start discarding all sessions (generate DiscardSession events) that have reached their absolute or idle timeout.

      Do not make the sessions unavailable yet.

      Returns the time when the next timeout occurs. This method is called only if at least one of the timeouts has been specified.

      Implementations have to take care that sessions are only discarded once. As they must remain available while the DiscardSession event is handled this may require marking them as being discarded.

      Parameters:
      absoluteTimeout - the absolute timeout
      idleTimeout - the idle timeout
      Returns:
      the next timeout (empty if no sessions left)

    • createSession

      protected abstract Session createSession(String sessionId)
      Creates a new session with the given id.
      Parameters:
      sessionId -
      Returns:
      the session

    • lookupSession

      protected abstract Optional<Session> lookupSession(String sessionId)
      Lookup the session with the given id.

      Lookup will fail if the session has timed out.

      Parameters:
      sessionId -
      Returns:
      the session

    • removeSession

      protected abstract void removeSession(String sessionId)
      Removes the given session from the cache.
      Parameters:
      sessionId - the session id

    • sessionCount

      protected abstract int sessionCount()
      Return the number of established sessions.
      Returns:
      the result

    • onDiscard

      @Handler(channels=Channel.class, priority=-1000) public void onDiscard(DiscardSession event)
      Discards the given session.

      The handler has a priority of -1000, thus allowing other handler to make use of the session (for a time) before it becomes unavailable.

      Parameters:
      event - the event

    • onProtocolSwitchAccepted

      @Handler(priority=1000) public void onProtocolSwitchAccepted(ProtocolSwitchAccepted event, IOSubchannel channel)
      Associates the channel with a Supplier<Optional<Session>> for the session.

      Initially, the associated session is the session associated with the protocol switch event. If this session times out, a new session is returned as a fallback, thus making sure that the Optional is never empty. The new session is, however, created independently of any new session created by onRequest(org.jgrapes.http.events.Request.In).

      Applications should avoid any ambiguity by executing a proper cleanup of the web application in response to a DiscardSession event (including reestablishing the web socket connections from new requests).

      Parameters:
      event - the event
      channel - the channel