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