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