lib/jetty/org/eclipse/jetty/server/SessionManager.java

   1 //
   2 //  ========================================================================
   3 //  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
   4 //  ------------------------------------------------------------------------
   5 //  All rights reserved. This program and the accompanying materials
   6 //  are made available under the terms of the Eclipse Public License v1.0
   7 //  and Apache License v2.0 which accompanies this distribution.
   8 //
   9 //      The Eclipse Public License is available at
  10 //      http://www.eclipse.org/legal/epl-v10.html
  11 //
  12 //      The Apache License v2.0 is available at
  13 //      http://www.opensource.org/licenses/apache2.0.php
  14 //
  15 //  You may elect to redistribute this code under either of these licenses.
  16 //  ========================================================================
  17 //
  18
  19 package org.eclipse.jetty.server;
  20
  21 import java.util.EventListener;
  22 import java.util.Set;
  23
  24 import javax.servlet.SessionCookieConfig;
  25 import javax.servlet.SessionTrackingMode;
  26 import javax.servlet.http.HttpServletRequest;
  27 import javax.servlet.http.HttpSession;
  28
  29 import org.eclipse.jetty.http.HttpCookie;
  30 import org.eclipse.jetty.server.session.SessionHandler;
  31 import org.eclipse.jetty.util.component.LifeCycle;
  32
  33 /* --------------------------------------------------------------------- */
  34 /**
  35  * Session Manager.
  36  * The API required to manage sessions for a servlet context.
  37  *
  38  */
  39
  40 /* ------------------------------------------------------------ */
  41 /**
  42  */
  43 public interface SessionManager extends LifeCycle
  44 {
  45     /* ------------------------------------------------------------ */
  46     /**
  47      * Session cookie name.
  48      * Defaults to <code>JSESSIONID</code>, but can be set with the
  49      * <code>org.eclipse.jetty.servlet.SessionCookie</code> context init parameter.
  50      */
  51     public final static String __SessionCookieProperty = "org.eclipse.jetty.servlet.SessionCookie";
  52     public final static String __DefaultSessionCookie = "JSESSIONID";
  53
  54
  55     /* ------------------------------------------------------------ */
  56     /**
  57      * Session id path parameter name.
  58      * Defaults to <code>jsessionid</code>, but can be set with the
  59      * <code>org.eclipse.jetty.servlet.SessionIdPathParameterName</code> context init parameter.
  60      * If set to null or "none" no URL rewriting will be done.
  61      */
  62     public final static String __SessionIdPathParameterNameProperty = "org.eclipse.jetty.servlet.SessionIdPathParameterName";
  63     public final static String __DefaultSessionIdPathParameterName = "jsessionid";
  64     public final static String __CheckRemoteSessionEncoding = "org.eclipse.jetty.servlet.CheckingRemoteSessionIdEncoding";
  65
  66
  67     /* ------------------------------------------------------------ */
  68     /**
  69      * Session Domain.
  70      * If this property is set as a ServletContext InitParam, then it is
  71      * used as the domain for session cookies. If it is not set, then
  72      * no domain is specified for the session cookie.
  73      */
  74     public final static String __SessionDomainProperty = "org.eclipse.jetty.servlet.SessionDomain";
  75     public final static String __DefaultSessionDomain = null;
  76
  77
  78     /* ------------------------------------------------------------ */
  79     /**
  80      * Session Path.
  81      * If this property is set as a ServletContext InitParam, then it is
  82      * used as the path for the session cookie.  If it is not set, then
  83      * the context path is used as the path for the cookie.
  84      */
  85     public final static String __SessionPathProperty = "org.eclipse.jetty.servlet.SessionPath";
  86
  87     /* ------------------------------------------------------------ */
  88     /**
  89      * Session Max Age.
  90      * If this property is set as a ServletContext InitParam, then it is
  91      * used as the max age for the session cookie.  If it is not set, then
  92      * a max age of -1 is used.
  93      */
  94     public final static String __MaxAgeProperty = "org.eclipse.jetty.servlet.MaxAge";
  95
  96     /* ------------------------------------------------------------ */
  97     /**
  98      * Returns the <code>HttpSession</code> with the given session id
  99      *
 100      * @param id the session id
 101      * @return the <code>HttpSession</code> with the corresponding id or null if no session with the given id exists
 102      */
 103     public HttpSession getHttpSession(String id);
 104
 105     /* ------------------------------------------------------------ */
 106     /**
 107      * Creates a new <code>HttpSession</code>.
 108      *
 109      * @param request the HttpServletRequest containing the requested session id
 110      * @return the new <code>HttpSession</code>
 111      */
 112     public HttpSession newHttpSession(HttpServletRequest request);
 113
 114
 115     /* ------------------------------------------------------------ */
 116     /**
 117      * @return true if session cookies should be HTTP-only (Microsoft extension)
 118      * @see org.eclipse.jetty.http.HttpCookie#isHttpOnly()
 119      */
 120     public boolean getHttpOnly();
 121
 122     /* ------------------------------------------------------------ */
 123     /**
 124      * @return the max period of inactivity, after which the session is invalidated, in seconds.
 125      * @see #setMaxInactiveInterval(int)
 126      */
 127     public int getMaxInactiveInterval();
 128
 129     /* ------------------------------------------------------------ */
 130     /**
 131      * Sets the max period of inactivity, after which the session is invalidated, in seconds.
 132      *
 133      * @param seconds the max inactivity period, in seconds.
 134      * @see #getMaxInactiveInterval()
 135      */
 136     public void setMaxInactiveInterval(int seconds);
 137
 138     /* ------------------------------------------------------------ */
 139     /**
 140      * Sets the {@link SessionHandler}.
 141      *
 142      * @param handler the <code>SessionHandler</code> object
 143      */
 144     public void setSessionHandler(SessionHandler handler);
 145
 146     /* ------------------------------------------------------------ */
 147     /**
 148      * Adds an event listener for session-related events.
 149      *
 150      * @param listener the session event listener to add
 151      *                 Individual SessionManagers implementations may accept arbitrary listener types,
 152      *                 but they are expected to at least handle HttpSessionActivationListener,
 153      *                 HttpSessionAttributeListener, HttpSessionBindingListener and HttpSessionListener.
 154      * @see #removeEventListener(EventListener)
 155      */
 156     public void addEventListener(EventListener listener);
 157
 158     /* ------------------------------------------------------------ */
 159     /**
 160      * Removes an event listener for for session-related events.
 161      *
 162      * @param listener the session event listener to remove
 163      * @see #addEventListener(EventListener)
 164      */
 165     public void removeEventListener(EventListener listener);
 166
 167     /* ------------------------------------------------------------ */
 168     /**
 169      * Removes all event listeners for session-related events.
 170      *
 171      * @see #removeEventListener(EventListener)
 172      */
 173     public void clearEventListeners();
 174
 175     /* ------------------------------------------------------------ */
 176     /**
 177      * Gets a Cookie for a session.
 178      *
 179      * @param session         the session to which the cookie should refer.
 180      * @param contextPath     the context to which the cookie should be linked.
 181      *                        The client will only send the cookie value when requesting resources under this path.
 182      * @param requestIsSecure whether the client is accessing the server over a secure protocol (i.e. HTTPS).
 183      * @return if this <code>SessionManager</code> uses cookies, then this method will return a new
 184      *         {@link Cookie cookie object} that should be set on the client in order to link future HTTP requests
 185      *         with the <code>session</code>. If cookies are not in use, this method returns <code>null</code>.
 186      */
 187     public HttpCookie getSessionCookie(HttpSession session, String contextPath, boolean requestIsSecure);
 188
 189     /* ------------------------------------------------------------ */
 190     /**
 191      * @return the cross context session id manager.
 192      * @see #setSessionIdManager(SessionIdManager)
 193      */
 194     public SessionIdManager getSessionIdManager();
 195
 196     /* ------------------------------------------------------------ */
 197     /**
 198      * @return the cross context session id manager.
 199      * @deprecated use {@link #getSessionIdManager()}
 200      */
 201     @Deprecated
 202     public SessionIdManager getMetaManager();
 203
 204     /* ------------------------------------------------------------ */
 205     /**
 206      * Sets the cross context session id manager
 207      *
 208      * @param idManager the cross context session id manager.
 209      * @see #getSessionIdManager()
 210      */
 211     public void setSessionIdManager(SessionIdManager idManager);
 212
 213     /* ------------------------------------------------------------ */
 214     /**
 215      * @param session the session to test for validity
 216      * @return whether the given session is valid, that is, it has not been invalidated.
 217      */
 218     public boolean isValid(HttpSession session);
 219
 220     /* ------------------------------------------------------------ */
 221     /**
 222      * @param session the session object
 223      * @return the unique id of the session within the cluster, extended with an optional node id.
 224      * @see #getClusterId(HttpSession)
 225      */
 226     public String getNodeId(HttpSession session);
 227
 228     /* ------------------------------------------------------------ */
 229     /**
 230      * @param session the session object
 231      * @return the unique id of the session within the cluster (without a node id extension)
 232      * @see #getNodeId(HttpSession)
 233      */
 234     public String getClusterId(HttpSession session);
 235
 236     /* ------------------------------------------------------------ */
 237     /**
 238      * Called by the {@link SessionHandler} when a session is first accessed by a request.
 239      *
 240      * @param session the session object
 241      * @param secure  whether the request is secure or not
 242      * @return the session cookie. If not null, this cookie should be set on the response to either migrate
 243      *         the session or to refresh a session cookie that may expire.
 244      * @see #complete(HttpSession)
 245      */
 246     public HttpCookie access(HttpSession session, boolean secure);
 247
 248     /* ------------------------------------------------------------ */
 249     /**
 250      * Called by the {@link SessionHandler} when a session is last accessed by a request.
 251      *
 252      * @param session the session object
 253      * @see #access(HttpSession, boolean)
 254      */
 255     public void complete(HttpSession session);
 256
 257     /**
 258      * Sets the session id URL path parameter name.
 259      *
 260      * @param parameterName the URL path parameter name for session id URL rewriting (null or "none" for no rewriting).
 261      * @see #getSessionIdPathParameterName()
 262      * @see #getSessionIdPathParameterNamePrefix()
 263      */
 264     public void setSessionIdPathParameterName(String parameterName);
 265
 266     /**
 267      * @return the URL path parameter name for session id URL rewriting, by default "jsessionid".
 268      * @see #setSessionIdPathParameterName(String)
 269      */
 270     public String getSessionIdPathParameterName();
 271
 272     /**
 273      * @return a formatted version of {@link #getSessionIdPathParameterName()}, by default
 274      *         ";" + sessionIdParameterName + "=", for easier lookup in URL strings.
 275      * @see #getSessionIdPathParameterName()
 276      */
 277     public String getSessionIdPathParameterNamePrefix();
 278
 279     /**
 280      * @return whether the session management is handled via cookies.
 281      */
 282     public boolean isUsingCookies();
 283
 284     /**
 285      * @return whether the session management is handled via URLs.
 286      */
 287     public boolean isUsingURLs();
 288
 289     public Set<SessionTrackingMode> getDefaultSessionTrackingModes();
 290
 291     public Set<SessionTrackingMode> getEffectiveSessionTrackingModes();
 292
 293     public void setSessionTrackingModes(Set<SessionTrackingMode> sessionTrackingModes);
 294
 295     public SessionCookieConfig getSessionCookieConfig();
 296
 297     /**
 298      * @return True if absolute URLs are check for remoteness before being session encoded.
 299      */
 300     public boolean isCheckingRemoteSessionIdEncoding();
 301
 302     /**
 303      * @param remote True if absolute URLs are check for remoteness before being session encoded.
 304      */
 305     public void setCheckingRemoteSessionIdEncoding(boolean remote);
 306
 307     /* ------------------------------------------------------------ */
 308     /** Change the existing session id.
 309     *
 310     * @param oldClusterId
 311     * @param oldNodeId
 312     * @param newClusterId
 313     * @param newNodeId
 314     */
 315     public void renewSessionId(String oldClusterId, String oldNodeId, String newClusterId, String newNodeId);
 316 }