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 }