Package org.eclipse.jetty.server.session

Class SessionHandler

java.lang.Object
org.eclipse.jetty.util.component.AbstractLifeCycle
org.eclipse.jetty.util.component.ContainerLifeCycle
org.eclipse.jetty.server.handler.AbstractHandler
org.eclipse.jetty.server.handler.AbstractHandlerContainer
org.eclipse.jetty.server.handler.HandlerWrapper
org.eclipse.jetty.server.handler.ScopedHandler
org.eclipse.jetty.server.session.SessionHandler
All Implemented Interfaces:
Handler, HandlerContainer, Container, Destroyable, Dumpable, Dumpable.DumpableContainer, LifeCycle
@ManagedObject public class SessionHandler extends ScopedHandler
SessionHandler.

  • Field Details

    • DEFAULT_TRACKING

      public static final EnumSet<jakarta.servlet.SessionTrackingMode> DEFAULT_TRACKING

    • __SessionCookieProperty

      public static final String __SessionCookieProperty
      Session cookie name. Defaults to JSESSIONID, but can be set with the org.eclipse.jetty.servlet.SessionCookie context init parameter.
      See Also:

    • __DefaultSessionCookie

      public static final String __DefaultSessionCookie
      See Also:

    • __SessionIdPathParameterNameProperty

      public static final String __SessionIdPathParameterNameProperty
      Session id path parameter name. Defaults to jsessionid, but can be set with the org.eclipse.jetty.servlet.SessionIdPathParameterName context init parameter. If context init param is "none", or setSessionIdPathParameterName is called with null or "none", no URL rewriting will be done.
      See Also:

    • __DefaultSessionIdPathParameterName

      public static final String __DefaultSessionIdPathParameterName
      See Also:

    • __CheckRemoteSessionEncoding

      public static final String __CheckRemoteSessionEncoding
      See Also:

    • __SessionDomainProperty

      public static final String __SessionDomainProperty
      Session Domain. If this property is set as a ServletContext InitParam, then it is used as the domain for session cookies. If it is not set, then no domain is specified for the session cookie.
      See Also:

    • __DefaultSessionDomain

      public static final String __DefaultSessionDomain

    • __SessionPathProperty

      public static final String __SessionPathProperty
      Session Path. If this property is set as a ServletContext InitParam, then it is used as the path for the session cookie. If it is not set, then the context path is used as the path for the cookie.
      See Also:

    • __MaxAgeProperty

      public static final String __MaxAgeProperty
      Session Max Age. If this property is set as a ServletContext InitParam, then it is used as the max age for the session cookie. If it is not set, then a max age of -1 is used.
      See Also:

    • DEFAULT_SESSION_TRACKING_MODES

      public static final Set<jakarta.servlet.SessionTrackingMode> DEFAULT_SESSION_TRACKING_MODES

    • SESSION_LISTENER_TYPES

      public static final Class<? extends EventListener>[] SESSION_LISTENER_TYPES

    • _dftMaxIdleSecs

      protected int _dftMaxIdleSecs
      Setting of max inactive interval for new sessions -1 means no timeout

    • _httpOnly

      protected boolean _httpOnly

    • _sessionIdManager

      protected SessionIdManager _sessionIdManager

    • _secureCookies

      protected boolean _secureCookies

    • _secureRequestOnly

      protected boolean _secureRequestOnly

    • _sessionAttributeListeners

      protected final List<jakarta.servlet.http.HttpSessionAttributeListener> _sessionAttributeListeners

    • _sessionListeners

      protected final List<jakarta.servlet.http.HttpSessionListener> _sessionListeners

    • _sessionIdListeners

      protected final List<jakarta.servlet.http.HttpSessionIdListener> _sessionIdListeners

    • _loader

      protected ClassLoader _loader

    • _context

      protected ContextHandler.Context _context

    • _sessionContext

      protected SessionContext _sessionContext

    • _sessionCookie

      protected String _sessionCookie

    • _sessionIdPathParameterName

      protected String _sessionIdPathParameterName

    • _sessionIdPathParameterNamePrefix

      protected String _sessionIdPathParameterNamePrefix

    • _sessionDomain

      protected String _sessionDomain

    • _sessionPath

      protected String _sessionPath

    • _maxCookieAge

      protected int _maxCookieAge

    • _refreshCookieAge

      protected int _refreshCookieAge

    • _checkingRemoteSessionIdEncoding

      protected boolean _checkingRemoteSessionIdEncoding

    • _sessionComment

      protected String _sessionComment

    • _sessionCache

      protected SessionCache _sessionCache

    • _sessionTimeStats

      protected final SampleStatistic _sessionTimeStats

    • _sessionsCreatedStats

      protected final CounterStatistic _sessionsCreatedStats

    • _sessionTrackingModes

      public Set<jakarta.servlet.SessionTrackingMode> _sessionTrackingModes

    • _usingURLs

      protected boolean _usingURLs

    • _usingCookies

      protected boolean _usingCookies

    • _candidateSessionIdsForExpiry

      protected Set<String> _candidateSessionIdsForExpiry

    • _scheduler

      protected Scheduler _scheduler

    • _ownScheduler

      protected boolean _ownScheduler

  • Constructor Details

    • SessionHandler

      public SessionHandler()
      Constructor.

  • Method Details

    • getSessionPath

      @ManagedAttribute("path of the session cookie, or null for default") public String getSessionPath()

    • getMaxCookieAge

      @ManagedAttribute("if greater the zero, the time in seconds a session cookie will last for") public int getMaxCookieAge()

    • access

      public HttpCookie access(jakarta.servlet.http.HttpSession session, boolean secure)
      Called by the SessionHandler when a session is first accessed by a request. Updates the last access time for the session and generates a fresh cookie if necessary.
      Parameters:
      session - the session object
      secure - whether the request is secure or not
      Returns:
      the session cookie. If not null, this cookie should be set on the response to either migrate the session or to refresh a session cookie that may expire.
      See Also:

    • addEventListener

      public boolean addEventListener(EventListener listener)
      Adds an event listener for session-related events.
      Specified by:
      addEventListener in interface Container
      Specified by:
      addEventListener in interface LifeCycle
      Overrides:
      addEventListener in class ContainerLifeCycle
      Parameters:
      listener - the session event listener to add Individual SessionManagers implementations may accept arbitrary listener types, but they are expected to at least handle HttpSessionActivationListener, HttpSessionAttributeListener, HttpSessionBindingListener and HttpSessionListener.
      Returns:
      true if the listener was added
      See Also:

    • callSessionDestroyedListeners

      protected void callSessionDestroyedListeners(Session session)
      Call the session lifecycle listeners in the reverse order they were added.
      Parameters:
      session - the session on which to call the lifecycle listeners

    • callSessionCreatedListeners

      protected void callSessionCreatedListeners(Session session)
      Call the session lifecycle listeners in the order they were added.
      Parameters:
      session - the session on which to call the lifecycle listeners

    • callSessionIdListeners

      protected void callSessionIdListeners(Session session, String oldId)

    • complete

      public void complete(jakarta.servlet.http.HttpSession session)
      Called when a request is finally leaving a session.
      Parameters:
      session - the session object

    • commit

      public void commit(jakarta.servlet.http.HttpSession session)
      Called when a response is about to be committed. We might take this opportunity to persist the session so that any subsequent requests to other servers will see the modifications.

    • doStart

      protected void doStart() throws Exception
      Description copied from class: ContainerLifeCycle
      Starts the managed lifecycle beans in the order they were added.
      Overrides:
      doStart in class ScopedHandler
      Throws:
      AbstractLifeCycle.StopException - If thrown, the lifecycle will immediately be stopped.
      Exception - If there was a problem starting. Will cause a transition to FAILED state

    • doStop

      protected void doStop() throws Exception
      Description copied from class: ContainerLifeCycle
      Stops the managed lifecycle beans in the reverse order they were added.
      Overrides:
      doStop in class AbstractHandler
      Throws:
      Exception - If there was a problem stopping. Will cause a transition to FAILED state

    • getHttpOnly

      @ManagedAttribute("true if cookies use the http only flag") public boolean getHttpOnly()
      Returns:
      true if session cookies should be HTTP-only (Microsoft extension)
      See Also:

    • getSameSite

      @ManagedAttribute("SameSite setting for session cookies") public HttpCookie.SameSite getSameSite()
      Returns:
      The sameSite setting for session cookies or null for no setting
      See Also:

    • getHttpSession

      protected jakarta.servlet.http.HttpSession getHttpSession(String extendedId)
      Returns the HttpSession with the given session id
      Parameters:
      extendedId - the session id
      Returns:
      the HttpSession with the corresponding id or null if no session with the given id exists

    • getSessionIdManager

      @ManagedAttribute("Session ID Manager") public SessionIdManager getSessionIdManager()
      Gets the cross context session id manager
      Returns:
      the session id manager

    • getMaxInactiveInterval

      @ManagedAttribute("default maximum time a session may be idle for (in s)") public int getMaxInactiveInterval()
      Returns:
      the max period of inactivity, after which the session is invalidated, in seconds.
      See Also:

    • getRefreshCookieAge

      @ManagedAttribute("time before a session cookie is re-set (in s)") public int getRefreshCookieAge()

    • getSecureCookies

      @ManagedAttribute("if true, secure cookie flag is set on session cookies") public boolean getSecureCookies()
      Returns:
      same as SessionCookieConfig.getSecure(). If true, session cookies are ALWAYS marked as secure. If false, a session cookie is ONLY marked as secure if _secureRequestOnly == true and it is an HTTPS request.

    • isSecureRequestOnly

      public boolean isSecureRequestOnly()
      Returns:
      true if session cookie is to be marked as secure only on HTTPS requests

    • setSecureRequestOnly

      public void setSecureRequestOnly(boolean secureRequestOnly)
      HTTPS request. Can be overridden by setting SessionCookieConfig.setSecure(true), in which case the session cookie will be marked as secure on both HTTPS and HTTP.
      Parameters:
      secureRequestOnly - true to set Session Cookie Config as secure

    • getSessionCookie

      @ManagedAttribute("the set session cookie") public String getSessionCookie()

    • getSessionCookie

      public HttpCookie getSessionCookie(jakarta.servlet.http.HttpSession session, String contextPath, boolean requestIsSecure)
      A session cookie is marked as secure IFF any of the following conditions are true:
      1. SessionCookieConfig.setSecure == true
      2. SessionCookieConfig.setSecure == false && _secureRequestOnly==true && request is HTTPS
      According to SessionCookieConfig javadoc, case 1 can be used when: "... even though the request that initiated the session came over HTTP, is to support a topology where the web container is front-ended by an SSL offloading load balancer. In this case, the traffic between the client and the load balancer will be over HTTPS, whereas the traffic between the load balancer and the web container will be over HTTP."

      For case 2, you can use _secureRequestOnly to determine if you want the Servlet Spec 3.0 default behavior when SessionCookieConfig.setSecure==false, which is: "they shall be marked as secure only if the request that initiated the corresponding session was also secure"

      The default for _secureRequestOnly is true, which gives the above behavior. If you set it to false, then a session cookie is NEVER marked as secure, even if the initiating request was secure.

      Parameters:
      session - the session to which the cookie should refer.
      contextPath - the context to which the cookie should be linked. The client will only send the cookie value when requesting resources under this path.
      requestIsSecure - whether the client is accessing the server over a secure protocol (i.e. HTTPS).
      Returns:
      if this SessionManager uses cookies, then this method will return a new cookie object that should be set on the client in order to link future HTTP requests with the session. If cookies are not in use, this method returns null.

    • getSessionDomain

      @ManagedAttribute("domain of the session cookie, or null for the default") public String getSessionDomain()

    • getSessionsCreated

      @ManagedAttribute("number of sessions created by this node") public int getSessionsCreated()

    • getSessionIdPathParameterName

      @ManagedAttribute("name of use for URL session tracking") public String getSessionIdPathParameterName()
      Returns:
      the URL path parameter name for session id URL rewriting, by default "jsessionid".
      See Also:

    • getSessionIdPathParameterNamePrefix

      public String getSessionIdPathParameterNamePrefix()
      Returns:
      a formatted version of getSessionIdPathParameterName(), by default ";" + sessionIdParameterName + "=", for easier lookup in URL strings.
      See Also:

    • isUsingCookies

      public boolean isUsingCookies()
      Returns:
      whether the session management is handled via cookies.

    • isValid

      public boolean isValid(jakarta.servlet.http.HttpSession session)
      Parameters:
      session - the session to test for validity
      Returns:
      whether the given session is valid, that is, it has not been invalidated.

    • getId

      public String getId(jakarta.servlet.http.HttpSession session)
      Parameters:
      session - the session object
      Returns:
      the unique id of the session within the cluster (without a node id extension)
      See Also:

    • getExtendedId

      public String getExtendedId(jakarta.servlet.http.HttpSession session)
      Parameters:
      session - the session object
      Returns:
      the unique id of the session within the cluster, extended with an optional node id.
      See Also:

    • newHttpSession

      public jakarta.servlet.http.HttpSession newHttpSession(jakarta.servlet.http.HttpServletRequest request)
      Creates a new HttpSession.
      Parameters:
      request - the HttpServletRequest containing the requested session id
      Returns:
      the new HttpSession

    • removeEventListener

      public boolean removeEventListener(EventListener listener)
      Description copied from interface: Container
      Remove an event listener.
      Specified by:
      removeEventListener in interface Container
      Specified by:
      removeEventListener in interface LifeCycle
      Overrides:
      removeEventListener in class ContainerLifeCycle
      Parameters:
      listener - the listener to remove
      Returns:
      true if the listener was removed
      See Also:

    • statsReset

      @ManagedOperation(value="reset statistics", impact="ACTION") public void statsReset()
      Reset statistics values

    • setHttpOnly

      public void setHttpOnly(boolean httpOnly)
      Set if Session cookies should use HTTP Only
      Parameters:
      httpOnly - True if cookies should be HttpOnly.
      See Also:

    • setPartitioned

      public void setPartitioned(boolean partitioned)
      Sets whether session cookies should have the Partitioned attribute.
      Parameters:
      partitioned - whether session cookies should have the Partitioned attribute
      See Also:

    • setSameSite

      public void setSameSite(HttpCookie.SameSite sameSite)
      Set Session cookie sameSite mode. Currently this is encoded in the session comment until sameSite is supported by SessionCookieConfig
      Parameters:
      sameSite - The sameSite setting for Session cookies (or null for no sameSite setting)

    • setSessionIdManager

      public void setSessionIdManager(SessionIdManager metaManager)
      Parameters:
      metaManager - The metaManager used for cross context session management.

    • setMaxInactiveInterval

      public void setMaxInactiveInterval(int seconds)
      Sets the max period of inactivity, after which the session is invalidated, in seconds.
      Parameters:
      seconds - the max inactivity period, in seconds. If less than or equal to zero, then the session is immortal
      See Also:

    • setRefreshCookieAge

      public void setRefreshCookieAge(int ageInSeconds)

    • setSessionCookie

      public void setSessionCookie(String cookieName)

    • setSessionIdPathParameterName

      public void setSessionIdPathParameterName(String param)
      Sets the session id URL path parameter name.
      Parameters:
      param - the URL path parameter name for session id URL rewriting (null or "none" for no rewriting).
      See Also:

    • setUsingCookies

      public void setUsingCookies(boolean usingCookies)
      Parameters:
      usingCookies - The usingCookies to set.

    • getSession

      public Session getSession(String id)
      Get a known existing session
      Parameters:
      id - The session ID stripped of any worker name.
      Returns:
      A Session or null if none exists.

    • shutdownSessions

      protected void shutdownSessions() throws Exception
      Prepare sessions for session manager shutdown
      Throws:
      Exception - if unable to shutdown sesssions

    • getSessionCache

      public SessionCache getSessionCache()
      Returns:
      the session store

    • setSessionCache

      public void setSessionCache(SessionCache cache)
      Parameters:
      cache - the session store to use

    • removeSession

      public Session removeSession(String id, boolean invalidate)
      Remove session from manager
      Parameters:
      id - The session to remove
      invalidate - True if HttpSessionListener.sessionDestroyed(HttpSessionEvent) and SessionIdManager.expireAll(String) should be called.
      Returns:
      if the session was removed

    • getSessionTimeMax

      @ManagedAttribute("maximum amount of time sessions have remained active (in s)") public long getSessionTimeMax()
      Returns:
      maximum amount of time session remained valid

    • getDefaultSessionTrackingModes

      public Set<jakarta.servlet.SessionTrackingMode> getDefaultSessionTrackingModes()

    • getEffectiveSessionTrackingModes

      public Set<jakarta.servlet.SessionTrackingMode> getEffectiveSessionTrackingModes()

    • setSessionTrackingModes

      public void setSessionTrackingModes(Set<jakarta.servlet.SessionTrackingMode> sessionTrackingModes)

    • isUsingURLs

      public boolean isUsingURLs()
      Returns:
      whether the session management is handled via URLs.

    • getSessionCookieConfig

      public jakarta.servlet.SessionCookieConfig getSessionCookieConfig()

    • getSessionTimeTotal

      @ManagedAttribute("total time sessions have remained valid") public long getSessionTimeTotal()
      Returns:
      total amount of time all sessions remained valid

    • getSessionTimeMean

      @ManagedAttribute("mean time sessions remain valid (in s)") public double getSessionTimeMean()
      Returns:
      mean amount of time session remained valid

    • getSessionTimeStdDev

      @ManagedAttribute("standard deviation a session remained valid (in s)") public double getSessionTimeStdDev()
      Returns:
      standard deviation of amount of time session remained valid

    • isCheckingRemoteSessionIdEncoding

      @ManagedAttribute("check remote session id encoding") public boolean isCheckingRemoteSessionIdEncoding()
      Returns:
      True if absolute URLs are check for remoteness before being session encoded.

    • setCheckingRemoteSessionIdEncoding

      public void setCheckingRemoteSessionIdEncoding(boolean remote)
      Parameters:
      remote - True if absolute URLs are check for remoteness before being session encoded.

    • renewSessionId

      public void renewSessionId(String oldId, String oldExtendedId, String newId, String newExtendedId)
      Change the existing session id.
      Parameters:
      oldId - the old session id
      oldExtendedId - the session id including worker suffix
      newId - the new session id
      newExtendedId - the new session id including worker suffix

    • recordSessionTime

      protected void recordSessionTime(Session session)
      Record length of time session has been active. Called when the session is about to be invalidated.
      Parameters:
      session - the session whose time to record

    • invalidate

      public void invalidate(String id)
      Called by SessionIdManager to remove a session that has been invalidated, either by this context or another context. Also called by SessionIdManager when a session has expired in either this context or another context.
      Parameters:
      id - the session id to invalidate

    • scavenge

      public void scavenge()
      Called periodically by the HouseKeeper to handle the list of sessions that have expired since the last call to scavenge.

    • sessionInactivityTimerExpired

      public void sessionInactivityTimerExpired(Session session, long now)
      Each session has a timer that is configured to go off when either the session has not been accessed for a configurable amount of time, or the session itself has passed its expiry. If it has passed its expiry, then we will mark it for scavenging by next run of the HouseKeeper; if it has been idle longer than the configured eviction period, we evict from the cache. If none of the above are true, then the System timer is inconsistent and the caller of this method will need to reset the timer.
      Parameters:
      session - the session
      now - the time at which to check for expiry

    • isIdInUse

      public boolean isIdInUse(String id) throws Exception
      Check if id is in use by this context
      Parameters:
      id - identity of session to check
      Returns:
      true if this manager knows about this id
      Throws:
      Exception - if any error occurred

    • getScheduler

      public Scheduler getScheduler()

    • getSessionCookieName

      public static String getSessionCookieName(jakarta.servlet.SessionCookieConfig config)

    • doSessionAttributeListeners

      public void doSessionAttributeListeners(Session session, String name, Object old, Object value)

    • doScope

      public void doScope(String target, Request baseRequest, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response) throws IOException, jakarta.servlet.ServletException
      Description copied from class: ScopedHandler
      Scope the handler

      Derived implementations should call ScopedHandler.nextScope(String, Request, HttpServletRequest, HttpServletResponse)

      Overrides:
      doScope in class ScopedHandler
      Parameters:
      target - The target of the request - either a URI or a name.
      baseRequest - The original unwrapped request object.
      request - The request either as the Request object or a wrapper of that request. The HttpConnection.getCurrentConnection().getHttpChannel().getRequest() method can be used access the Request object if required.
      response - The response as the Response object or a wrapper of that request. The HttpConnection.getCurrentConnection().getHttpChannel().getResponse() method can be used access the Response object if required.
      Throws:
      IOException - if unable to handle the request or response processing
      jakarta.servlet.ServletException - if unable to handle the request or response due to underlying servlet issue

    • doHandle

      public void doHandle(String target, Request baseRequest, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response) throws IOException, jakarta.servlet.ServletException
      Description copied from class: ScopedHandler
      Do the handler work within the scope.

      Derived implementations should call ScopedHandler.nextHandle(String, Request, HttpServletRequest, HttpServletResponse)

      Specified by:
      doHandle in class ScopedHandler
      Parameters:
      target - The target of the request - either a URI or a name.
      baseRequest - The original unwrapped request object.
      request - The request either as the Request object or a wrapper of that request. The HttpConnection.getCurrentConnection().getHttpChannel().getRequest() method can be used access the Request object if required.
      response - The response as the Response object or a wrapper of that request. The HttpConnection.getCurrentConnection().getHttpChannel().getResponse() method can be used access the Response object if required.
      Throws:
      IOException - if unable to handle the request or response processing
      jakarta.servlet.ServletException - if unable to handle the request or response due to underlying servlet issue

    • checkRequestedSessionId

      protected void checkRequestedSessionId(Request baseRequest, jakarta.servlet.http.HttpServletRequest request)
      Look for a requested session ID in cookies and URI parameters
      Parameters:
      baseRequest - the request to check
      request - the request to check

    • toString

      public String toString()
      Overrides:
      toString in class AbstractLifeCycle