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.
9 // The Eclipse Public License is available at
10 // http://www.eclipse.org/legal/epl-v10.html
12 // The Apache License v2.0 is available at
13 // http://www.opensource.org/licenses/apache2.0.php
15 // You may elect to redistribute this code under either of these licenses.
16 // ========================================================================
19 package org.eclipse.jetty.server;
21 import java.util.EventListener;
24 import javax.servlet.SessionCookieConfig;
25 import javax.servlet.SessionTrackingMode;
26 import javax.servlet.http.HttpServletRequest;
27 import javax.servlet.http.HttpSession;
29 import org.eclipse.jetty.http.HttpCookie;
30 import org.eclipse.jetty.server.session.SessionHandler;
31 import org.eclipse.jetty.util.component.LifeCycle;
33 /* --------------------------------------------------------------------- */
36 * The API required to manage sessions for a servlet context.
40 /* ------------------------------------------------------------ */
43 public interface SessionManager extends LifeCycle
45 /* ------------------------------------------------------------ */
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.
51 public final static String __SessionCookieProperty = "org.eclipse.jetty.servlet.SessionCookie";
52 public final static String __DefaultSessionCookie = "JSESSIONID";
55 /* ------------------------------------------------------------ */
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.
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";
67 /* ------------------------------------------------------------ */
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.
74 public final static String __SessionDomainProperty = "org.eclipse.jetty.servlet.SessionDomain";
75 public final static String __DefaultSessionDomain = null;
78 /* ------------------------------------------------------------ */
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.
85 public final static String __SessionPathProperty = "org.eclipse.jetty.servlet.SessionPath";
87 /* ------------------------------------------------------------ */
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.
94 public final static String __MaxAgeProperty = "org.eclipse.jetty.servlet.MaxAge";
96 /* ------------------------------------------------------------ */
98 * Returns the <code>HttpSession</code> with the given session id
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
103 public HttpSession getHttpSession(String id);
105 /* ------------------------------------------------------------ */
107 * Creates a new <code>HttpSession</code>.
109 * @param request the HttpServletRequest containing the requested session id
110 * @return the new <code>HttpSession</code>
112 public HttpSession newHttpSession(HttpServletRequest request);
115 /* ------------------------------------------------------------ */
117 * @return true if session cookies should be HTTP-only (Microsoft extension)
118 * @see org.eclipse.jetty.http.HttpCookie#isHttpOnly()
120 public boolean getHttpOnly();
122 /* ------------------------------------------------------------ */
124 * @return the max period of inactivity, after which the session is invalidated, in seconds.
125 * @see #setMaxInactiveInterval(int)
127 public int getMaxInactiveInterval();
129 /* ------------------------------------------------------------ */
131 * Sets the max period of inactivity, after which the session is invalidated, in seconds.
133 * @param seconds the max inactivity period, in seconds.
134 * @see #getMaxInactiveInterval()
136 public void setMaxInactiveInterval(int seconds);
138 /* ------------------------------------------------------------ */
140 * Sets the {@link SessionHandler}.
142 * @param handler the <code>SessionHandler</code> object
144 public void setSessionHandler(SessionHandler handler);
146 /* ------------------------------------------------------------ */
148 * Adds an event listener for session-related events.
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)
156 public void addEventListener(EventListener listener);
158 /* ------------------------------------------------------------ */
160 * Removes an event listener for for session-related events.
162 * @param listener the session event listener to remove
163 * @see #addEventListener(EventListener)
165 public void removeEventListener(EventListener listener);
167 /* ------------------------------------------------------------ */
169 * Removes all event listeners for session-related events.
171 * @see #removeEventListener(EventListener)
173 public void clearEventListeners();
175 /* ------------------------------------------------------------ */
177 * Gets a Cookie for a session.
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>.
187 public HttpCookie getSessionCookie(HttpSession session, String contextPath, boolean requestIsSecure);
189 /* ------------------------------------------------------------ */
191 * @return the cross context session id manager.
192 * @see #setSessionIdManager(SessionIdManager)
194 public SessionIdManager getSessionIdManager();
196 /* ------------------------------------------------------------ */
198 * @return the cross context session id manager.
199 * @deprecated use {@link #getSessionIdManager()}
202 public SessionIdManager getMetaManager();
204 /* ------------------------------------------------------------ */
206 * Sets the cross context session id manager
208 * @param idManager the cross context session id manager.
209 * @see #getSessionIdManager()
211 public void setSessionIdManager(SessionIdManager idManager);
213 /* ------------------------------------------------------------ */
215 * @param session the session to test for validity
216 * @return whether the given session is valid, that is, it has not been invalidated.
218 public boolean isValid(HttpSession session);
220 /* ------------------------------------------------------------ */
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)
226 public String getNodeId(HttpSession session);
228 /* ------------------------------------------------------------ */
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)
234 public String getClusterId(HttpSession session);
236 /* ------------------------------------------------------------ */
238 * Called by the {@link SessionHandler} when a session is first accessed by a request.
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)
246 public HttpCookie access(HttpSession session, boolean secure);
248 /* ------------------------------------------------------------ */
250 * Called by the {@link SessionHandler} when a session is last accessed by a request.
252 * @param session the session object
253 * @see #access(HttpSession, boolean)
255 public void complete(HttpSession session);
258 * Sets the session id URL path parameter name.
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()
264 public void setSessionIdPathParameterName(String parameterName);
267 * @return the URL path parameter name for session id URL rewriting, by default "jsessionid".
268 * @see #setSessionIdPathParameterName(String)
270 public String getSessionIdPathParameterName();
273 * @return a formatted version of {@link #getSessionIdPathParameterName()}, by default
274 * ";" + sessionIdParameterName + "=", for easier lookup in URL strings.
275 * @see #getSessionIdPathParameterName()
277 public String getSessionIdPathParameterNamePrefix();
280 * @return whether the session management is handled via cookies.
282 public boolean isUsingCookies();
285 * @return whether the session management is handled via URLs.
287 public boolean isUsingURLs();
289 public Set<SessionTrackingMode> getDefaultSessionTrackingModes();
291 public Set<SessionTrackingMode> getEffectiveSessionTrackingModes();
293 public void setSessionTrackingModes(Set<SessionTrackingMode> sessionTrackingModes);
295 public SessionCookieConfig getSessionCookieConfig();
298 * @return True if absolute URLs are check for remoteness before being session encoded.
300 public boolean isCheckingRemoteSessionIdEncoding();
303 * @param remote True if absolute URLs are check for remoteness before being session encoded.
305 public void setCheckingRemoteSessionIdEncoding(boolean remote);
307 /* ------------------------------------------------------------ */
308 /** Change the existing session id.
310 * @param oldClusterId
312 * @param newClusterId
315 public void renewSessionId(String oldClusterId, String oldNodeId, String newClusterId, String newNodeId);