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