Module org.eclipse.jetty.session

Package org.eclipse.jetty.session

Class AbstractSessionManager

java.lang.Object

org.eclipse.jetty.util.component.AbstractLifeCycle

org.eclipse.jetty.util.component.ContainerLifeCycle

org.eclipse.jetty.session.AbstractSessionManager

All Implemented Interfaces:

SessionConfig, SessionConfig.Mutable, SessionManager, org.eclipse.jetty.util.component.Container, org.eclipse.jetty.util.component.Destroyable, org.eclipse.jetty.util.component.Dumpable, org.eclipse.jetty.util.component.Dumpable.DumpableContainer, org.eclipse.jetty.util.component.LifeCycle

Direct Known Subclasses:

SessionHandler

public abstract class AbstractSessionManager
extends org.eclipse.jetty.util.component.ContainerLifeCycle
implements SessionManager, SessionConfig.Mutable

AbstractSessionHandler Class to implement most non-servlet-spec specific session behaviour.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	AbstractSessionManager.RequestedSession	Details of the requested session.

Nested classes/interfaces inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

org.eclipse.jetty.util.component.AbstractLifeCycle.AbstractLifeCycleListener, org.eclipse.jetty.util.component.AbstractLifeCycle.StopException

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.Container

org.eclipse.jetty.util.component.Container.InheritedListener, org.eclipse.jetty.util.component.Container.Listener

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.Dumpable

org.eclipse.jetty.util.component.Dumpable.DumpableContainer, org.eclipse.jetty.util.component.Dumpable.DumpAppendable

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.LifeCycle

org.eclipse.jetty.util.component.LifeCycle.Listener

Nested classes/interfaces inherited from interface org.eclipse.jetty.session.SessionConfig

SessionConfig.Mutable

Field Summary

Fields inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

FAILED, STARTED, STARTING, STOPPED, STOPPING

Fields inherited from interface org.eclipse.jetty.util.component.Dumpable

LEGEND

Fields inherited from interface org.eclipse.jetty.session.SessionConfig

__CheckRemoteSessionEncodingProperty, __DefaultSessionCookie, __DefaultSessionDomain, __DefaultSessionIdPathParameterName, __MaxAgeProperty, __SessionCookieProperty, __SessionDomainProperty, __SessionIdPathParameterNameProperty, __SessionPathProperty

Constructor Summary

Constructors

Constructor	Description
AbstractSessionManager()

Method Summary

