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