jetty/server/SessionManager.java

0001 //
0002 //  ========================================================================
0003 //  Copyright (c) 1995-2018 Mort Bay Consulting Pty. Ltd.
0004 //  ------------------------------------------------------------------------
0005 //  All rights reserved. This program and the accompanying materials
0006 //  are made available under the terms of the Eclipse Public License v1.0
0007 //  and Apache License v2.0 which accompanies this distribution.
0008 //
0009 //      The Eclipse Public License is available at
0010 //      http://www.eclipse.org/legal/epl-v10.html
0011 //
0012 //      The Apache License v2.0 is available at
0013 //      http://www.opensource.org/licenses/apache2.0.php
0014 //
0015 //  You may elect to redistribute this code under either of these licenses.
0016 //  ========================================================================
0017 //
0018
0019 package org.eclipse.jetty.server;
0020
0021 import javax.servlet.SessionCookieConfig;
0022 import javax.servlet.SessionTrackingMode;
0023 import javax.servlet.http.Cookie;
0024 import javax.servlet.http.HttpServletRequest;
0025 import javax.servlet.http.HttpSession;
0026 import java.util.EventListener;
0027 import java.util.Set;
0028
0029 import org.eclipse.jetty.http.HttpCookie;
0030 import org.eclipse.jetty.server.session.SessionHandler;
0031 import org.eclipse.jetty.util.component.LifeCycle;
0032
0033 /**
0034  * Adapted from https://github.com/eclipse/jetty.project/blob/jetty-9.3.25.v20180904/
0035  *   jetty-server/src/main/java/org/eclipse/jetty/server/SessionManager.java
0036  */
0037 public interface SessionManager extends LifeCycle {
0038   /**
0039    * Session cookie name.
0040    * Defaults to <code>JSESSIONID</code>, but can be set with the
0041    * <code>org.eclipse.jetty.servlet.SessionCookie</code> context init parameter.
0042    */
0043   String __SessionCookieProperty = "org.eclipse.jetty.servlet.SessionCookie";
0044   String __DefaultSessionCookie = "JSESSIONID";
0045
0046   /**
0047    * Session id path parameter name.
0048    * Defaults to <code>jsessionid</code>, but can be set with the
0049    * <code>org.eclipse.jetty.servlet.SessionIdPathParameterName</code> context init parameter.
0050    * If set to null or "none" no URL rewriting will be done.
0051    */
0052   String __SessionIdPathParameterNameProperty =
0053     "org.eclipse.jetty.servlet.SessionIdPathParameterName";
0054   String __DefaultSessionIdPathParameterName = "jsessionid";
0055   String __CheckRemoteSessionEncoding = "org.eclipse.jetty.servlet.CheckingRemoteSessionIdEncoding";
0056
0057   /**
0058    * Session Domain.
0059    * If this property is set as a ServletContext InitParam, then it is
0060    * used as the domain for session cookies. If it is not set, then
0061    * no domain is specified for the session cookie.
0062    */
0063   String __SessionDomainProperty = "org.eclipse.jetty.servlet.SessionDomain";
0064   String __DefaultSessionDomain = null;
0065
0066   /**
0067    * Session Path.
0068    * If this property is set as a ServletContext InitParam, then it is
0069    * used as the path for the session cookie.  If it is not set, then
0070    * the context path is used as the path for the cookie.
0071    */
0072   String __SessionPathProperty = "org.eclipse.jetty.servlet.SessionPath";
0073
0074   /**
0075    * Session Max Age.
0076    * If this property is set as a ServletContext InitParam, then it is
0077    * used as the max age for the session cookie.  If it is not set, then
0078    * a max age of -1 is used.
0079    */
0080   String __MaxAgeProperty = "org.eclipse.jetty.servlet.MaxAge";
0081
0082   /**
0083    * Returns the <code>HttpSession</code> with the given session id
0084    *
0085    * @param id the session id
0086    * @return the <code>HttpSession</code> with the corresponding id
0087    *         or null if no session with the given id exists
0088    */
0089   HttpSession getHttpSession(String id);
0090
0091   /**
0092    * Creates a new <code>HttpSession</code>.
0093    *
0094    * @param request the HttpServletRequest containing the requested session id
0095    * @return the new <code>HttpSession</code>
0096    */
0097   HttpSession newHttpSession(HttpServletRequest request);
0098
0099   /**
0100    * @return true if session cookies should be HTTP-only (Microsoft extension)
0101    * @see HttpCookie#isHttpOnly()
0102    */
0103   boolean getHttpOnly();
0104
0105   /**
0106    * @return the max period of inactivity, after which the session is invalidated, in seconds.
0107    * @see #setMaxInactiveInterval(int)
0108    */
0109   int getMaxInactiveInterval();
0110
0111   /**
0112    * Sets the max period of inactivity, after which the session is invalidated, in seconds.
0113    *
0114    * @param seconds the max inactivity period, in seconds.
0115    * @see #getMaxInactiveInterval()
0116    */
0117   void setMaxInactiveInterval(int seconds);
0118
0119   /**
0120    * Sets the {@link SessionHandler}.
0121    *
0122    * @param handler the <code>SessionHandler</code> object
0123    */
0124   void setSessionHandler(SessionHandler handler);
0125
0126   /**
0127    * Adds an event listener for session-related events.
0128    *
0129    * @param listener the session event listener to add
0130    *                 Individual SessionManagers implementations may accept arbitrary listener types,
0131    *                 but they are expected to at least handle HttpSessionActivationListener,
0132    *                 HttpSessionAttributeListener,
0133    *                 HttpSessionBindingListener and HttpSessionListener.
0134    * @see #removeEventListener(EventListener)
0135    */
0136   void addEventListener(EventListener listener);
0137
0138   /**
0139    * Removes an event listener for for session-related events.
0140    *
0141    * @param listener the session event listener to remove
0142    * @see #addEventListener(EventListener)
0143    */
0144   void removeEventListener(EventListener listener);
0145
0146   /**
0147    * Removes all event listeners for session-related events.
0148    *
0149    * @see #removeEventListener(EventListener)
0150    */
0151   void clearEventListeners();
0152
0153   /**
0154    * Gets a Cookie for a session.
0155    *
0156    * @param session         the session to which the cookie should refer.
0157    * @param contextPath     the context to which the cookie should be linked.
0158    *                        The client will only send the cookie value when
0159    *                        requesting resources under this path.
0160    * @param requestIsSecure whether the client is accessing the server over
0161    *                        a secure protocol (i.e. HTTPS).
0162    * @return if this <code>SessionManager</code> uses cookies, then this method will return a new
0163    *         {@link Cookie cookie object} that should be set on the client
0164    *         in order to link future HTTP requests
0165    *         with the <code>session</code>. If cookies are not in use,
0166    *         this method returns <code>null</code>.
0167    */
0168   HttpCookie getSessionCookie(HttpSession session, String contextPath, boolean requestIsSecure);
0169
0170   /**
0171    * @return the cross context session id manager.
0172    * @see #setSessionIdManager(SessionIdManager)
0173    */
0174   SessionIdManager getSessionIdManager();
0175
0176   /**
0177    * @return the cross context session id manager.
0178    * @deprecated use {@link #getSessionIdManager()}
0179    */
0180   @Deprecated
0181   SessionIdManager getMetaManager();
0182
0183   /**
0184    * Sets the cross context session id manager
0185    *
0186    * @param idManager the cross context session id manager.
0187    * @see #getSessionIdManager()
0188    */
0189   void setSessionIdManager(SessionIdManager idManager);
0190
0191   /**
0192    * @param session the session to test for validity
0193    * @return whether the given session is valid, that is, it has not been invalidated.
0194    */
0195   boolean isValid(HttpSession session);
0196
0197   /**
0198    * @param session the session object
0199    * @return the unique id of the session within the cluster, extended with an optional node id.
0200    * @see #getClusterId(HttpSession)
0201    */
0202   String getNodeId(HttpSession session);
0203
0204   /**
0205    * @param session the session object
0206    * @return the unique id of the session within the cluster (without a node id extension)
0207    * @see #getNodeId(HttpSession)
0208    */
0209   String getClusterId(HttpSession session);
0210
0211   /**
0212    * Called by the {@link SessionHandler} when a session is first accessed by a request.
0213    *
0214    * @param session the session object
0215    * @param secure  whether the request is secure or not
0216    * @return the session cookie. If not null,
0217    *         this cookie should be set on the response to either migrate
0218    *         the session or to refresh a session cookie that may expire.
0219    * @see #complete(HttpSession)
0220    */
0221   HttpCookie access(HttpSession session, boolean secure);
0222
0223   /**
0224    * Called by the {@link SessionHandler} when a session is last accessed by a request.
0225    *
0226    * @param session the session object
0227    * @see #access(HttpSession, boolean)
0228    */
0229   void complete(HttpSession session);
0230
0231   /**
0232    * Sets the session id URL path parameter name.
0233    *
0234    * @param parameterName the URL path parameter name
0235    *                      for session id URL rewriting (null or "none" for no rewriting).
0236    * @see #getSessionIdPathParameterName()
0237    * @see #getSessionIdPathParameterNamePrefix()
0238    */
0239   void setSessionIdPathParameterName(String parameterName);
0240
0241   /**
0242    * @return the URL path parameter name for session id URL rewriting, by default "jsessionid".
0243    * @see #setSessionIdPathParameterName(String)
0244    */
0245   String getSessionIdPathParameterName();
0246
0247   /**
0248    * @return a formatted version of {@link #getSessionIdPathParameterName()}, by default
0249    *         ";" + sessionIdParameterName + "=", for easier lookup in URL strings.
0250    * @see #getSessionIdPathParameterName()
0251    */
0252   String getSessionIdPathParameterNamePrefix();
0253
0254   /**
0255    * @return whether the session management is handled via cookies.
0256    */
0257   boolean isUsingCookies();
0258
0259   /**
0260    * @return whether the session management is handled via URLs.
0261    */
0262   boolean isUsingURLs();
0263
0264   Set<SessionTrackingMode> getDefaultSessionTrackingModes();
0265
0266   Set<SessionTrackingMode> getEffectiveSessionTrackingModes();
0267
0268   void setSessionTrackingModes(Set<SessionTrackingMode> sessionTrackingModes);
0269
0270   SessionCookieConfig getSessionCookieConfig();
0271
0272   /**
0273    * @return True if absolute URLs are check for remoteness before being session encoded.
0274    */
0275   boolean isCheckingRemoteSessionIdEncoding();
0276
0277   /**
0278    * @param remote True if absolute URLs are check for remoteness before being session encoded.
0279    */
0280   void setCheckingRemoteSessionIdEncoding(boolean remote);
0281
0282   /** Change the existing session id.
0283    *
0284    * @param oldClusterId the old cluster id
0285    * @param oldNodeId the old node id
0286    * @param newClusterId the new cluster id
0287    * @param newNodeId the new node id
0288    */
0289   void renewSessionId(String oldClusterId, String oldNodeId, String newClusterId, String newNodeId);
0290 }