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 /* ------------------------------------------------------------ */ getHttpSession(String id)84 public HttpSession getHttpSession(String id); 85 86 /* ------------------------------------------------------------ */ newHttpSession(HttpServletRequest request)87 public HttpSession newHttpSession(HttpServletRequest request); 88 89 /* ------------------------------------------------------------ */ 90 /** @return true if session cookies should be secure 91 */ getSecureCookies()92 public boolean getSecureCookies(); 93 94 /* ------------------------------------------------------------ */ 95 /** @return true if session cookies should be httponly (microsoft extension) 96 */ getHttpOnly()97 public boolean getHttpOnly(); 98 99 /* ------------------------------------------------------------ */ getMaxInactiveInterval()100 public int getMaxInactiveInterval(); 101 102 /* ------------------------------------------------------------ */ setMaxInactiveInterval(int seconds)103 public void setMaxInactiveInterval(int seconds); 104 105 /* ------------------------------------------------------------ */ setSessionHandler(SessionHandler handler)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 */ addEventListener(EventListener listener)118 public void addEventListener(EventListener listener); 119 120 /* ------------------------------------------------------------ */ removeEventListener(EventListener listener)121 public void removeEventListener(EventListener listener); 122 123 /* ------------------------------------------------------------ */ clearEventListeners()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 */ getSessionCookie(HttpSession session,String contextPath, boolean requestIsSecure)136 public Cookie getSessionCookie(HttpSession session,String contextPath, boolean requestIsSecure); 137 138 /* ------------------------------------------------------------ */ 139 /** 140 * @return the cross context session meta manager. 141 */ getIdManager()142 public SessionIdManager getIdManager(); 143 144 /* ------------------------------------------------------------ */ 145 /** 146 * @return the cross context session id manager. 147 * @deprecated use {@link #getIdManager()} 148 */ getMetaManager()149 public SessionIdManager getMetaManager(); 150 151 /* ------------------------------------------------------------ */ 152 /** 153 * @param meta the cross context session meta manager. 154 */ setIdManager(SessionIdManager meta)155 public void setIdManager(SessionIdManager meta); 156 157 /* ------------------------------------------------------------ */ isValid(HttpSession session)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 */ getNodeId(HttpSession session)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 */ getClusterId(HttpSession session)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 */ access(HttpSession session,boolean secure)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 */ complete(HttpSession session)187 public void complete(HttpSession session); 188 189 setSessionCookie(String cookieName)190 public void setSessionCookie (String cookieName); 191 getSessionCookie()192 public String getSessionCookie (); 193 setSessionURL(String url)194 public void setSessionURL (String url); 195 getSessionURL()196 public String getSessionURL (); 197 getSessionURLPrefix()198 public String getSessionURLPrefix(); 199 setSessionDomain(String domain)200 public void setSessionDomain (String domain); 201 getSessionDomain()202 public String getSessionDomain (); 203 setSessionPath(String path)204 public void setSessionPath (String path); 205 getSessionPath()206 public String getSessionPath (); 207 setMaxCookieAge(int maxCookieAgeInSeconds)208 public void setMaxCookieAge (int maxCookieAgeInSeconds); 209 getMaxCookieAge()210 public int getMaxCookieAge(); 211 isUsingCookies()212 public boolean isUsingCookies(); 213 214 } 215