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.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      */
getHttpSession(String id)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      */
newHttpSession(HttpServletRequest request)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      */
getHttpOnly()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      */
getMaxInactiveInterval()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      */
setMaxInactiveInterval(int seconds)137     public void setMaxInactiveInterval(int seconds);
138 
139     /* ------------------------------------------------------------ */
140     /**
141      * Sets the {@link SessionHandler}.
142      *
143      * @param handler the <code>SessionHandler</code> object
144      */
setSessionHandler(SessionHandler handler)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      */
addEventListener(EventListener listener)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      */
removeEventListener(EventListener listener)166     public void removeEventListener(EventListener listener);
167 
168     /* ------------------------------------------------------------ */
169     /**
170      * Removes all event listeners for session-related events.
171      *
172      * @see #removeEventListener(EventListener)
173      */
clearEventListeners()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      */
getSessionCookie(HttpSession session, String contextPath, boolean requestIsSecure)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      */
getSessionIdManager()195     public SessionIdManager getSessionIdManager();
196 
197     /* ------------------------------------------------------------ */
198     /**
199      * @return the cross context session id manager.
200      * @deprecated use {@link #getSessionIdManager()}
201      */
202     @Deprecated
getMetaManager()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      */
setSessionIdManager(SessionIdManager idManager)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      */
isValid(HttpSession session)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      */
getNodeId(HttpSession session)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      */
getClusterId(HttpSession session)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      */
access(HttpSession session, boolean secure)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      */
complete(HttpSession session)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      */
setSessionIdPathParameterName(String parameterName)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      */
getSessionIdPathParameterName()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      */
getSessionIdPathParameterNamePrefix()278     public String getSessionIdPathParameterNamePrefix();
279 
280     /**
281      * @return whether the session management is handled via cookies.
282      */
isUsingCookies()283     public boolean isUsingCookies();
284 
285     /**
286      * @return whether the session management is handled via URLs.
287      */
isUsingURLs()288     public boolean isUsingURLs();
289 
getDefaultSessionTrackingModes()290     public Set<SessionTrackingMode> getDefaultSessionTrackingModes();
291 
getEffectiveSessionTrackingModes()292     public Set<SessionTrackingMode> getEffectiveSessionTrackingModes();
293 
setSessionTrackingModes(Set<SessionTrackingMode> sessionTrackingModes)294     public void setSessionTrackingModes(Set<SessionTrackingMode> sessionTrackingModes);
295 
getSessionCookieConfig()296     public SessionCookieConfig getSessionCookieConfig();
297 
298     /**
299      * @return True if absolute URLs are check for remoteness before being session encoded.
300      */
isCheckingRemoteSessionIdEncoding()301     public boolean isCheckingRemoteSessionIdEncoding();
302 
303     /**
304      * @param remote True if absolute URLs are check for remoteness before being session encoded.
305      */
setCheckingRemoteSessionIdEncoding(boolean remote)306     public void setCheckingRemoteSessionIdEncoding(boolean remote);
307 }
308