home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgLangD.iso / VCAFE.3.0A / Main.bin / HttpServletRequest.java < prev    next >
Text File  |  1998-04-21  |  9KB  |  257 lines
  1. /*
  2.  * @(#)HttpServletRequest.java    1.26 98/04/16
  3.  * 
  4.  * Copyright (c) 1995-1997 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.0
  20.  */
  21.  
  22. package javax.servlet.http;
  23.  
  24. import javax.servlet.ServletRequest;
  25. import java.util.Enumeration;
  26.  
  27. /**
  28.  * An HTTP servlet request.  This interface gets data from the client
  29.  * to the servlet for use in the <code>HttpServlet.service</code>
  30.  * method.  It allows the HTTP-protocol specified header information to
  31.  * be accessed from the <code>service</code> method.  This interface is
  32.  * implemented by network-service developers for use within servlets.
  33.  *
  34.  * @version 1.26, 04/16/98
  35.  */
  36. public
  37. interface HttpServletRequest extends ServletRequest {
  38.  
  39.     /**
  40.      * Gets the array of cookies found in this request.
  41.      *
  42.      * @return the array of cookies found in this request
  43.      */
  44.     public Cookie[] getCookies();
  45.  
  46.     /**
  47.      * Gets the HTTP method (for example, GET, POST, PUT) with which
  48.      * this request was made. Same as the CGI variable REQUEST_METHOD.
  49.      *
  50.      * @return the HTTP method with which this request was made
  51.      */
  52.     public String getMethod();
  53.  
  54.     /**
  55.      * Gets, from the first line of the HTTP request, the part of this
  56.      * request's URI that is to the left of any query string.
  57.      * For example,
  58.      *
  59.      * <blockquote>
  60.      * <table>
  61.      * <tr align=left><th>First line of HTTP request<th>
  62.      * <th>Return from <code>getRequestURI</code>
  63.      * <tr><td>POST /some/path.html HTTP/1.1<td><td>/some/path.html
  64.      * <tr><td>GET http://foo.bar/a.html HTTP/1.0
  65.      * <td><td>http://foo.bar/a.html
  66.      * <tr><td>HEAD /xyz?a=b HTTP/1.1<td><td>/xyz
  67.      * </table>
  68.      * </blockquote>
  69.      * 
  70.      * <p>To reconstruct a URL with a URL scheme and host, use the
  71.      * method javax.servlet.http.HttpUtils.getRequestURL, which returns
  72.      * a StringBuffer.
  73.      *
  74.      * @return this request's URI
  75.      * @see javax.servlet.http.HttpUtils#getRequestURL
  76.      */
  77.     public String getRequestURI();
  78.  
  79.     /**
  80.      * Gets the part of this request's URI that refers to the servlet
  81.      * being invoked. Analogous to the CGI variable SCRIPT_NAME.
  82.      *
  83.      * @return the servlet being invoked, as contained in this
  84.      * request's URI
  85.      */
  86.     public String getServletPath();
  87.  
  88.     /**
  89.      * Gets any optional extra path information following the servlet
  90.      * path of this request's URI, but immediately preceding its query
  91.      * string. Same as the CGI variable PATH_INFO.
  92.      *
  93.      * @return the optional path information following the servlet
  94.      * path, but before the query string, in this request's URI; null
  95.      * if this request's URI contains no extra path information
  96.      */
  97.     public String getPathInfo();
  98.  
  99.     /**
  100.      * Gets any optional extra path information following the servlet
  101.      * path of this request's URI, but immediately preceding its query
  102.      * string, and translates it to a real path.  Similar to the CGI
  103.      * variable PATH_TRANSLATED
  104.      *
  105.      * @return extra path information translated to a real path or null
  106.      * if no extra path information is in the request's URI
  107.      */
  108.     public String getPathTranslated();
  109.  
  110.     /**
  111.      * Gets any query string that is part of the HTTP request URI.
  112.      * Same as the CGI variable QUERY_STRING.
  113.      *
  114.      * @return query string that is part of this request's URI, or null
  115.      * if it contains no query string
  116.      */
  117.     public String getQueryString();
  118.  
  119.     /**
  120.      * Gets the name of the user making this request.  The user name is
  121.      * set with HTTP authentication.  Whether the user name will
  122.      * continue to be sent with each subsequent communication is
  123.      * browser-dependent.  Same as the CGI variable REMOTE_USER.
  124.      *
  125.      * @return the name of the user making this request, or null if not
  126.      * known.
  127.      */
  128.     public String getRemoteUser();
  129.  
  130.     /**
  131.      * Gets the authentication scheme of this request.  Same as the CGI
  132.      * variable AUTH_TYPE.
  133.      *
  134.      * @return this request's authentication scheme, or null if none.
  135.      */
  136.     public String getAuthType();
  137.  
  138.     /**
  139.      * Gets the value of the requested header field of this request.
  140.      * The case of the header field name is ignored.
  141.      * 
  142.      * @param name the String containing the name of the requested
  143.      * header field
  144.      * @return the value of the requested header field, or null if not
  145.      * known.
  146.      */
  147.     public String getHeader(String name); 
  148.  
  149.     /**
  150.      * Gets the value of the specified integer header field of this
  151.      * request.  The case of the header field name is ignored.  If the
  152.      * header can't be converted to an integer, the method throws a
  153.      * NumberFormatException.
  154.      * 
  155.      * @param name the String containing the name of the requested
  156.      * header field
  157.      * @return the value of the requested header field, or -1 if not
  158.      * found.
  159.      */
  160.     public int getIntHeader(String name);
  161.  
  162.     /**
  163.      * Gets the value of the requested date header field of this
  164.      * request.  If the header can't be converted to a date, the method
  165.      * throws an IllegalArgumentException.  The case of the header
  166.      * field name is ignored.
  167.      * 
  168.      * @param name the String containing the name of the requested
  169.      * header field
  170.      * @return the value the requested date header field, or -1 if not
  171.      * found.
  172.      */
  173.     public long getDateHeader(String name);
  174.  
  175.     /**
  176.      * Gets the header names for this request.
  177.      *
  178.      * @return an enumeration of strings representing the header names
  179.      * for this request. Some server implementations do not allow
  180.      * headers to be accessed in this way, in which case this method
  181.      * will return null.
  182.      */
  183.     public Enumeration getHeaderNames();
  184.  
  185.     /**
  186.      * Gets the current valid session associated with this request, if
  187.      * create is false or, if necessary, creates a new session for the
  188.      * request, if create is true.
  189.      *
  190.      * <p><b>Note</b>: to ensure the session is properly maintained,
  191.      * the servlet developer must call this method (at least once)
  192.      * before any output is written to the response.
  193.      *
  194.      * <p>Additionally, application-writers need to be aware that newly
  195.      * created sessions (that is, sessions for which
  196.      * <code>HttpSession.isNew</code> returns true) do not have any
  197.      * application-specific state.
  198.      *
  199.      * @return the session associated with this request or null if
  200.      * create was false and no valid session is associated
  201.      * with this request.
  202.      */
  203.     public HttpSession getSession (boolean create);
  204.    
  205.     /**
  206.      * Gets the session id specified with this request.  This may
  207.      * differ from the actual session id.  For example, if the request
  208.      * specified an id for an invalid session, then this will get a new
  209.      * session with a new id.
  210.      *
  211.      * @return the session id specified by this request, or null if the
  212.      * request did not specify a session id
  213.      * 
  214.      * @see #isRequestedSessionIdValid */
  215.     public String getRequestedSessionId ();
  216.  
  217.     /**
  218.      * Checks whether this request is associated with a session that
  219.      * is valid in the current session context.  If it is not valid,
  220.      * the requested session will never be returned from the
  221.      * <code>getSession</code> method.
  222.      * 
  223.      * @return true if this request is assocated with a session that is
  224.      * valid in the current session context.
  225.      *
  226.      * @see #getRequestedSessionId
  227.      * @see javax.servlet.http.HttpSessionContext
  228.      * @see #getSession
  229.      */
  230.     public boolean isRequestedSessionIdValid ();
  231.  
  232.     /**
  233.      * Checks whether the session id specified by this request came in
  234.      * as a cookie.  (The requested session may not be one returned by
  235.      * the <code>getSession</code> method.)
  236.      * 
  237.      * @return true if the session id specified by this request came in
  238.      * as a cookie; false otherwise
  239.      *
  240.      * @see #getSession
  241.      */
  242.     public boolean isRequestedSessionIdFromCookie ();
  243.  
  244.     /**
  245.      * Checks whether the session id specified by this request came in
  246.      * as part of the URL.  (The requested session may not be the one
  247.      * returned by the <code>getSession</code> method.)
  248.      * 
  249.      * @return true if the session id specified by the request for this
  250.      * session came in as part of the URL; false otherwise
  251.      *
  252.      * @see #getSession
  253.      */
  254.     public boolean isRequestedSessionIdFromUrl ();
  255.  
  256. }
  257.