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

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