1 // ======================================================================== 2 // Copyright 1996-2005 Mort Bay Consulting Pty. Ltd. 3 // ------------------------------------------------------------------------ 4 // Licensed under the Apache License, Version 2.0 (the "License"); 5 // you may not use this file except in compliance with the License. 6 // You may obtain a copy of the License at 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // Unless required by applicable law or agreed to in writing, software 9 // distributed under the License is distributed on an "AS IS" BASIS, 10 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 11 // See the License for the specific language governing permissions and 12 // limitations under the License. 13 // ======================================================================== 14 15 package org.mortbay.jetty; 16 17 import java.util.EventListener; 18 19 import javax.servlet.http.Cookie; 20 import javax.servlet.http.HttpServletRequest; 21 import javax.servlet.http.HttpSession; 22 23 import org.mortbay.component.LifeCycle; 24 import org.mortbay.jetty.servlet.SessionHandler; 25 26 /* --------------------------------------------------------------------- */ 27 /** 28 * Session Manager. 29 * The API required to manage sessions for a servlet context. 30 * 31 * @author Greg Wilkins 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.mortbay.jetty.servlet.SessionCookie context init parameter. 40 */ 41 public final static String __SessionCookieProperty = "org.mortbay.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.mortbay.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.mortbay.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.mortbay.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.mortbay.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.mortbay.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 Cookie 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 public SessionIdManager getMetaManager(); 196 197 /* ------------------------------------------------------------ */ 198 /** 199 * Sets the cross context session id manager 200 * 201 * @param idManager the cross context session id manager. 202 * @see #getIdManager() 203 */ 204 public void setIdManager(SessionIdManager idManager); 205 206 /* ------------------------------------------------------------ */ 207 /** 208 * @param session the session to test for validity 209 * @return whether the given session is valid, that is, it has not been invalidated. 210 */ 211 public boolean isValid(HttpSession session); 212 213 /* ------------------------------------------------------------ */ 214 /** 215 * @param session the session object 216 * @return the unique id of the session within the cluster, extended with an optional node id. 217 * @see #getClusterId(HttpSession) 218 */ 219 public String getNodeId(HttpSession session); 220 221 /* ------------------------------------------------------------ */ 222 /** 223 * @param session the session object 224 * @return the unique id of the session within the cluster (without a node id extension) 225 * @see #getNodeId(HttpSession) 226 */ 227 public String getClusterId(HttpSession session); 228 229 /* ------------------------------------------------------------ */ 230 /** 231 * Called by the {@link SessionHandler} when a session is first accessed by a request. 232 * 233 * @param session the session object 234 * @param secure whether the request is secure or not 235 * @return the session cookie. If not null, this cookie should be set on the response to either migrate 236 * the session or to refresh a session cookie that may expire. 237 * @see #complete(HttpSession) 238 */ 239 public Cookie access(HttpSession session, boolean secure); 240 241 /* ------------------------------------------------------------ */ 242 /** 243 * Called by the {@link SessionHandler} when a session is last accessed by a request. 244 * 245 * @param session the session object 246 * @see #access(HttpSession, boolean) 247 */ 248 public void complete(HttpSession session); 249 250 /** 251 * Sets the session cookie name. 252 * @param cookieName the session cookie name 253 * @see #getSessionCookie() 254 */ 255 public void setSessionCookie(String cookieName); 256 257 /** 258 * @return the session cookie name, by default "JSESSIONID". 259 * @see #setSessionCookie(String) 260 */ 261 public String getSessionCookie(); 262 263 /** 264 * Sets the session id URL path parameter name. 265 * 266 * @param parameterName the URL path parameter name for session id URL rewriting (null or "none" for no rewriting). 267 * @see #getSessionIdPathParameterName() 268 * @see #getSessionIdPathParameterNamePrefix() 269 */ 270 public void setSessionIdPathParameterName(String parameterName); 271 272 /** 273 * @return the URL path parameter name for session id URL rewriting, by default "jsessionid". 274 * @see #setSessionIdPathParameterName(String) 275 */ 276 public String getSessionIdPathParameterName(); 277 278 /** 279 * @return a formatted version of {@link #getSessionIdPathParameterName()}, by default 280 * ";" + sessionIdParameterName + "=", for easier lookup in URL strings. 281 * @see #getSessionIdPathParameterName() 282 */ 283 public String getSessionIdPathParameterNamePrefix(); 284 285 /** 286 * Sets the domain to set on the session cookie 287 * @param domain the domain to set on the session cookie 288 * @see #getSessionDomain() 289 */ 290 public void setSessionDomain(String domain); 291 292 /** 293 * @return the domain to set on the session cookie 294 * @see #setSessionDomain(String) 295 */ 296 public String getSessionDomain(); 297 298 /** 299 * Sets the path to set on the session cookie 300 * @param path the path to set on the session cookie 301 * @see #getSessionPath() 302 */ 303 public void setSessionPath(String path); 304 305 /** 306 * @return the path to set on the session cookie 307 * @see #setSessionPath(String) 308 */ 309 public String getSessionPath(); 310 311 /** 312 * Sets the max age to set on the session cookie, in seconds 313 * @param maxCookieAge the max age to set on the session cookie, in seconds 314 * @see #getMaxCookieAge() 315 */ 316 public void setMaxCookieAge(int maxCookieAge); 317 318 /** 319 * @return the max age to set on the session cookie, in seconds 320 * @see #setMaxCookieAge(int) 321 */ 322 public int getMaxCookieAge(); 323 324 /** 325 * @return whether the session management is handled via cookies. 326 */ 327 public boolean isUsingCookies(); 328 }