lib/servlet-api/javax/servlet/http/HttpSession.java

   1 /*
   2  * Licensed to the Apache Software Foundation (ASF) under one or more
   3  * contributor license agreements.  See the NOTICE file distributed with
   4  * this work for additional information regarding copyright ownership.
   5  * The ASF licenses this file to You under the Apache License, Version 2.0
   6  * (the "License"); you may not use this file except in compliance with
   7  * the License.  You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17 package javax.servlet.http;
  18
  19 import java.util.Enumeration;
  20
  21 import javax.servlet.ServletContext;
  22
  23 /**
  24  * Provides a way to identify a user across more than one page request or visit
  25  * to a Web site and to store information about that user.
  26  * <p>
  27  * The servlet container uses this interface to create a session between an HTTP
  28  * client and an HTTP server. The session persists for a specified time period,
  29  * across more than one connection or page request from the user. A session
  30  * usually corresponds to one user, who may visit a site many times. The server
  31  * can maintain a session in many ways such as using cookies or rewriting URLs.
  32  * <p>
  33  * This interface allows servlets to
  34  * <ul>
  35  * <li>View and manipulate information about a session, such as the session
  36  * identifier, creation time, and last accessed time
  37  * <li>Bind objects to sessions, allowing user information to persist across
  38  * multiple user connections
  39  * </ul>
  40  * <p>
  41  * When an application stores an object in or removes an object from a session,
  42  * the session checks whether the object implements
  43  * {@link HttpSessionBindingListener}. If it does, the servlet notifies the
  44  * object that it has been bound to or unbound from the session. Notifications
  45  * are sent after the binding methods complete. For session that are invalidated
  46  * or expire, notifications are sent after the session has been invalidated or
  47  * expired.
  48  * <p>
  49  * When container migrates a session between VMs in a distributed container
  50  * setting, all session attributes implementing the
  51  * {@link HttpSessionActivationListener} interface are notified.
  52  * <p>
  53  * A servlet should be able to handle cases in which the client does not choose
  54  * to join a session, such as when cookies are intentionally turned off. Until
  55  * the client joins the session, <code>isNew</code> returns <code>true</code>.
  56  * If the client chooses not to join the session, <code>getSession</code> will
  57  * return a different session on each request, and <code>isNew</code> will
  58  * always return <code>true</code>.
  59  * <p>
  60  * Session information is scoped only to the current web application (
  61  * <code>ServletContext</code>), so information stored in one context will not
  62  * be directly visible in another.
  63  *
  64  * @see HttpSessionBindingListener
  65  */
  66 public interface HttpSession {
  67
  68     /**
  69      * Returns the time when this session was created, measured in milliseconds
  70      * since midnight January 1, 1970 GMT.
  71      *
  72      * @return a <code>long</code> specifying when this session was created,
  73      *         expressed in milliseconds since 1/1/1970 GMT
  74      * @exception IllegalStateException
  75      *                if this method is called on an invalidated session
  76      */
  77     public long getCreationTime();
  78
  79     /**
  80      * Returns a string containing the unique identifier assigned to this
  81      * session. The identifier is assigned by the servlet container and is
  82      * implementation dependent.
  83      *
  84      * @return a string specifying the identifier assigned to this session
  85      * @exception IllegalStateException
  86      *                if this method is called on an invalidated session
  87      */
  88     public String getId();
  89
  90     /**
  91      * Returns the last time the client sent a request associated with this
  92      * session, as the number of milliseconds since midnight January 1, 1970
  93      * GMT, and marked by the time the container received the request.
  94      * <p>
  95      * Actions that your application takes, such as getting or setting a value
  96      * associated with the session, do not affect the access time.
  97      *
  98      * @return a <code>long</code> representing the last time the client sent a
  99      *         request associated with this session, expressed in milliseconds
 100      *         since 1/1/1970 GMT
 101      * @exception IllegalStateException
 102      *                if this method is called on an invalidated session
 103      */
 104     public long getLastAccessedTime();
 105
 106     /**
 107      * Returns the ServletContext to which this session belongs.
 108      *
 109      * @return The ServletContext object for the web application
 110      * @since 2.3
 111      */
 112     public ServletContext getServletContext();
 113
 114     /**
 115      * Specifies the time, in seconds, between client requests before the
 116      * servlet container will invalidate this session. A zero or negative time
 117      * indicates that the session should never timeout.
 118      *
 119      * @param interval
 120      *            An integer specifying the number of seconds
 121      */
 122     public void setMaxInactiveInterval(int interval);
 123
 124     /**
 125      * Returns the maximum time interval, in seconds, that the servlet container
 126      * will keep this session open between client accesses. After this interval,
 127      * the servlet container will invalidate the session. The maximum time
 128      * interval can be set with the <code>setMaxInactiveInterval</code> method.
 129      * A zero or negative time indicates that the session should never timeout.
 130      *
 131      * @return an integer specifying the number of seconds this session remains
 132      *         open between client requests
 133      * @see #setMaxInactiveInterval
 134      */
 135     public int getMaxInactiveInterval();
 136
 137     /**
 138      * @deprecated As of Version 2.1, this method is deprecated and has no
 139      *             replacement. It will be removed in a future version of the
 140      *             Java Servlet API.
 141      */
 142     @SuppressWarnings("dep-ann")
 143     // Spec API does not use @Deprecated
 144     public HttpSessionContext getSessionContext();
 145
 146     /**
 147      * Returns the object bound with the specified name in this session, or
 148      * <code>null</code> if no object is bound under the name.
 149      *
 150      * @param name
 151      *            a string specifying the name of the object
 152      * @return the object with the specified name
 153      * @exception IllegalStateException
 154      *                if this method is called on an invalidated session
 155      */
 156     public Object getAttribute(String name);
 157
 158     /**
 159      * @param name
 160      *            a string specifying the name of the object
 161      * @return the object with the specified name
 162      * @exception IllegalStateException
 163      *                if this method is called on an invalidated session
 164      * @deprecated As of Version 2.2, this method is replaced by
 165      *             {@link #getAttribute}.
 166      */
 167     @SuppressWarnings("dep-ann")
 168     // Spec API does not use @Deprecated
 169     public Object getValue(String name);
 170
 171     /**
 172      * Returns an <code>Enumeration</code> of <code>String</code> objects
 173      * containing the names of all the objects bound to this session.
 174      *
 175      * @return an <code>Enumeration</code> of <code>String</code> objects
 176      *         specifying the names of all the objects bound to this session
 177      * @exception IllegalStateException
 178      *                if this method is called on an invalidated session
 179      */
 180     public Enumeration<String> getAttributeNames();
 181
 182     /**
 183      * @return an array of <code>String</code> objects specifying the names of
 184      *         all the objects bound to this session
 185      * @exception IllegalStateException
 186      *                if this method is called on an invalidated session
 187      * @deprecated As of Version 2.2, this method is replaced by
 188      *             {@link #getAttributeNames}
 189      */
 190     @SuppressWarnings("dep-ann")
 191     // Spec API does not use @Deprecated
 192     public String[] getValueNames();
 193
 194     /**
 195      * Binds an object to this session, using the name specified. If an object
 196      * of the same name is already bound to the session, the object is replaced.
 197      * <p>
 198      * After this method executes, and if the new object implements
 199      * <code>HttpSessionBindingListener</code>, the container calls
 200      * <code>HttpSessionBindingListener.valueBound</code>. The container then
 201      * notifies any <code>HttpSessionAttributeListener</code>s in the web
 202      * application.
 203      * <p>
 204      * If an object was already bound to this session of this name that
 205      * implements <code>HttpSessionBindingListener</code>, its
 206      * <code>HttpSessionBindingListener.valueUnbound</code> method is called.
 207      * <p>
 208      * If the value passed in is null, this has the same effect as calling
 209      * <code>removeAttribute()</code>.
 210      *
 211      * @param name
 212      *            the name to which the object is bound; cannot be null
 213      * @param value
 214      *            the object to be bound
 215      * @exception IllegalStateException
 216      *                if this method is called on an invalidated session
 217      */
 218     public void setAttribute(String name, Object value);
 219
 220     /**
 221      * @param name
 222      *            the name to which the object is bound; cannot be null
 223      * @param value
 224      *            the object to be bound; cannot be null
 225      * @exception IllegalStateException
 226      *                if this method is called on an invalidated session
 227      * @deprecated As of Version 2.2, this method is replaced by
 228      *             {@link #setAttribute}
 229      */
 230     @SuppressWarnings("dep-ann")
 231     // Spec API does not use @Deprecated
 232     public void putValue(String name, Object value);
 233
 234     /**
 235      * Removes the object bound with the specified name from this session. If
 236      * the session does not have an object bound with the specified name, this
 237      * method does nothing.
 238      * <p>
 239      * After this method executes, and if the object implements
 240      * <code>HttpSessionBindingListener</code>, the container calls
 241      * <code>HttpSessionBindingListener.valueUnbound</code>. The container then
 242      * notifies any <code>HttpSessionAttributeListener</code>s in the web
 243      * application.
 244      *
 245      * @param name
 246      *            the name of the object to remove from this session
 247      * @exception IllegalStateException
 248      *                if this method is called on an invalidated session
 249      */
 250     public void removeAttribute(String name);
 251
 252     /**
 253      * @param name
 254      *            the name of the object to remove from this session
 255      * @exception IllegalStateException
 256      *                if this method is called on an invalidated session
 257      * @deprecated As of Version 2.2, this method is replaced by
 258      *             {@link #removeAttribute}
 259      */
 260     @SuppressWarnings("dep-ann")
 261     // Spec API does not use @Deprecated
 262     public void removeValue(String name);
 263
 264     /**
 265      * Invalidates this session then unbinds any objects bound to it.
 266      *
 267      * @exception IllegalStateException
 268      *                if this method is called on an already invalidated session
 269      */
 270     public void invalidate();
 271
 272     /**
 273      * Returns <code>true</code> if the client does not yet know about the
 274      * session or if the client chooses not to join the session. For example, if
 275      * the server used only cookie-based sessions, and the client had disabled
 276      * the use of cookies, then a session would be new on each request.
 277      *
 278      * @return <code>true</code> if the server has created a session, but the
 279      *         client has not yet joined
 280      * @exception IllegalStateException
 281      *                if this method is called on an already invalidated session
 282      */
 283     public boolean isNew();
 284 }