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