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

Save This Page
Home » glassfish-v2ur2-b04-src » javax » servlet » http » [javadoc | source]