Updates to session javadoc
This commit is contained in:
Jan Bartel
parent
e87557e527
commit
4ac821d582
|
|
@ -27,6 +27,7 @@ import org.eclipse.jetty.util.component.LifeCycle;
|
|||
|
||||
/**
|
||||
* Session ID Manager.
|
||||
*
|
||||
* Manages session IDs across multiple contexts.
|
||||
*/
|
||||
public interface SessionIdManager extends LifeCycle
|
||||
|
|
|
|||
|
|
@ -33,22 +33,21 @@ import org.eclipse.jetty.util.thread.Locker.Lock;
|
|||
/**
|
||||
* AbstractSessionCache
|
||||
*
|
||||
* A base implementation of the SessionCache interface for managing a set of
|
||||
* A base implementation of the {@link SessionCache} interface for managing a set of
|
||||
* Session objects pertaining to a context in memory.
|
||||
*
|
||||
* This implementation ensures that multiple requests for the same session id
|
||||
* always return the same Session object.
|
||||
*
|
||||
* It will delay writing out a session to the SessionDataStore until the
|
||||
* last request exists the session. If the SessionDataStore supports passivation
|
||||
* last request exits the session. If the SessionDataStore supports passivation
|
||||
* then the session passivation and activation listeners are called appropriately as
|
||||
* the session is written. Additionally the session can be evicted from the
|
||||
* AbstractSessionCache after passivation on write.
|
||||
* the session is written.
|
||||
*
|
||||
* This implementation also supports evicting idle Session objects. An idle Session
|
||||
* is one that is still valid, has not expired, but has not been accessed by a
|
||||
* request for a configurable amount of time. An idle session will be first
|
||||
* passivated before eviction from the cache.
|
||||
* passivated before it is evicted from the cache.
|
||||
*
|
||||
*/
|
||||
public abstract class AbstractSessionCache extends ContainerLifeCycle implements SessionCache
|
||||
|
|
@ -89,6 +88,10 @@ public abstract class AbstractSessionCache extends ContainerLifeCycle implements
|
|||
protected boolean _saveOnInactiveEviction;
|
||||
|
||||
|
||||
/**
|
||||
* If true, a Session whose data cannot be read will be
|
||||
* deleted from the SessionDataStore.
|
||||
*/
|
||||
protected boolean _removeUnloadableSessions;
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -37,12 +37,16 @@ import org.eclipse.jetty.util.log.Logger;
|
|||
|
||||
|
||||
/**
|
||||
* AbstractSessionIdManager
|
||||
* DefaultSessionIdManager
|
||||
*
|
||||
* Manages session ids to ensure each session id within a context is unique, and that
|
||||
* session ids can be shared across contexts (but not session contents).
|
||||
*
|
||||
* There is only 1 session id manager per Server instance.
|
||||
*
|
||||
* Runs a HouseKeeper thread to periodically check for expired Sessions.
|
||||
*
|
||||
* @See HouseKeeper
|
||||
*/
|
||||
public class DefaultSessionIdManager extends AbstractLifeCycle implements SessionIdManager
|
||||
{
|
||||
|
|
|
|||
|
|
@ -47,7 +47,18 @@ import org.eclipse.jetty.util.thread.Locker.Lock;
|
|||
/**
|
||||
* Session
|
||||
*
|
||||
*
|
||||
* A heavy-weight Session object representing a HttpSession. Session objects
|
||||
* relating to a context are kept in a {@link SessionCache}. The purpose of
|
||||
* the SessionCache is to keep the working set of Session objects in memory
|
||||
* so that they may be accessed quickly, and facilitate the sharing of a
|
||||
* Session object amongst multiple simultaneous requests referring to the
|
||||
* same session id.
|
||||
*
|
||||
* The {@link SessionHandler} coordinates
|
||||
* the lifecycle of Session objects with the help of the SessionCache.
|
||||
*
|
||||
* @see SessionHandler
|
||||
* @see org.eclipse.jetty.server.SessionIdManager
|
||||
*/
|
||||
public class Session implements SessionHandler.SessionIf
|
||||
{
|
||||
|
|
@ -87,13 +98,16 @@ public class Session implements SessionHandler.SessionIf
|
|||
/* ------------------------------------------------------------- */
|
||||
/**
|
||||
* SessionInactivityTimeout
|
||||
*
|
||||
*
|
||||
* Each Session has a timer associated with it that fires whenever
|
||||
* it has been idle (ie not referenced by a request) for a
|
||||
* configurable amount of time, or the Session expires.
|
||||
*
|
||||
* @see SessionCache
|
||||
*
|
||||
*/
|
||||
public class SessionInactivityTimeout extends IdleTimeout
|
||||
{
|
||||
|
||||
|
||||
/**
|
||||
*
|
||||
*/
|
||||
|
|
@ -146,7 +160,7 @@ public class Session implements SessionHandler.SessionIf
|
|||
/* ------------------------------------------------------------- */
|
||||
/**
|
||||
* Create a new session
|
||||
* @param handler TODO
|
||||
* @param handler the SessionHandler that manages this session
|
||||
* @param request the request the session should be based on
|
||||
* @param data the session data
|
||||
*/
|
||||
|
|
@ -162,8 +176,9 @@ public class Session implements SessionHandler.SessionIf
|
|||
|
||||
/* ------------------------------------------------------------- */
|
||||
/**
|
||||
* Re-create an existing session
|
||||
* @param handler TODO
|
||||
* Re-inflate an existing session from some eg persistent store.
|
||||
*
|
||||
* @param handler the SessionHandler managing the session
|
||||
* @param data the session data
|
||||
*/
|
||||
public Session (SessionHandler handler, SessionData data)
|
||||
|
|
@ -175,9 +190,9 @@ public class Session implements SessionHandler.SessionIf
|
|||
|
||||
/* ------------------------------------------------------------- */
|
||||
/**
|
||||
* Should call this method with a lock held if you want to
|
||||
* make decision on what to do with the session
|
||||
*
|
||||
* Returns the current number of requests that are active in the
|
||||
* Session.
|
||||
*
|
||||
* @return the number of active requests for this session
|
||||
*/
|
||||
public long getRequests()
|
||||
|
|
@ -242,7 +257,8 @@ public class Session implements SessionHandler.SessionIf
|
|||
|
||||
/* ------------------------------------------------------------- */
|
||||
/** Check to see if session has expired as at the time given.
|
||||
* @param time the time in milliseconds
|
||||
*
|
||||
* @param time the time since the epoch in ms
|
||||
* @return true if expired
|
||||
*/
|
||||
protected boolean isExpiredAt(long time)
|
||||
|
|
@ -254,6 +270,12 @@ public class Session implements SessionHandler.SessionIf
|
|||
}
|
||||
|
||||
|
||||
/* ------------------------------------------------------------- */
|
||||
/** Check if the Session has been idle longer than a number of seconds.
|
||||
*
|
||||
* @param sec the number of seconds
|
||||
* @return true if the session has been idle longer than the interval
|
||||
*/
|
||||
protected boolean isIdleLongerThan (int sec)
|
||||
{
|
||||
long now = System.currentTimeMillis();
|
||||
|
|
@ -320,7 +342,7 @@ public class Session implements SessionHandler.SessionIf
|
|||
/* ------------------------------------------------------------- */
|
||||
/**
|
||||
* Call the activation listeners. This must be called holding the
|
||||
* _lock.
|
||||
* lock.
|
||||
*/
|
||||
public void didActivate()
|
||||
{
|
||||
|
|
@ -340,7 +362,7 @@ public class Session implements SessionHandler.SessionIf
|
|||
/* ------------------------------------------------------------- */
|
||||
/**
|
||||
* Call the passivation listeners. This must be called holding the
|
||||
* _lock
|
||||
* lock
|
||||
*/
|
||||
public void willPassivate()
|
||||
{
|
||||
|
|
@ -573,7 +595,8 @@ public class Session implements SessionHandler.SessionIf
|
|||
|
||||
/* ------------------------------------------------------------- */
|
||||
/**
|
||||
* asserts that the session is valid
|
||||
* Check that the session can be modified.
|
||||
*
|
||||
* @throws IllegalStateException if the session is invalid
|
||||
*/
|
||||
protected void checkValidForWrite() throws IllegalStateException
|
||||
|
|
@ -590,7 +613,8 @@ public class Session implements SessionHandler.SessionIf
|
|||
|
||||
/* ------------------------------------------------------------- */
|
||||
/**
|
||||
* asserts that the session is valid
|
||||
* Chech that the session data can be read.
|
||||
*
|
||||
* @throws IllegalStateException if the session is invalid
|
||||
*/
|
||||
protected void checkValidForRead () throws IllegalStateException
|
||||
|
|
@ -764,6 +788,10 @@ public class Session implements SessionHandler.SessionIf
|
|||
}
|
||||
|
||||
/* ------------------------------------------------------------ */
|
||||
/** Force a change to the id of a session.
|
||||
*
|
||||
* @param request the Request associated with the call to change id.
|
||||
*/
|
||||
public void renewId(HttpServletRequest request)
|
||||
{
|
||||
if (_handler == null)
|
||||
|
|
@ -846,6 +874,11 @@ public class Session implements SessionHandler.SessionIf
|
|||
}
|
||||
|
||||
/* ------------------------------------------------------------- */
|
||||
/** Call HttpSessionAttributeListeners as part of invalidating
|
||||
* a Session.
|
||||
*
|
||||
* @throws IllegalStateException
|
||||
*/
|
||||
protected void doInvalidate() throws IllegalStateException
|
||||
{
|
||||
try (Lock lock = _lock.lockIfNotHeld())
|
||||
|
|
@ -928,12 +961,13 @@ public class Session implements SessionHandler.SessionIf
|
|||
return _sessionData;
|
||||
}
|
||||
|
||||
|
||||
/* ------------------------------------------------------------- */
|
||||
public void setResident (boolean resident)
|
||||
{
|
||||
_resident = resident;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------- */
|
||||
public boolean isResident ()
|
||||
{
|
||||
return _resident;
|
||||
|
|
|
|||
|
|
@ -28,28 +28,31 @@ import org.eclipse.jetty.util.component.LifeCycle;
|
|||
/**
|
||||
* SessionCache
|
||||
*
|
||||
* A set of Session objects for a context that are actively being
|
||||
* managed by this context instance.
|
||||
* A working set of {@link Session} objects for a context.
|
||||
*
|
||||
* Multiple requests for the same session id on the same context should always
|
||||
* share the same Session object from the SessionCache.
|
||||
* 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 data for the Session objects is obtained from, and written to a SessionDataStore.
|
||||
* It is assumed that the SessionDataStore is the authoritative source of session data:
|
||||
* The SessionData pertaining to the Session objects is obtained from/written to a SessionDataStore.
|
||||
* The SessionDataStore is the authoritative source of session data:
|
||||
* <ul>
|
||||
* <li>if the session data is not present in the SessionDataStore the session does not exist.</li>
|
||||
* <li>if the session data is present in the SessionDataStore but its expiry time has passed then
|
||||
* the session is deemed to have expired</li>
|
||||
* the session is deemed to have expired and is therefore invalid</li>
|
||||
*</ul>
|
||||
*
|
||||
* Examples of SessionDataStores are relational or nosql databases, filesystems, or other
|
||||
* distributed mechanisms.
|
||||
* A SessionCache can passivate a valid Session to the SessionDataStore and
|
||||
* evict it from the cache according to various strategies:
|
||||
* <ul>
|
||||
* <li>whenever the last request exits a Session</li>
|
||||
* <li>whenever the Session has not been accessed for a configurable number of seconds</li>
|
||||
* </ul>.
|
||||
*
|
||||
* A SessionCache is optionally able to passivate a managed Session to the SessionDataStore and
|
||||
* evict it from the cache if it has been in memory, but not accessed for a configurable amount of time.
|
||||
* 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.
|
||||
*
|
||||
* Implementations of the SessionCache may also implement different strategies for writing out
|
||||
* Session data to the SessionDataStore.
|
||||
*/
|
||||
public interface SessionCache extends LifeCycle
|
||||
{
|
||||
|
|
@ -59,27 +62,177 @@ public interface SessionCache extends LifeCycle
|
|||
|
||||
|
||||
|
||||
/**
|
||||
* @param context
|
||||
*/
|
||||
void initialize(SessionContext context);
|
||||
SessionHandler getSessionHandler();
|
||||
Session newSession (HttpServletRequest request, String id, long time, long maxInactiveMs);
|
||||
Session newSession (SessionData data);
|
||||
Session renewSessionId (String oldId, String newId) throws Exception;
|
||||
Session get(String id) throws Exception;
|
||||
void put(String id, Session session) throws Exception;
|
||||
boolean contains (String id) throws Exception;
|
||||
boolean exists (String id) throws Exception;
|
||||
Session delete (String id) throws Exception;
|
||||
|
||||
void shutdown ();
|
||||
|
||||
|
||||
SessionHandler getSessionHandler();
|
||||
|
||||
|
||||
/**
|
||||
* Create an entirely new Session.
|
||||
*
|
||||
* @param request
|
||||
* @param id
|
||||
* @param time
|
||||
* @param maxInactiveMs
|
||||
* @return
|
||||
*/
|
||||
Session newSession (HttpServletRequest request, String id, long time, long maxInactiveMs);
|
||||
|
||||
/**
|
||||
* Re-inflate a Session that has previously existed.
|
||||
* @param data
|
||||
* @return
|
||||
*/
|
||||
Session newSession (SessionData data);
|
||||
|
||||
|
||||
/**
|
||||
* Change the id of a Session.
|
||||
*
|
||||
* @param oldId
|
||||
* @param newId
|
||||
* @return
|
||||
* @throws Exception
|
||||
*/
|
||||
Session renewSessionId (String oldId, String newId) throws Exception;
|
||||
|
||||
|
||||
/**
|
||||
* Get an existing Session. If necessary, the cache will load the data for
|
||||
* the session from the configured SessionDataStore.
|
||||
*
|
||||
* @param id
|
||||
* @return
|
||||
* @throws Exception
|
||||
*/
|
||||
Session get(String id) throws 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.
|
||||
*
|
||||
* @param id
|
||||
* @param session
|
||||
* @throws Exception
|
||||
*/
|
||||
void put(String id, Session session) throws Exception;
|
||||
|
||||
|
||||
/**
|
||||
* Check to see if a Session is in the cache. Does NOT consult
|
||||
* the SessionDataStore.
|
||||
*
|
||||
* @param id
|
||||
* @return true if a Session object matching the id is present
|
||||
* in the cache, false otherwise
|
||||
* @throws Exception
|
||||
*/
|
||||
boolean contains (String id) throws Exception;
|
||||
|
||||
|
||||
/**
|
||||
* Check to see if a session exists: WILL consult the
|
||||
* SessionDataStore.
|
||||
*
|
||||
* @param id
|
||||
* @return
|
||||
* @throws Exception
|
||||
*/
|
||||
boolean exists (String id) throws Exception;
|
||||
|
||||
|
||||
/**
|
||||
* Remove a Session completely: from both this
|
||||
* cache and the SessionDataStore.
|
||||
*
|
||||
* @param id
|
||||
* @return
|
||||
* @throws Exception
|
||||
*/
|
||||
Session delete (String id) throws Exception;
|
||||
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @param candidates the session ids to check
|
||||
* @return the set of session ids that have actually expired: this can
|
||||
* be a superset of the original candidate list.
|
||||
*/
|
||||
Set<String> checkExpiration (Set<String> candidates);
|
||||
SessionDataStore getSessionDataStore();
|
||||
void setSessionDataStore(SessionDataStore sds);
|
||||
|
||||
/**
|
||||
* Check a Session to see if it might be appropriate to
|
||||
* evict or expire.
|
||||
*
|
||||
* @param session
|
||||
*/
|
||||
void checkInactiveSession(Session session);
|
||||
|
||||
|
||||
/**
|
||||
* A SessionDataStore that is the authoritative source
|
||||
* of session information.
|
||||
* @param sds
|
||||
*/
|
||||
void setSessionDataStore(SessionDataStore sds);
|
||||
SessionDataStore getSessionDataStore();
|
||||
|
||||
|
||||
/**
|
||||
* Sessions in this cache can be:
|
||||
* <ul>
|
||||
* <li>never evicted</li>
|
||||
* <li>evicted once the last request exits</li>
|
||||
* <li>evicted after a configurable period of inactivity</li>
|
||||
* </ul>
|
||||
*
|
||||
* @param -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.
|
||||
*/
|
||||
void setEvictionPolicy (int policy);
|
||||
int getEvictionPolicy ();
|
||||
|
||||
/**
|
||||
* Whether or not a a session that is about to be evicted should
|
||||
* be saved before being evicted.
|
||||
*
|
||||
* @param saveOnEvict
|
||||
*/
|
||||
void setSaveOnInactiveEviction (boolean saveOnEvict);
|
||||
boolean isSaveOnInactiveEviction ();
|
||||
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @param saveOnCreate
|
||||
*/
|
||||
void setSaveOnCreate(boolean saveOnCreate);
|
||||
boolean isSaveOnCreate();
|
||||
|
||||
|
||||
/**
|
||||
* If the data for a session exists but is unreadable,
|
||||
* the SessionCache can instruct the SessionDataStore to delete it.
|
||||
*
|
||||
* @param removeUnloadableSessions
|
||||
*/
|
||||
void setRemoveUnloadableSessions(boolean removeUnloadableSessions);
|
||||
boolean isRemoveUnloadableSessions();
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1285,10 +1285,7 @@ public class SessionHandler extends ScopedHandler
|
|||
* when either the session has not been accessed for a
|
||||
* configurable amount of time, or the session itself
|
||||
* has passed its expiry.
|
||||
* <ul>
|
||||
* <li> for being expired </li>
|
||||
* <li> for being idle </li>
|
||||
* </ul>
|
||||
*
|
||||
* @param session
|
||||
*/
|
||||
public void sessionInactivityTimerExpired (Session session)
|
||||
|
|
|
|||
Loading…
Reference in New Issue