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