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 }