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