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