View Javadoc

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 }