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