home *** CD-ROM | disk | FTP | other *** search
/ Java Developer's Companion / Java Developer's Companion.iso / binaries / Windows / jsdk / src / javax / servlet / ServletRequest.java < prev    next >
Encoding:
Java Source  |  1997-07-18  |  6.3 KB  |  172 lines
  1. /*
  2.  * @(#)ServletRequest.java    1.33 97/05/22
  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;
  23.  
  24. import java.io.IOException;
  25. import java.util.Enumeration;
  26.  
  27. /**
  28.  * 
  29.  * This interface is for getting data from the client to the servlet
  30.  * for a service request.  Network service developers implement the
  31.  * ServletRequest interface.  The methods are then used by servlets
  32.  * when the service method is executed; the ServletRequest object is
  33.  * passed as an argument to the service method.
  34.  *
  35.  * <p>Some of the data provided by the ServletRequest object includes
  36.  * parameter names and values, attributes, and an input stream.
  37.  * Subclasses of ServletRequest can provide additional
  38.  * protocol-specific data.  For example, HTTP data is provided by the
  39.  * interface HttpServletRequest, which extends ServletRequest.  This
  40.  * framework provides the servlet's only access to this data.
  41.  * 
  42.  * @see javax.servlet.http.HttpServletRequest
  43.  *
  44.  * @version    1.33,05/22/97
  45.  * @author David Connelly */
  46.  
  47. public
  48. interface ServletRequest {
  49.     /**
  50.      * Returns the size of the request entity data, or -1 if not known.
  51.      * Same as the CGI variable CONTENT_LENGTH.
  52.      */
  53.     public int getContentLength();
  54.  
  55.     /**
  56.      * Returns the Internet Media Type of the request entity data, or
  57.      * null if not known. Same as the CGI variable CONTENT_TYPE.
  58.      */
  59.     public String getContentType();
  60.  
  61.     /**
  62.      * Returns the protocol and version of the request as a string of
  63.      * the form <code><protocol>/<major version>.<minor
  64.      * version></code>.  Same as the CGI variable SERVER_PROTOCOL.
  65.      */
  66.     public String getProtocol();
  67.  
  68.     /**
  69.      * Returns the scheme of the URL used in this request, for example
  70.      * "http", "https", or "ftp".  Different schemes have different
  71.      * rules for constructing URLs, as noted in RFC 1738.  The URL used
  72.      * to create a request may be reconstructed using this scheme, the
  73.      * server name and port, and additional information such as URIs.
  74.      */
  75.     public String getScheme();
  76.  
  77.     /**
  78.      * Returns the host name of the server that received the request.
  79.      * Same as the CGI variable SERVER_NAME.
  80.      */
  81.     public String getServerName();
  82.  
  83.     /**
  84.      * Returns the port number on which this request was received.
  85.      * Same as the CGI variable SERVER_PORT.
  86.      */
  87.     public int getServerPort();
  88.  
  89.     /**
  90.      * Returns the IP address of the agent that sent the request.
  91.      * Same as the CGI variable REMOTE_ADDR.
  92.      */
  93.     public String getRemoteAddr();
  94.  
  95.     /**
  96.      * Returns the fully qualified host name of the agent that sent the
  97.      * request. Same as the CGI variable REMOTE_HOST.
  98.      */
  99.     public String getRemoteHost();
  100.  
  101.     /**
  102.      * Applies alias rules to the specified virtual path and returns
  103.      * the corresponding real path, or null if the translation can not
  104.      * be performed for any reason.  For example, an HTTP servlet would
  105.      * resolve the path using the virtual docroot, if virtual hosting
  106.      * is enabled, and with the default docroot otherwise.  Calling
  107.      * this method with the string "/" as an argument returns the
  108.      * document root.
  109.      *
  110.      * @param path the virtual path to be translated to a real path */
  111.     String getRealPath(String path);
  112.  
  113.     /**
  114.      * Returns an input stream for reading the request body. 
  115.      */
  116.     public ServletInputStream getInputStream() throws IOException;  
  117.  
  118.     /**
  119.      * Returns a string containing the lone value of the specified
  120.      * parameter, or null if the parameter does not exist. For example,
  121.      * in an HTTP servlet this method would return the value of the
  122.      * specified query string parameter. Servlet writers should use
  123.      * this method only when they are sure that there is only one value
  124.      * for the parameter.  If the parameter has (or could have)
  125.      * multiple values, servlet writers should use
  126.      * getParameterValues. If a multiple valued parameter name is
  127.      * passed as an argument, the return value is implementation
  128.      * dependent.
  129.      *
  130.      * @param name the name of the parameter whose value is required.
  131.      * @see javax.servlet.ServletRequest#getParameterValues
  132.      */
  133.     public String getParameter(String name);
  134.  
  135.     /**
  136.      * 
  137.      * Returns the values of the specified parameter for the request as
  138.      * an array of strings, or null if the named parameter does not
  139.      * exist. For example, in an HTTP servlet this method would return
  140.      * the values of the specified query string or posted form as an
  141.      * array of strings.
  142.      *
  143.      * @param name the name of the parameter whose value is required.
  144.      * @see javax.servlet.ServletRequest#getParameter
  145.      */
  146.  
  147.     public String[] getParameterValues(String name);
  148.  
  149.     /**
  150.      * Returns the parameter names for this request as an enumeration
  151.      * of strings, or an empty enumeration if there are no parameters
  152.      * or the input stream is empty.  The input stream would be empty
  153.      * if all the data had been read from the stream returned by the
  154.      * method getInputStream.
  155.      */
  156.     public Enumeration getParameterNames();
  157.  
  158.     /**
  159.      * 
  160.      * Returns the value of the named attribute of the request, or
  161.      * null if the attribute does not exist.  This method allows
  162.      * access to request information not already provided by the other
  163.      * methods in this interface.  Attribute names should follow the
  164.      * same convention as package names.  The package names java.*,
  165.      * and javax.* are reserved for use by Javasoft, and com.sun.* is
  166.      * reserved for use by Sun Microsystems.
  167.      *
  168.      * @param name the name of the attribute whose value is required
  169.      */
  170.     public Object getAttribute(String name);
  171. }
  172.