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 /* --------------------------------------------------------------------- */
29 /** Session Manager.
30 * The API required to manage sessions for a servlet context.
31 *
32 * @author Greg Wilkins
33 */
34 public interface SessionManager extends LifeCycle
35 {
36
37 /* ------------------------------------------------------------ */
38 /** Session cookie name.
39 * Defaults to JSESSIONID, but can be set with the
40 * org.mortbay.jetty.servlet.SessionCookie context init parameter.
41 */
42 public final static String __SessionCookieProperty = "org.mortbay.jetty.servlet.SessionCookie";
43 public final static String __DefaultSessionCookie = "JSESSIONID";
44
45
46 /* ------------------------------------------------------------ */
47 /** Session URL parameter name.
48 * Defaults to jsessionid, but can be set with the
49 * org.mortbay.jetty.servlet.SessionURL context init parameter. If set to null or
50 * "none" no URL rewriting will be done.
51 */
52 public final static String __SessionURLProperty = "org.mortbay.jetty.servlet.SessionURL";
53 public final static String __DefaultSessionURL = "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 /** Session Path.
69 * If this property is set as a ServletContext InitParam, then it is
70 * used as the path for the session cookie. If it is not set, then
71 * the context path is used as the path for the cookie.
72 */
73 public final static String __SessionPathProperty="org.mortbay.jetty.servlet.SessionPath";
74
75 /* ------------------------------------------------------------ */
76 /** Session Max Age.
77 * If this property is set as a ServletContext InitParam, then it is
78 * used as the max age for the session cookie. If it is not set, then
79 * a max age of -1 is used.
80 */
81 public final static String __MaxAgeProperty="org.mortbay.jetty.servlet.MaxAge";
82
83 /* ------------------------------------------------------------ */
84 public HttpSession getHttpSession(String id);
85
86 /* ------------------------------------------------------------ */
87 public HttpSession newHttpSession(HttpServletRequest request);
88
89 /* ------------------------------------------------------------ */
90 /** @return true if session cookies should be secure
91 */
92 public boolean getSecureCookies();
93
94 /* ------------------------------------------------------------ */
95 /** @return true if session cookies should be httponly (microsoft extension)
96 */
97 public boolean getHttpOnly();
98
99 /* ------------------------------------------------------------ */
100 public int getMaxInactiveInterval();
101
102 /* ------------------------------------------------------------ */
103 public void setMaxInactiveInterval(int seconds);
104
105 /* ------------------------------------------------------------ */
106 public void setSessionHandler(SessionHandler handler);
107
108 /* ------------------------------------------------------------ */
109 /** Add an event listener.
110 * @param listener An Event Listener. Individual SessionManagers
111 * implemetations may accept arbitrary listener types, but they
112 * are expected to at least handle
113 * HttpSessionActivationListener,
114 * HttpSessionAttributeListener,
115 * HttpSessionBindingListener,
116 * HttpSessionListener
117 */
118 public void addEventListener(EventListener listener);
119
120 /* ------------------------------------------------------------ */
121 public void removeEventListener(EventListener listener);
122
123 /* ------------------------------------------------------------ */
124 public void clearEventListeners();
125
126 /* ------------------------------------------------------------ */
127 /** Get a Cookie for a session.
128 * @param session The session to which the cookie should refer.
129 * @param contextPath The context to which the cookie should be linked. The client will only send the cookie value
130 * when requesting resources under this path.
131 * @param requestIsSecure Whether the client is accessing the server over a secure protocol (i.e. HTTPS).
132 * @return If this <code>SessionManager</code> uses cookies, then this method will return a new
133 * {@link Cookie cookie object} that should be set on the client in order to link future HTTP requests
134 * with the <code>session</code>. If cookies are not in use, this method returns <code>null</code>.
135 */
136 public Cookie getSessionCookie(HttpSession session,String contextPath, boolean requestIsSecure);
137
138 /* ------------------------------------------------------------ */
139 /**
140 * @return the cross context session meta manager.
141 */
142 public SessionIdManager getIdManager();
143
144 /* ------------------------------------------------------------ */
145 /**
146 * @return the cross context session id manager.
147 * @deprecated use {@link #getIdManager()}
148 */
149 public SessionIdManager getMetaManager();
150
151 /* ------------------------------------------------------------ */
152 /**
153 * @param meta the cross context session meta manager.
154 */
155 public void setIdManager(SessionIdManager meta);
156
157 /* ------------------------------------------------------------ */
158 public boolean isValid(HttpSession session);
159
160 /* ------------------------------------------------------------ */
161 /** Get the session node id
162 * @param session
163 * @return The unique id of the session within the cluster, extended with an optional node id.
164 */
165 public String getNodeId(HttpSession session);
166
167 /* ------------------------------------------------------------ */
168 /** Get the session cluster id
169 * @param session
170 * @return The unique id of the session within the cluster (without a node id extension)
171 */
172 public String getClusterId(HttpSession session);
173
174 /* ------------------------------------------------------------ */
175 /** Called by the {@link SessionHandler} when a session is access by a request
176 * @return Cookie If non null, this cookie should be set on the response to either migrate
177 * the session or to refresh a cookie that may expire.
178 */
179 public Cookie access(HttpSession session,boolean secure);
180
181 /* ------------------------------------------------------------ */
182 /** Called by the {@link SessionHandler} when a reqeuest is not longer
183 * handling a session. Not this includes new sessions, so there may not
184 * be a matching call to {@link #access(HttpSession)}.
185 *
186 */
187 public void complete(HttpSession session);
188
189
190 public void setSessionCookie (String cookieName);
191
192 public String getSessionCookie ();
193
194 public void setSessionURL (String url);
195
196 public String getSessionURL ();
197
198 public String getSessionURLPrefix();
199
200 public void setSessionDomain (String domain);
201
202 public String getSessionDomain ();
203
204 public void setSessionPath (String path);
205
206 public String getSessionPath ();
207
208 public void setMaxCookieAge (int maxCookieAgeInSeconds);
209
210 public int getMaxCookieAge();
211
212 public boolean isUsingCookies();
213
214 }