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