Modifier and Type	Method	Description
org.eclipse.jetty.http.HttpCookie	access(ManagedSession session, boolean secure)	Called when a session is first accessed by request processing.
protected void	addSessionStreamWrapper(org.eclipse.jetty.server.Request request)
long	calculateInactivityTimeout(String id, long timeRemainingMs, long maxInactiveMs)	Calculate what the session timer setting should be based on: the time remaining before the session expires and any idle eviction time configured.
void	commit(ManagedSession session)	Called when a response is about to be committed.
void	complete(ManagedSession session)	Called when a request is finally leaving a session.
void	doStart()
protected void	doStop()
String	encodeURI(org.eclipse.jetty.server.Request request, String uri, boolean cookiesInUse)
org.eclipse.jetty.server.Context	getContext()
ManagedSession	getManagedSession(String extendedId)	Get a known existing session
int	getMaxCookieAge()
int	getMaxInactiveInterval()
int	getRefreshCookieAge()
org.eclipse.jetty.http.HttpCookie.SameSite	getSameSite()
abstract org.eclipse.jetty.server.Server	getServer()
SessionCache	getSessionCache()
String	getSessionComment()
SessionContext	getSessionContext()
String	getSessionCookie()
org.eclipse.jetty.http.HttpCookie	getSessionCookie(ManagedSession session, boolean requestIsSecure)	A session cookie is marked as secure IFF any of the following conditions are true: SessionCookieConfig.setSecure == true 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.
String	getSessionCookieAttribute(String name)
Map<String,String>	getSessionCookieAttributes()
String	getSessionDomain()
SessionIdManager	getSessionIdManager()
String	getSessionIdPathParameterName()
String	getSessionIdPathParameterNamePrefix()
String	getSessionPath()
int	getSessionsCreated()
double	getSessionTimeMean()
double	getSessionTimeStdDev()
long	getSessionTimeTotal()
void	invalidate(String id)	Called by SessionIdManager to remove a session that has been invalidated, either by this context or another context.
boolean	isCheckingRemoteSessionIdEncoding()
boolean	isHttpOnly()
boolean	isIdInUse(String id)	Check if id is in use by this context
boolean	isPartitioned()
boolean	isSecureCookies()
boolean	isSecureRequestOnly()
boolean	isUsingCookies()
boolean	isUsingUriParameters()
void	newSession(org.eclipse.jetty.server.Request request, String requestedSessionId, Consumer<ManagedSession> consumer)	Create a new Session, using the requested session id if possible.
SessionInactivityTimer	newSessionInactivityTimer(ManagedSession session)	Make a new timer for the session.
void	onSessionCreated(org.eclipse.jetty.server.Session session)
void	onSessionDestroyed(org.eclipse.jetty.server.Session session)
void	onSessionIdChanged(org.eclipse.jetty.server.Session session, String oldId)
void	recordSessionTime(ManagedSession session)	Record length of time session has been active.
void	renewSessionId(String oldId, String oldExtendedId, String newId, String newExtendedId)	Change the existing session id.
protected AbstractSessionManager.RequestedSession	resolveRequestedSessionId(org.eclipse.jetty.server.Request request)	Find any Session associated with the Request.
void	scavenge()	Called periodically by the HouseKeeper to handle the list of sessions that have expired since the last call to scavenge.
void	sessionTimerExpired(ManagedSession 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.
void	setCheckingRemoteSessionIdEncoding(boolean remote)
void	setHttpOnly(boolean httpOnly)	Set if Session cookies should use HTTP Only
void	setMaxCookieAge(int maxCookieAge)
void	setMaxInactiveInterval(int seconds)	Sets the max period of inactivity, after which the session is invalidated, in seconds.
void	setPartitioned(boolean partitioned)	Sets whether session cookies should have the Partitioned attribute
void	setRefreshCookieAge(int ageInSeconds)
void	setSameSite(org.eclipse.jetty.http.HttpCookie.SameSite sessionSameSite)
void	setSecureCookies(boolean secure)
void	setSecureRequestOnly(boolean secureRequestOnly)	HTTPS request.
void	setSessionCache(SessionCache cache)	Set up the SessionCache.
void	setSessionComment(String sessionComment)
void	setSessionCookie(String cookieName)
void	setSessionCookieAttribute(String name, String value)
void	setSessionDomain(String domain)
void	setSessionIdManager(SessionIdManager sessionIdManager)	Set up the SessionIdManager.
void	setSessionIdPathParameterName(String param)	Sets the session id URL path parameter name.
void	setSessionPath(String sessionPath)
void	setUsingCookies(boolean usingCookies)
void	setUsingUriParameters(boolean usingUriParameters)

Methods inherited from class org.eclipse.jetty.util.component.ContainerLifeCycle

addBean, addBean, addEventListener, addManaged, contains, destroy, dump, dump, dump, dumpObjects, dumpStdErr, getBean, getBeans, getBeans, getContainedBeans, getContainedBeans, installBean, installBean, isAuto, isManaged, isUnmanaged, manage, removeBean, removeBeans, removeEventListener, setBeans, start, stop, unmanage, updateBean, updateBean, updateBeans, updateBeans

Methods inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

getEventListeners, getState, getState, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, setEventListeners, start, stop, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.eclipse.jetty.util.component.Container

getCachedBeans, getEventListeners

Methods inherited from interface org.eclipse.jetty.util.component.Dumpable

dumpSelf

Methods inherited from interface org.eclipse.jetty.util.component.Dumpable.DumpableContainer

isDumpable

Methods inherited from interface org.eclipse.jetty.util.component.LifeCycle

addEventListener, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeEventListener, start, stop

Methods inherited from interface org.eclipse.jetty.session.SessionManager

getManagedSession, newSessionAPIWrapper, onSessionActivation, onSessionAttributeUpdate, onSessionPassivation

Constructor Details

AbstractSessionManager

public AbstractSessionManager()

Method Details

access

public org.eclipse.jetty.http.HttpCookie access(ManagedSession session,
 boolean secure)

Called when a session is first accessed by request processing. 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:

• complete(ManagedSession)

calculateInactivityTimeout

public long calculateInactivityTimeout(String id,
 long timeRemainingMs,
 long maxInactiveMs)

Calculate what the session timer setting should be based on: the time remaining before the session expires and any idle eviction time configured. The timer value will be the lesser of the above.

Specified by:

calculateInactivityTimeout in interface SessionManager

Parameters:

id - the ID of the session

timeRemainingMs - The time in milliseconds remaining before this session is considered Idle

maxInactiveMs - The maximum time in milliseconds that a session may be idle.

Returns:

the time remaining before expiry or inactivity timeout

commit

public void commit(ManagedSession 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.

Specified by:

commit in interface SessionManager

complete

public void complete(ManagedSession session)

Called when a request is finally leaving a session.

Specified by:

complete in interface SessionManager

Parameters:

session - the session object

doStart

public void doStart()
             throws Exception

Overrides:

doStart in class org.eclipse.jetty.util.component.ContainerLifeCycle

Throws:

Exception

getContext

public org.eclipse.jetty.server.Context getContext()

Specified by:

getContext in interface SessionManager

getMaxCookieAge

public int getMaxCookieAge()

Specified by:

getMaxCookieAge in interface SessionConfig

setMaxCookieAge

public void setMaxCookieAge(int maxCookieAge)

Specified by:

setMaxCookieAge in interface SessionConfig.Mutable

getMaxInactiveInterval

public int getMaxInactiveInterval()

Specified by:

getMaxInactiveInterval in interface SessionConfig

Returns:

the max period of inactivity, after which the session is invalidated, in seconds. If less than or equal to zero, then the session is immortal

See Also:

• setMaxInactiveInterval(int)

setMaxInactiveInterval

public void setMaxInactiveInterval(int seconds)

Sets the max period of inactivity, after which the session is invalidated, in seconds.

Specified by:

setMaxInactiveInterval in interface SessionConfig.Mutable

Parameters:

seconds - the max inactivity period, in seconds. If less than or equal to zero, then the session is immortal

See Also:

• getMaxInactiveInterval()

getRefreshCookieAge

public int getRefreshCookieAge()

Specified by:

getRefreshCookieAge in interface SessionConfig

setRefreshCookieAge

public void setRefreshCookieAge(int ageInSeconds)

Specified by:

setRefreshCookieAge in interface SessionConfig.Mutable

getServer

public abstract org.eclipse.jetty.server.Server getServer()

getManagedSession

public ManagedSession getManagedSession(String extendedId)

Get a known existing session

Specified by:

getManagedSession in interface SessionManager

Parameters:

extendedId - The session id, possibly including worker name suffix.

Returns:

the Session matching the id or null if none exists

getSessionCache

public SessionCache getSessionCache()

Specified by:

getSessionCache in interface SessionManager

Returns:

the session cache

setSessionCache

public void setSessionCache(SessionCache cache)

Set up the SessionCache.

Specified by:

setSessionCache in interface SessionConfig.Mutable

Specified by:

setSessionCache in interface SessionManager

Parameters:

cache - the SessionCache to use

getSessionComment

public String getSessionComment()

Specified by:

getSessionComment in interface SessionConfig

setSessionComment

public void setSessionComment(String sessionComment)

Specified by:

setSessionComment in interface SessionConfig.Mutable

getSameSite

public org.eclipse.jetty.http.HttpCookie.SameSite getSameSite()

Specified by:

getSameSite in interface SessionConfig

setSameSite

public void setSameSite(org.eclipse.jetty.http.HttpCookie.SameSite sessionSameSite)

Specified by:

setSameSite in interface SessionConfig.Mutable

getSessionContext

public SessionContext getSessionContext()

getSessionCookie

public String getSessionCookie()

Specified by:

getSessionCookie in interface SessionConfig

setSessionCookie

public void setSessionCookie(String cookieName)

Specified by:

setSessionCookie in interface SessionConfig.Mutable

getSessionDomain

public String getSessionDomain()

Specified by:

getSessionDomain in interface SessionConfig

setSessionDomain

public void setSessionDomain(String domain)

Specified by:

setSessionDomain in interface SessionConfig.Mutable

setSessionCookieAttribute

public void setSessionCookieAttribute(String name,
 String value)

getSessionCookieAttribute

public String getSessionCookieAttribute(String name)

getSessionCookieAttributes

public Map<String,String> getSessionCookieAttributes()

Returns:

all of the cookie config attributes EXCEPT for those that have explicit setter/getters

getSessionIdManager

public SessionIdManager getSessionIdManager()

Specified by:

getSessionIdManager in interface SessionManager

setSessionIdManager

public void setSessionIdManager(SessionIdManager sessionIdManager)

Set up the SessionIdManager.

Specified by:

setSessionIdManager in interface SessionConfig.Mutable

Specified by:

setSessionIdManager in interface SessionManager

Parameters:

sessionIdManager - The sessionIdManager used for cross context session management.

getSessionIdPathParameterName

public String getSessionIdPathParameterName()

Specified by:

getSessionIdPathParameterName in interface SessionConfig

Returns:

the URL path parameter name for session id URL rewriting, by default "jsessionid".

See Also:

• setSessionIdPathParameterName(String)

setSessionIdPathParameterName

public void setSessionIdPathParameterName(String param)

Sets the session id URL path parameter name.

Specified by:

setSessionIdPathParameterName in interface SessionConfig.Mutable

Parameters:

param - the URL path parameter name for session id URL rewriting (null or "none" for no rewriting).

See Also:

• getSessionIdPathParameterName()
• getSessionIdPathParameterNamePrefix()

getSessionIdPathParameterNamePrefix

public String getSessionIdPathParameterNamePrefix()

Specified by:

getSessionIdPathParameterNamePrefix in interface SessionConfig

Returns:

a formatted version of getSessionIdPathParameterName(), by default ";" + sessionIdParameterName + "=", for easier lookup in URL strings.

See Also:

• getSessionIdPathParameterName()

getSessionPath

public String getSessionPath()

Specified by:

getSessionPath in interface SessionConfig

setSessionPath

public void setSessionPath(String sessionPath)

Specified by:

setSessionPath in interface SessionConfig.Mutable

getSessionTimeMean

@ManagedAttribute("mean time sessions remain valid (in s)")
public double getSessionTimeMean()

Specified by:

getSessionTimeMean in interface SessionManager

Returns:

mean amount of time session remained valid

getSessionTimeStdDev

@ManagedAttribute("standard deviation a session remained valid (in s)")
public double getSessionTimeStdDev()

Specified by:

getSessionTimeStdDev in interface SessionManager

Returns:

standard deviation of amount of time session remained valid

getSessionTimeTotal

@ManagedAttribute("total time sessions have remained valid")
public long getSessionTimeTotal()

Specified by:

getSessionTimeTotal in interface SessionManager

Returns:

total amount of time all sessions remained valid

getSessionsCreated

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

Specified by:

getSessionsCreated in interface SessionManager

encodeURI

public String encodeURI(org.eclipse.jetty.server.Request request,
 String uri,
 boolean cookiesInUse)

Specified by:

encodeURI in interface SessionManager

onSessionIdChanged

public void onSessionIdChanged(org.eclipse.jetty.server.Session session,
 String oldId)

Specified by:

onSessionIdChanged in interface SessionManager

onSessionCreated

public void onSessionCreated(org.eclipse.jetty.server.Session session)

Specified by:

onSessionCreated in interface SessionManager

onSessionDestroyed

public void onSessionDestroyed(org.eclipse.jetty.server.Session session)

Specified by:

onSessionDestroyed in interface SessionManager

invalidate

public void invalidate(String id)
                throws Exception

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.

Specified by:

invalidate in interface SessionManager

Parameters:

id - the session id to invalidate

Throws:

Exception

isCheckingRemoteSessionIdEncoding

public boolean isCheckingRemoteSessionIdEncoding()

Specified by:

isCheckingRemoteSessionIdEncoding in interface SessionConfig

Returns:

True if absolute URLs are check for remoteness before being session encoded.

setCheckingRemoteSessionIdEncoding

public void setCheckingRemoteSessionIdEncoding(boolean remote)

Specified by:

setCheckingRemoteSessionIdEncoding in interface SessionConfig.Mutable

Parameters:

remote - True if absolute URLs are check for remoteness before being session encoded.

isHttpOnly

public boolean isHttpOnly()

Specified by:

isHttpOnly in interface SessionConfig

Returns:

true if session cookies should be HTTP only

See Also:

• HttpCookie.isHttpOnly()

setHttpOnly

public void setHttpOnly(boolean httpOnly)

Set if Session cookies should use HTTP Only

Specified by:

setHttpOnly in interface SessionConfig.Mutable

Parameters:

httpOnly - True if cookies should be HttpOnly.

See Also:

• HttpCookie

isPartitioned

public boolean isPartitioned()

Specified by:

isPartitioned in interface SessionConfig

Returns:

true if session cookies should have the Partitioned attribute

See Also:

• HttpCookie.isPartitioned()

setPartitioned

public void setPartitioned(boolean partitioned)

Sets whether session cookies should have the Partitioned attribute

Specified by:

setPartitioned in interface SessionConfig.Mutable

Parameters:

partitioned - whether session cookies should have the Partitioned attribute

See Also:

• HttpCookie

isIdInUse

public boolean isIdInUse(String id)
                  throws Exception

Check if id is in use by this context

Specified by:

isIdInUse in interface SessionManager

Parameters:

id - identity of session to check

Returns:

true if this manager knows about this id

Throws:

Exception - if any error occurred

isSecureCookies

public boolean isSecureCookies()

Specified by:

isSecureCookies in interface SessionConfig

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.

setSecureCookies

public void setSecureCookies(boolean secure)

Specified by:

setSecureCookies in interface SessionConfig.Mutable

isSecureRequestOnly

public boolean isSecureRequestOnly()

Specified by:

isSecureRequestOnly in interface SessionConfig

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.

Specified by:

setSecureRequestOnly in interface SessionConfig.Mutable

Parameters:

secureRequestOnly - true to set Session Cookie Config as secure

isUsingCookies

public boolean isUsingCookies()

Specified by:

isUsingCookies in interface SessionConfig

Returns:

true if using session cookies is allowed, false otherwise

setUsingCookies

public void setUsingCookies(boolean usingCookies)

Specified by:

setUsingCookies in interface SessionConfig.Mutable

Parameters:

usingCookies - true if cookies are used to track sessions

isUsingUriParameters

public boolean isUsingUriParameters()

Specified by:

isUsingUriParameters in interface SessionConfig

Returns:

whether the session management is handled via URLs.

setUsingUriParameters

public void setUsingUriParameters(boolean usingUriParameters)

Specified by:

setUsingUriParameters in interface SessionConfig.Mutable

newSession

public void newSession(org.eclipse.jetty.server.Request request,
 String requestedSessionId,
 Consumer<ManagedSession> consumer)

Create a new Session, using the requested session id if possible.

Specified by:

newSession in interface SessionManager

Parameters:

request - the inbound request

requestedSessionId - the session id used by the request

newSessionInactivityTimer

public SessionInactivityTimer newSessionInactivityTimer(ManagedSession session)

Make a new timer for the session.

Specified by:

newSessionInactivityTimer in interface SessionManager

Parameters:

session - the session to time

recordSessionTime

public void recordSessionTime(ManagedSession session)

Record length of time session has been active. Called when the session is about to be invalidated.

Specified by:

recordSessionTime in interface SessionManager

Parameters:

session - the session whose time to record

renewSessionId

public void renewSessionId(String oldId,
 String oldExtendedId,
 String newId,
 String newExtendedId)

Change the existing session id.

Specified by:

renewSessionId in interface SessionManager

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

scavenge

public void scavenge()

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

Specified by:

scavenge in interface SessionManager

sessionTimerExpired

public void sessionTimerExpired(ManagedSession 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.

Specified by:

sessionTimerExpired in interface SessionManager

Parameters:

session - the session

now - the time at which to check for expiry

addSessionStreamWrapper

protected void addSessionStreamWrapper(org.eclipse.jetty.server.Request request)

doStop

protected void doStop()
               throws Exception

Overrides:

doStop in class org.eclipse.jetty.util.component.ContainerLifeCycle

Throws:

Exception

resolveRequestedSessionId

protected AbstractSessionManager.RequestedSession resolveRequestedSessionId(org.eclipse.jetty.server.Request request)

Find any Session associated with the Request.

Parameters:

request - The request from which to obtain the ID

getSessionCookie

public org.eclipse.jetty.http.HttpCookie getSessionCookie(ManagedSession session,
 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.

Specified by:

getSessionCookie in interface SessionManager

Parameters:

session - the session to which the cookie should refer.

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.