home *** CD-ROM | disk | FTP | other *** search
/ Total Network Tools 2002 / NextStepPublishing-TotalNetworkTools2002-Win95.iso / Archive / Web Server / Sambar Server.exe / _SETUP.1 / javaeng.jar / javax / servlet / http / HttpSession.java < prev    next >
Encoding:
Java Source  |  2000-04-03  |  7.5 KB  |  261 lines
  1. /*
  2.  * HttpSession.java -- Holds client data between requests
  3.  *
  4.  * Copyright (c) 1998, 1999 by Free Software Foundation, Inc.
  5.  * Written by Paul Siegmann (pauls@euronet.nl)
  6.  *
  7.  * This program is free software; you can redistribute it and/or modify
  8.  * it under the terms of the GNU Library General Public License as published
  9.  * by the Free Software Foundation, version 2. (see COPYING.LIB)
  10.  *
  11.  * This program is distributed in the hope that it will be useful, but
  12.  * WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  * GNU General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU General Public License
  17.  * along with this program; if not, write to the Free Software Foundation
  18.  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307 USA
  19.  */
  20.  
  21. package javax.servlet.http;
  22. #ifdef SERVLET_2_2
  23. import java.util.Enumeration;
  24. #endif
  25.  
  26. /**
  27.  * A HttpSession holds session-dependant data on the server side.
  28.  * A servlet can request the servlet by using HttpServletRequest.getSession(...)
  29.  * <P>
  30.  * The handling of the Session objects is a job done by the server and
  31.  * servlets together.
  32.  * <DL>
  33.  * <DT>As follows:
  34.  * <DD>
  35.  * The server maintaines the set of HttpSessions.<BR>
  36.  * The server creates HttpSession on request by a servlet<BR>
  37.  * The server removes all invalidated HttpSessions<BR>
  38.  * The server connects an incoming request with its HttpSession
  39.  * (usually done using cookies)<BR>
  40.  * Servlets manipulate the contents of the HttpSession by adding and removing
  41.  * items.<BR>
  42.  * Servlets ask the server to remove HttpSessions by invalidating them<BR>
  43.  * </DD>
  44.  * </DL>
  45.  *
  46. #ifdef SERVLET_2_0
  47.  * @version Servlet API 2.0 
  48. #endif
  49. #ifdef SERVLET_2_1
  50.  * @version Servlet API 2.1
  51. #endif
  52. #ifdef SERVLET_2_2
  53.  * @version Servlet API 2.2
  54. #endif
  55.  * @since Servlet API 2.0
  56.  * @author Paul Siegmann (pauls@euronet.nl)
  57.  */
  58. public interface HttpSession
  59. {
  60.     /**
  61.      * Gets this session's creation time in seconds since january 1st 1970.
  62.      *
  63.      * @since Servlet API 2.0
  64.      *
  65.      * @return a number of seconds
  66.      * @exception IllegalStateException if the session has been invalidated.
  67.      */
  68.     long getCreationTime() throws IllegalStateException;
  69.  
  70.  
  71.     /**
  72.      * Gets the unique session id.
  73.      * Every HttpSession has a Id that is unique for this (virtual) http
  74.      * server.
  75.      *
  76.      * @since Servlet API 2.0
  77.      *
  78.      * @return The Id
  79.      * @exception IllegalStateException if the session has been invalidated.
  80.      */
  81.     String getId() throws IllegalStateException;
  82.  
  83.  
  84.     /**
  85.      * Gets the number of seconds since the previous access of this session.
  86.      * Every time a client's request comes in the server checks (usually by
  87.      * using cookies) which HttpSession object corresponds with this
  88.      * particular client.
  89.      * The server then sets the lastAccessedTime to the current time.
  90.      * (And the isNew flag to false.) If the client has never requested anything
  91.      * with this Session then this method returns -1
  92.      *
  93.      * @since Servlet API 2.0
  94.      *
  95.      * @return number of seconds since last access or -1
  96.      * @exception IllegalStateException if the session has been invalidated.
  97.      */
  98.     long getLastAccessedTime() throws IllegalStateException;
  99.  
  100.  
  101. #ifdef SERVLET_2_0
  102. #else
  103.     /**
  104.      * Returns the minimum time this session will be kept alive by the
  105.      * server when it doesn't get accessed by a client.
  106.      *
  107.      * @since Servlet API 2.1
  108.      *
  109.      * @returns the time in seconds, or -1 when this session will live forever
  110.      */
  111.     int getMaxInactiveInterval() throws IllegalStateException;
  112. #endif
  113.  
  114.     /**
  115.      * Gets a object from the set of name/value pairs in the session.
  116.      *
  117.      * @since Servlet API 2.0
  118.      *
  119.      * @param name the name of the item required
  120.      * @return the value of the item. null if not present.
  121.      * @exception IllegalStateException if the session has been invalidated.
  122.      */
  123.     Object getValue(String name) throws IllegalStateException;
  124.  
  125.  
  126.     /**
  127.      * Get a list of all item names in the session.
  128.      *
  129.      * @since Servlet API 2.0
  130.      *
  131.      * @return An array of Strings containing all item names.
  132.      * @exception IllegalStateException if the session has been invalidated.
  133.      */
  134.     String[] getValueNames() throws IllegalStateException;
  135.  
  136.  
  137.     /**
  138.      * Make this HttpSession unavailable for use by other servlets and tell
  139.      * the server to remove this session. All values bound to this session
  140.      * with <code>putValue()</code> that implement
  141.      * <code>HttpSessionBindingListener</code> will be called with
  142.      * <code>valueUnbound()</code>.
  143.      * Also: make it throw an IllegalStateException when a
  144.      * servlet tries to execute one of its methods.
  145.      *
  146.      * @since Servlet API 2.0
  147.      *
  148.      * @exception IllegalStateException if the session has been invalidated.
  149.      */
  150.     void invalidate() throws IllegalStateException;
  151.  
  152.  
  153.     /**
  154.      * Returns whether this session has been freshly created.
  155.      * A servlet can ask the server to give the HttpSession connected with
  156.      * this request/client.
  157.      * The Servlet can use this method to check whether the HttpSession has
  158.      * been newly created or if a HttpSession had already been created for a
  159.      * previous request.
  160.      *
  161.      * @since Servlet API 2.0
  162.      *
  163.      * @return Whether this is a new HttpSession
  164.      * @exception IllegalStateException if the session has been invalidated.
  165.      */
  166.     boolean isNew() throws IllegalStateException;
  167.  
  168.  
  169.     /**
  170.      * Puts a name and value in the HttpSession.
  171.      * If the Object implements <code>HttpSessionBindindListener</code> then
  172.      * the <code>valueBound()</code> method of the Object will be called.
  173.      *
  174.      * @since Servlet API 2.0
  175.      *
  176.      * @param name the name of the item
  177.      * @param value the value of the item
  178.      * @exception IllegalStateException if the session has been invalidated.
  179.      */
  180.     void putValue(String name,Object value) throws IllegalStateException;
  181.  
  182.     /**
  183.      * Removes an item from the session.
  184.      * If the Object implements <code>HttpSessionBindindListener</code> then
  185.      * the <code>valueUnBound()</code> method of the Object will be called.
  186.      *
  187.      * @since Servlet API 2.0
  188.      *
  189.      * @exception IllegalStateException if the session has been invalidated.
  190.      * @param name the name of the item.
  191.      */
  192.     void removeValue(String name) throws IllegalStateException;
  193.  
  194.  
  195. #ifdef SERVLET_2_0
  196. #else
  197.     /**
  198.      * Sets the minimum time this session will be kept alive by the
  199.      * server when it doesn't get accessed by a client.<BR>
  200.      * <B>Note:</B> hmmm, should an interval of -1 mean that it should live forever?
  201.      * @since Servlet API 2.1
  202.      *
  203.      * @param interval Probably seconds or -1 if never
  204.      */
  205.     void setMaxInactiveInterval(int interval) throws IllegalStateException;
  206.  
  207. #endif
  208.  
  209. #ifdef SERVLET_2_2
  210.  
  211.     /**
  212.      * XXX
  213.      *
  214.      * @since Servlet API 2.2
  215.      */
  216.     Object getAttribute(String name);
  217.  
  218.  
  219.     /**
  220.      * XXX
  221.      *
  222.      * @since Servlet API 2.2
  223.      */
  224.     Enumeration getAttributeNames();
  225.  
  226.  
  227.     /**
  228.      * XXX
  229.      *
  230.      * @since Servlet API 2.2
  231.      */
  232.     void setAttribute(String name, Object value);
  233.  
  234.  
  235.     /**
  236.      * XXX
  237.      *
  238.      * @since Servlet API 2.2
  239.      */
  240.     void removeAttribute(String name);
  241.  
  242. #endif
  243.  
  244.     /**
  245.      * Gets this HttpSession's context.
  246.      * The context contains information that is the same for all HttpSessions
  247.      * for this (virtual) host.
  248.      *
  249. #ifdef SERVLET_2_0
  250. #else
  251.      * @deprecated <code>HttpSessionContext</code> has been depricated for
  252.      *    security reasons. 
  253. #endif
  254.      * @since Servlet API 2.0
  255.      *
  256.      * @return The context
  257.      * @exception IllegalStateException if the session has been invalidated.
  258.      */
  259.     HttpSessionContext getSessionContext() throws IllegalStateException;
  260. }
  261.