View Javadoc

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