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.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 }