View Javadoc

    1
    2
    3   /*
    4    * The contents of this file are subject to the terms
    5    * of the Common Development and Distribution License
    6    * (the "License").  You may not use this file except
    7    * in compliance with the License.
    8    *
    9    * You can obtain a copy of the license at
    10   * glassfish/bootstrap/legal/CDDLv1.0.txt or
    11   * https://glassfish.dev.java.net/public/CDDLv1.0.html.
    12   * See the License for the specific language governing
    13   * permissions and limitations under the License.
    14   *
    15   * When distributing Covered Code, include this CDDL
    16   * HEADER in each file and include the License file at
    17   * glassfish/bootstrap/legal/CDDLv1.0.txt.  If applicable,
    18   * add the following below this CDDL HEADER, with the
    19   * fields enclosed by brackets "[]" replaced with your
    20   * own identifying information: Portions Copyright [yyyy]
    21   * [name of copyright owner]
    22   *
    23   * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
    24   *
    25   * Portions Copyright Apache Software Foundation.
    26   */
    27
    28  package javax.servlet.http;
    29
    30  import java.util.Enumeration;
    31  import javax.servlet.ServletContext;
    32
    33  /**
    34   *
    35   * Provides a way to identify a user across more than one page
    36   * request or visit to a Web site and to store information about that user.
    37   *
    38   * <p>The servlet container uses this interface to create a session
    39   * between an HTTP client and an HTTP server. The session persists
    40   * for a specified time period, across more than one connection or
    41   * page request from the user. A session usually corresponds to one
    42   * user, who may visit a site many times. The server can maintain a
    43   * session in many ways such as using cookies or rewriting URLs.
    44   *
    45   * <p>This interface allows servlets to
    46   * <ul>
    47   * <li>View and manipulate information about a session, such as
    48   *     the session identifier, creation time, and last accessed time
    49   * <li>Bind objects to sessions, allowing user information to persist
    50   *     across multiple user connections
    51   * </ul>
    52   *
    53   * <p>When an application stores an object in or removes an object from a
    54   * session, the session checks whether the object implements
    55   * {@link HttpSessionBindingListener}. If it does,
    56   * the servlet notifies the object that it has been bound to or unbound
    57   * from the session. Notifications are sent after the binding methods complete.
    58   * For session that are invalidated or expire, notifications are sent after
    59   * the session has been invalidated or expired.
    60   *
    61   * <p> When container migrates a session between VMs in a distributed container
    62   * setting, all session attributes implementing the {@link HttpSessionActivationListener}
    63   * interface are notified.
    64   *
    65   * <p>A servlet should be able to handle cases in which
    66   * the client does not choose to join a session, such as when cookies are
    67   * intentionally turned off. Until the client joins the session,
    68   * <code>isNew</code> returns <code>true</code>.  If the client chooses
    69   * not to join
    70   * the session, <code>getSession</code> will return a different session
    71   * on each request, and <code>isNew</code> will always return
    72   * <code>true</code>.
    73   *
    74   * <p>Session information is scoped only to the current web application
    75   * (<code>ServletContext</code>), so information stored in one context
    76   * will not be directly visible in another.
    77   *
    78   * @author	Various
    79   *
    80   * @see 	HttpSessionBindingListener
    81   * @see 	HttpSessionContext
    82   *
    83   */
    84
    85  public interface HttpSession {
    86
    87
    88
    89
    90      /**
    91       *
    92       * Returns the time when this session was created, measured
    93       * in milliseconds since midnight January 1, 1970 GMT.
    94       *
    95       * @return				a <code>long</code> specifying
    96       * 					when this session was created,
    97       *					expressed in
    98       *					milliseconds since 1/1/1970 GMT
    99       *
    100      * @exception IllegalStateException	if this method is called on an
    101      *					invalidated session
    102      *
    103      */
    104
    105     public long getCreationTime();
    106
    107
    108
    109
    110     /**
    111      *
    112      * Returns a string containing the unique identifier assigned
    113      * to this session. The identifier is assigned
    114      * by the servlet container and is implementation dependent.
    115      *
    116      * @return				a string specifying the identifier
    117      *					assigned to this session
    118      */
    119
    120     public String getId();
    121
    122
    123
    124
    125     /**
    126      *
    127      * Returns the last time the client sent a request associated with
    128      * this session, as the number of milliseconds since midnight
    129      * January 1, 1970 GMT, and marked by the time the container received the request.
    130      *
    131      * <p>Actions that your application takes, such as getting or setting
    132      * a value associated with the session, do not affect the access
    133      * time.
    134      *
    135      * @return				a <code>long</code>
    136      *					representing the last time
    137      *					the client sent a request associated
    138      *					with this session, expressed in
    139      *					milliseconds since 1/1/1970 GMT
    140      *
    141      * @exception IllegalStateException	if this method is called on an
    142      *					invalidated session
    143      *
    144      */
    145
    146     public long getLastAccessedTime();
    147
    148
    149     /**
    150     * Returns the ServletContext to which this session belongs.
    151     *
    152     * @return The ServletContext object for the web application
    153     * @since 2.3
    154     */
    155
    156     public ServletContext getServletContext();
    157
    158
    159     /**
    160      *
    161      * Specifies the time, in seconds, between client requests before the
    162      * servlet container will invalidate this session.  A negative time
    163      * indicates the session should never timeout.
    164      *
    165      * @param interval		An integer specifying the number
    166      * 				of seconds
    167      *
    168      */
    169
    170     public void setMaxInactiveInterval(int interval);
    171
    172
    173
    174
    175    /**
    176     * Returns the maximum time interval, in seconds, that
    177     * the servlet container will keep this session open between
    178     * client accesses. After this interval, the servlet container
    179     * will invalidate the session.  The maximum time interval can be set
    180     * with the <code>setMaxInactiveInterval</code> method.
    181     * A negative time indicates the session should never timeout.
    182     *
    183     *
    184     * @return		an integer specifying the number of
    185     *			seconds this session remains open
    186     *			between client requests
    187     *
    188     * @see		#setMaxInactiveInterval
    189     *
    190     *
    191     */
    192
    193     public int getMaxInactiveInterval();
    194
    195
    196
    197
    198    /**
    199     *
    200     * @deprecated 	As of Version 2.1, this method is
    201     *			deprecated and has no replacement.
    202     *			It will be removed in a future
    203     *			version of the Java Servlet API.
    204     *
    205     */
    206
    207     public HttpSessionContext getSessionContext();
    208
    209
    210
    211
    212     /**
    213      *
    214      * Returns the object bound with the specified name in this session, or
    215      * <code>null</code> if no object is bound under the name.
    216      *
    217      * @param name		a string specifying the name of the object
    218      *
    219      * @return			the object with the specified name
    220      *
    221      * @exception IllegalStateException	if this method is called on an
    222      *					invalidated session
    223      *
    224      */
    225
    226     public Object getAttribute(String name);
    227
    228
    229
    230
    231     /**
    232      *
    233      * @deprecated 	As of Version 2.2, this method is
    234      * 			replaced by {@link #getAttribute}.
    235      *
    236      * @param name		a string specifying the name of the object
    237      *
    238      * @return			the object with the specified name
    239      *
    240      * @exception IllegalStateException	if this method is called on an
    241      *					invalidated session
    242      *
    243      */
    244
    245     public Object getValue(String name);
    246
    247
    248
    249
    250     /**
    251      *
    252      * Returns an <code>Enumeration</code> of <code>String</code> objects
    253      * containing the names of all the objects bound to this session.
    254      *
    255      * @return			an <code>Enumeration</code> of
    256      *				<code>String</code> objects specifying the
    257      *				names of all the objects bound to
    258      *				this session
    259      *
    260      * @exception IllegalStateException	if this method is called on an
    261      *					invalidated session
    262      *
    263      */
    264
    265     public Enumeration getAttributeNames();
    266
    267
    268
    269
    270     /**
    271      *
    272      * @deprecated 	As of Version 2.2, this method is
    273      * 			replaced by {@link #getAttributeNames}
    274      *
    275      * @return				an array of <code>String</code>
    276      *					objects specifying the
    277      *					names of all the objects bound to
    278      *					this session
    279      *
    280      * @exception IllegalStateException	if this method is called on an
    281      *					invalidated session
    282      *
    283      */
    284
    285     public String[] getValueNames();
    286
    287
    288
    289
    290     /**
    291      * Binds an object to this session, using the name specified.
    292      * If an object of the same name is already bound to the session,
    293      * the object is replaced.
    294      *
    295      * <p>After this method executes, and if the new object
    296      * implements <code>HttpSessionBindingListener</code>,
    297      * the container calls
    298      * <code>HttpSessionBindingListener.valueBound</code>. The container then
    299      * notifies any <code>HttpSessionAttributeListener</code>s in the web
    300      * application.
    301
    302      * <p>If an object was already bound to this session of this name
    303      * that implements <code>HttpSessionBindingListener</code>, its
    304      * <code>HttpSessionBindingListener.valueUnbound</code> method is called.
    305      *
    306      * <p>If the value passed in is null, this has the same effect as calling
    307      * <code>removeAttribute()<code>.
    308      *
    309      *
    310      * @param name			the name to which the object is bound;
    311      *					cannot be null
    312      *
    313      * @param value			the object to be bound
    314      *
    315      * @exception IllegalStateException	if this method is called on an
    316      *					invalidated session
    317      *
    318      */
    319
    320     public void setAttribute(String name, Object value);
    321
    322
    323
    324
    325
    326     /**
    327      *
    328      * @deprecated 	As of Version 2.2, this method is
    329      * 			replaced by {@link #setAttribute}
    330      *
    331      * @param name			the name to which the object is bound;
    332      *					cannot be null
    333      *
    334      * @param value			the object to be bound; cannot be null
    335      *
    336      * @exception IllegalStateException	if this method is called on an
    337      *					invalidated session
    338      *
    339      */
    340
    341     public void putValue(String name, Object value);
    342
    343
    344
    345
    346
    347     /**
    348      *
    349      * Removes the object bound with the specified name from
    350      * this session. If the session does not have an object
    351      * bound with the specified name, this method does nothing.
    352      *
    353      * <p>After this method executes, and if the object
    354      * implements <code>HttpSessionBindingListener</code>,
    355      * the container calls
    356      * <code>HttpSessionBindingListener.valueUnbound</code>. The container
    357      * then notifies any <code>HttpSessionAttributeListener</code>s in the web
    358      * application.
    359      *
    360      *
    361      *
    362      * @param name				the name of the object to
    363      *						remove from this session
    364      *
    365      * @exception IllegalStateException	if this method is called on an
    366      *					invalidated session
    367      */
    368
    369     public void removeAttribute(String name);
    370
    371
    372
    373
    374
    375     /**
    376      *
    377      * @deprecated 	As of Version 2.2, this method is
    378      * 			replaced by {@link #removeAttribute}
    379      *
    380      * @param name				the name of the object to
    381      *						remove from this session
    382      *
    383      * @exception IllegalStateException	if this method is called on an
    384      *					invalidated session
    385      */
    386
    387     public void removeValue(String name);
    388
    389
    390
    391
    392     /**
    393      *
    394      * Invalidates this session then unbinds any objects bound
    395      * to it.
    396      *
    397      * @exception IllegalStateException	if this method is called on an
    398      *					already invalidated session
    399      *
    400      */
    401
    402     public void invalidate();
    403
    404
    405
    406
    407     /**
    408      *
    409      * Returns <code>true</code> if the client does not yet know about the
    410      * session or if the client chooses not to join the session.  For
    411      * example, if the server used only cookie-based sessions, and
    412      * the client had disabled the use of cookies, then a session would
    413      * be new on each request.
    414      *
    415      * @return 				<code>true</code> if the
    416      *					server has created a session,
    417      *					but the client has not yet joined
    418      *
    419      * @exception IllegalStateException	if this method is called on an
    420      *					already invalidated session
    421      *
    422      */
    423
    424     public boolean isNew();
    425
    426
    427
    428 }
    429