home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgLangD.iso / VCAFE.3.0A / Main.bin / ServletRequest.java < prev    next >
Encoding:
Java Source  |  1998-04-21  |  8.8 KB  |  235 lines
  1. /*
  2.  * @(#)ServletRequest.java    1.49 98/04/15
  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.BufferedReader;
  25. import java.io.IOException;
  26. import java.io.UnsupportedEncodingException;
  27. import java.util.Enumeration;
  28.  
  29. /**
  30.  * This interface is for getting data from the client to the servlet
  31.  * for a service request.  Network service developers implement the
  32.  * ServletRequest interface.  The methods are then used by servlets
  33.  * when the service method is executed; the ServletRequest object is
  34.  * passed as an argument to the service method.
  35.  *
  36.  * <P> Some of the data provided by the ServletRequest object includes
  37.  * parameter names and values, attributes, and an input stream.
  38.  * Subclasses of ServletRequest can provide additional
  39.  * protocol-specific data.  For example, HTTP data is provided by the
  40.  * interface HttpServletRequest, which extends ServletRequest.  This
  41.  * framework provides the servlet's only access to this data.
  42.  *
  43.  * <P> MIME bodies are either text or binary data.  Use getReader to
  44.  * handle text, including the character encodings.  The getInputStream
  45.  * call should be used to handle binary data.  Multipart MIME bodies
  46.  * are treated as binary data, since the headers are US-ASCII data.
  47.  * 
  48.  * @see javax.servlet.http.HttpServletRequest
  49.  *
  50.  * @version    1.49,04/15/98
  51.  */
  52.  
  53. public
  54. interface ServletRequest {
  55.     /**
  56.      * Returns the size of the request entity data, or -1 if not known.
  57.      * Same as the CGI variable CONTENT_LENGTH.
  58.      */
  59.     public int getContentLength();
  60.  
  61.     /**
  62.      * Returns the Internet Media Type of the request entity data, or
  63.      * null if not known. Same as the CGI variable CONTENT_TYPE.
  64.      */
  65.     public String getContentType();
  66.  
  67.     /**
  68.      * Returns the protocol and version of the request as a string of
  69.      * the form <code><protocol>/<major version>.<minor
  70.      * version></code>.  Same as the CGI variable SERVER_PROTOCOL.
  71.      */
  72.     public String getProtocol();
  73.  
  74.     /**
  75.      * Returns the scheme of the URL used in this request, for example
  76.      * "http", "https", or "ftp".  Different schemes have different
  77.      * rules for constructing URLs, as noted in RFC 1738.  The URL used
  78.      * to create a request may be reconstructed using this scheme, the
  79.      * server name and port, and additional information such as URIs.
  80.      */
  81.     public String getScheme();
  82.  
  83.     /**
  84.      * Returns the host name of the server that received the request.
  85.      * Same as the CGI variable SERVER_NAME.
  86.      */
  87.     public String getServerName();
  88.  
  89.     /**
  90.      * Returns the port number on which this request was received.
  91.      * Same as the CGI variable SERVER_PORT.
  92.      */
  93.     public int getServerPort();
  94.  
  95.     /**
  96.      * Returns the IP address of the agent that sent the request.
  97.      * Same as the CGI variable REMOTE_ADDR.
  98.      */
  99.     public String getRemoteAddr();
  100.  
  101.     /**
  102.      * Returns the fully qualified host name of the agent that sent the
  103.      * request. Same as the CGI variable REMOTE_HOST.
  104.      */
  105.     public String getRemoteHost();
  106.  
  107.     /**
  108.      * Applies alias rules to the specified virtual path and returns
  109.      * the corresponding real path, or null if the translation can not
  110.      * be performed for any reason.  For example, an HTTP servlet would
  111.      * resolve the path using the virtual docroot, if virtual hosting
  112.      * is enabled, and with the default docroot otherwise.  Calling
  113.      * this method with the string "/" as an argument returns the
  114.      * document root.
  115.      *
  116.      * @param path the virtual path to be translated to a real path
  117.      */
  118.     public String getRealPath(String path);
  119.  
  120.     /**
  121.      * Returns an input stream for reading binary data in the request body.
  122.      *
  123.      * @see getReader
  124.      * @exception IllegalStateException if getReader has been
  125.      *    called on this same request.
  126.      * @exception IOException on other I/O related errors.
  127.      */
  128.     public ServletInputStream getInputStream() throws IOException;  
  129.  
  130.     /**
  131.      * Returns a string containing the lone value of the specified
  132.      * parameter, or null if the parameter does not exist. For example,
  133.      * in an HTTP servlet this method would return the value of the
  134.      * specified query string parameter. Servlet writers should use
  135.      * this method only when they are sure that there is only one value
  136.      * for the parameter.  If the parameter has (or could have)
  137.      * multiple values, servlet writers should use
  138.      * getParameterValues. If a multiple valued parameter name is
  139.      * passed as an argument, the return value is implementation
  140.      * dependent.
  141.      *
  142.      * @see #getParameterValues
  143.      *
  144.      * @param name the name of the parameter whose value is required.
  145.      */
  146.     public String getParameter(String name);
  147.  
  148.     /**
  149.      * Returns the values of the specified parameter for the request as
  150.      * an array of strings, or null if the named parameter does not
  151.      * exist. For example, in an HTTP servlet this method would return
  152.      * the values of the specified query string or posted form as an
  153.      * array of strings.
  154.      *
  155.      * @param name the name of the parameter whose value is required.
  156.      * @see javax.servlet.ServletRequest#getParameter
  157.      */
  158.     public String[] getParameterValues(String name);
  159.  
  160.     /**
  161.      * Returns the parameter names for this request as an enumeration
  162.      * of strings, or an empty enumeration if there are no parameters
  163.      * or the input stream is empty.  The input stream would be empty
  164.      * if all the data had been read from the stream returned by the
  165.      * method getInputStream.
  166.      */
  167.     public Enumeration getParameterNames();
  168.  
  169.     /**
  170.      * Returns the value of the named attribute of the request, or
  171.      * null if the attribute does not exist.  This method allows
  172.      * access to request information not already provided by the other
  173.      * methods in this interface.  Attribute names should follow the
  174.      * same convention as package names. 
  175.      * The following predefined attributes are provided.
  176.      *
  177.      * <TABLE BORDER>
  178.      * <tr>
  179.      *    <th>Attribute Name</th>
  180.      *    <th>Attribute Type</th>
  181.      *    <th>Description</th>
  182.      *    </tr>
  183.      *
  184.      * <tr>
  185.      *    <td VALIGN=TOP>javax.net.ssl.cipher_suite</td>
  186.      *    <td VALIGN=TOP>string</td>
  187.      *    <td>The string name of the SSL cipher suite in use, if the
  188.      *        request was made using SSL</td>
  189.      *    </tr>
  190.      *
  191.      * <tr>
  192.      *    <td VALIGN=TOP>javax.net.ssl.peer_certificates</td>
  193.      *    <td VALIGN=TOP>array of javax.security.cert.X509Certificate</td>
  194.      *    <td>The chain of X.509 certificates which authenticates the client.
  195.      *        This is only available when SSL is used with client
  196.      *        authentication is used.</td>
  197.      *    </tr>
  198.      *
  199.      * <tr>
  200.      *    <td VALIGN=TOP>javax.net.ssl.session</td>
  201.      *    <td VALIGN=TOP>javax.net.ssl.SSLSession</td>
  202.      *    <td>An SSL session object, if the request was made using SSL.</td>
  203.      *    </tr>
  204.      *
  205.      * </TABLE>
  206.      *
  207.      * <BR>
  208.      * <P>The package (and hence attribute) names beginning with java.*,
  209.      * and javax.* are reserved for use by Javasoft. Similarly, com.sun.*
  210.      * is reserved for use by Sun Microsystems.
  211.      *
  212.      * @param name the name of the attribute whose value is required
  213.      */
  214.     public Object getAttribute(String name);
  215.  
  216.     /**
  217.      * Returns a buffered reader for reading text in the request body.
  218.      * This translates character set encodings as appropriate. 
  219.      *
  220.      * @see getInputStream
  221.      *
  222.      * @exception UnsupportedEncodingException if the character set encoding
  223.      *  is unsupported, so the text can't be correctly decoded.
  224.      * @exception IllegalStateException if getInputStream has been
  225.      *    called on this same request.
  226.      * @exception IOException on other I/O related errors.
  227.      */
  228.     public BufferedReader getReader () throws IOException;
  229.  
  230.     /**
  231.      * Returns the character set encoding for the input of this request.
  232.      */
  233.     public String getCharacterEncoding ();
  234. }
  235.