ServletRequest.java
上传用户:tanyanyong
上传日期:2013-06-23
资源大小:1355k
文件大小:18k
源码类别:

电子政务应用

开发平台:

MultiPlatform

  1. /*
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 1999 The Apache Software Foundation.  All rights 
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer. 
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution, if
  20.  *    any, must include the following acknowlegement:  
  21.  *       "This product includes software developed by the 
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowlegement may appear in the software itself,
  24.  *    if and wherever such third-party acknowlegements normally appear.
  25.  *
  26.  * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
  27.  *    Foundation" must not be used to endorse or promote products derived
  28.  *    from this software without prior written permission. For written 
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache"
  32.  *    nor may "Apache" appear in their names without prior written
  33.  *    permission of the Apache Group.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  *
  54.  * ====================================================================
  55.  *
  56.  * This source code implements specifications defined by the Java
  57.  * Community Process. In order to remain compliant with the specification
  58.  * DO NOT add / change / or delete method signatures!
  59.  */ 
  60. package javax.servlet;
  61. import java.io.BufferedReader;
  62. import java.io.IOException;
  63. import java.io.UnsupportedEncodingException;
  64. import java.util.Enumeration;
  65. import java.util.Locale;
  66. /**
  67.  * Defines an object to provide client request information to a servlet.  The
  68.  * servlet container creates a <code>ServletRequest</code> object and passes
  69.  * it as an argument to the servlet's <code>service</code> method.
  70.  *
  71.  * <p>A <code>ServletRequest</code> object provides data including
  72.  * parameter name and values, attributes, and an input stream.
  73.  * Interfaces that extend <code>ServletRequest</code> can provide
  74.  * additional protocol-specific data (for example, HTTP data is
  75.  * provided by {@link javax.servlet.http.HttpServletRequest}.
  76.  * 
  77.  * @author  Various
  78.  * @version  $Version$
  79.  *
  80.  * @see  javax.servlet.http.HttpServletRequest
  81.  *
  82.  */
  83. public interface ServletRequest {
  84.     /**
  85.      *
  86.      * Returns the value of the named attribute as an <code>Object</code>,
  87.      * or <code>null</code> if no attribute of the given name exists. 
  88.      *
  89.      * <p> Attributes can be set two ways.  The servlet container may set
  90.      * attributes to make available custom information about a request.
  91.      * For example, for requests made using HTTPS, the attribute
  92.      * <code>javax.servlet.request.X509Certificate</code> can be used to
  93.      * retrieve information on the certificate of the client.  Attributes
  94.      * can also be set programatically using 
  95.      * {@link ServletRequest#setAttribute}.  This allows information to be
  96.      * embedded into a request before a {@link RequestDispatcher} call.
  97.      *
  98.      * <p>Attribute names should follow the same conventions as package
  99.      * names. This specification reserves names matching <code>java.*</code>,
  100.      * <code>javax.*</code>, and <code>sun.*</code>. 
  101.      *
  102.      * @param name a <code>String</code> specifying the name of 
  103.      * the attribute
  104.      *
  105.      * @return an <code>Object</code> containing the value 
  106.      * of the attribute, or <code>null</code> if
  107.      * the attribute does not exist
  108.      *
  109.      */
  110.     public Object getAttribute(String name);
  111.     
  112.     
  113.     /**
  114.      * Returns an <code>Enumeration</code> containing the
  115.      * names of the attributes available to this request. 
  116.      * This method returns an empty <code>Enumeration</code>
  117.      * if the request has no attributes available to it.
  118.      * 
  119.      *
  120.      * @return an <code>Enumeration</code> of strings 
  121.      * containing the names 
  122.      *  of the request's attributes
  123.      *
  124.      */
  125.     public Enumeration getAttributeNames();
  126.     
  127.     
  128.     
  129.     
  130.     /**
  131.      * Returns the name of the character encoding used in the body of this
  132.      * request. This method returns <code>null</code> if the request
  133.      * does not specify a character encoding
  134.      * 
  135.      *
  136.      * @return a <code>String</code> containing the name of 
  137.      * the chararacter encoding, or <code>null</code>
  138.      * if the request does not specify a character encoding
  139.      *
  140.      */
  141.     public String getCharacterEncoding();
  142.     
  143.     
  144.     
  145.     
  146.     /**
  147.      * Returns the length, in bytes, of the request body 
  148.      * and made available by the input stream, or -1 if the
  149.      * length is not known. For HTTP servlets, same as the value
  150.      * of the CGI variable CONTENT_LENGTH.
  151.      *
  152.      * @return an integer containing the length of the 
  153.      *  request body or -1 if the length is not known
  154.      *
  155.      */
  156.     public int getContentLength();
  157.     
  158.     
  159.     
  160.     /**
  161.      * Returns the MIME type of the body of the request, or 
  162.      * <code>null</code> if the type is not known. For HTTP servlets, 
  163.      * same as the value of the CGI variable CONTENT_TYPE.
  164.      *
  165.      * @return a <code>String</code> containing the name 
  166.      * of the MIME type of 
  167.      *  the request, or -1 if the type is not known
  168.      *
  169.      */
  170.     public String getContentType();
  171.     
  172.     
  173.     
  174.     /**
  175.      * Retrieves the body of the request as binary data using
  176.      * a {@link ServletInputStream}.  Either this method or 
  177.      * {@link #getReader} may be called to read the body, not both.
  178.      *
  179.      * @return a {@link ServletInputStream} object containing
  180.      *  the body of the request
  181.      *
  182.      * @exception IllegalStateException  if the {@link #getReader} method
  183.      *   has already been called for this request
  184.      *
  185.      * @exception IOException     if an input or output exception occurred
  186.      *
  187.      */
  188.     public ServletInputStream getInputStream() throws IOException; 
  189.      
  190.     
  191.     
  192.     /**
  193.      * Returns the value of a request parameter as a <code>String</code>,
  194.      * or <code>null</code> if the parameter does not exist. Request parameters
  195.      * are extra information sent with the request.  For HTTP servlets,
  196.      * parameters are contained in the query string or posted form data.
  197.      *
  198.      * <p>You should only use this method when you are sure the
  199.      * parameter has only one value. If the parameter might have
  200.      * more than one value, use {@link #getParameterValues}.
  201.      *
  202.      * <p>If you use this method with a multivalued
  203.      * parameter, the value returned is equal to the first value
  204.      * in the array returned by <code>getParameterValues</code>.
  205.      *
  206.      * <p>If the parameter data was sent in the request body, such as occurs
  207.      * with an HTTP POST request, then reading the body directly via {@link
  208.      * #getInputStream} or {@link #getReader} can interfere
  209.      * with the execution of this method.
  210.      *
  211.      * @param name  a <code>String</code> specifying the 
  212.      * name of the parameter
  213.      *
  214.      * @return a <code>String</code> representing the 
  215.      * single value of the parameter
  216.      *
  217.      * @see  #getParameterValues
  218.      *
  219.      */
  220.     public String getParameter(String name);
  221.     
  222.     
  223.     
  224.     /**
  225.      *
  226.      * Returns an <code>Enumeration</code> of <code>String</code>
  227.      * objects containing the names of the parameters contained
  228.      * in this request. If the request has 
  229.      * no parameters, the method returns an 
  230.      * empty <code>Enumeration</code>. 
  231.      *
  232.      * @return an <code>Enumeration</code> of <code>String</code>
  233.      * objects, each <code>String</code> containing
  234.      *  the name of a request parameter; or an 
  235.      * empty <code>Enumeration</code> if the
  236.      * request has no parameters
  237.      *
  238.      */
  239.      
  240.     public Enumeration getParameterNames();
  241.     
  242.     
  243.     
  244.     /**
  245.      * Returns an array of <code>String</code> objects containing 
  246.      * all of the values the given request parameter has, or 
  247.      * <code>null</code> if the parameter does not exist.
  248.      *
  249.      * <p>If the parameter has a single value, the array has a length
  250.      * of 1.
  251.      *
  252.      * @param name a <code>String</code> containing the name of 
  253.      * the parameter whose value is requested
  254.      *
  255.      * @return an array of <code>String</code> objects 
  256.      * containing the parameter's values
  257.      *
  258.      * @see #getParameter
  259.      *
  260.      */
  261.     public String[] getParameterValues(String name);
  262.     
  263.     
  264.     
  265.     /**
  266.      * Returns the name and version of the protocol the request uses
  267.      * in the form <i>protocol/majorVersion.minorVersion</i>, for 
  268.      * example, HTTP/1.1. For HTTP servlets, the value
  269.      * returned is the same as the value of the CGI variable 
  270.      * <code>SERVER_PROTOCOL</code>.
  271.      *
  272.      * @return a <code>String</code> containing the protocol 
  273.      * name and version number
  274.      *
  275.      */
  276.     
  277.     public String getProtocol();
  278.     
  279.     
  280.     
  281.     /**
  282.      * Returns the name of the scheme used to make this request, 
  283.      * for example,
  284.      * <code>http</code>, <code>https</code>, or <code>ftp</code>.
  285.      * Different schemes have different rules for constructing URLs,
  286.      * as noted in RFC 1738.
  287.      *
  288.      * @return a <code>String</code> containing the name 
  289.      * of the scheme used to make this request
  290.      *
  291.      */
  292.     public String getScheme();
  293.     
  294.     
  295.     
  296.     /**
  297.      * Returns the host name of the server that received the request.
  298.      * For HTTP servlets, same as the value of the CGI variable 
  299.      * <code>SERVER_NAME</code>.
  300.      *
  301.      * @return a <code>String</code> containing the name 
  302.      * of the server to which the request was sent
  303.      */
  304.     public String getServerName();
  305.     
  306.     
  307.     
  308.     /**
  309.      * Returns the port number on which this request was received.
  310.      * For HTTP servlets, same as the value of the CGI variable 
  311.      * <code>SERVER_PORT</code>.
  312.      *
  313.      * @return an integer specifying the port number
  314.      *
  315.      */
  316.     public int getServerPort();
  317.     
  318.     
  319.     
  320.     /**
  321.      * Retrieves the body of the request as character data using
  322.      * a <code>BufferedReader</code>.  The reader translates the character
  323.      * data according to the character encoding used on the body.
  324.      * Either this method or {@link #getReader} may be called to read the
  325.      * body, not both.
  326.      * 
  327.      *
  328.      * @return a <code>BufferedReader</code>
  329.      * containing the body of the request
  330.      *
  331.      * @exception UnsupportedEncodingException  if the character set encoding
  332.      *  used is not supported and the 
  333.      * text cannot be decoded
  334.      *
  335.      * @exception IllegalStateException    if {@link #getInputStream} method
  336.      *  has been called on this request
  337.      *
  338.      * @exception IOException   if an input or output exception occurred
  339.      *
  340.      * @see  #getInputStream
  341.      *
  342.      */
  343.     public BufferedReader getReader() throws IOException;
  344.     
  345.     
  346.     
  347.     /**
  348.      * Returns the Internet Protocol (IP) address of the client 
  349.      * that sent the request.  For HTTP servlets, same as the value of the 
  350.      * CGI variable <code>REMOTE_ADDR</code>.
  351.      *
  352.      * @return a <code>String</code> containing the 
  353.      * IP address of the client that sent the request
  354.      *
  355.      */
  356.     
  357.     public String getRemoteAddr();
  358.     
  359.     
  360.     
  361.     /**
  362.      * Returns the fully qualified name of the client that sent the
  363.      * request, or the IP address of the client if the name cannot be
  364.      * determined. For HTTP servlets, same as the value of the CGI variable 
  365.      * <code>REMOTE_HOST</code>.
  366.      *
  367.      * @return a <code>String</code> containing the fully qualified name 
  368.      * of the client
  369.      *
  370.      */
  371.     public String getRemoteHost();
  372.     
  373.     
  374.     
  375.     /**
  376.      *
  377.      * Stores an attribute in this request.
  378.      * Attributes are reset between requests.  This method is most
  379.      * often used in conjunction with {@link RequestDispatcher}.
  380.      *
  381.      * <p>Attribute names should follow the same conventions as
  382.      * package names. Names beginning with <code>java.*</code>,
  383.      * <code>javax.*</code>, and <code>com.sun.*</code>, are
  384.      * reserved for use by Sun Microsystems.
  385.      *
  386.      *
  387.      * @param name a <code>String</code> specifying 
  388.      * the name of the attribute
  389.      *
  390.      * @param o the <code>Object</code> to be stored
  391.      *
  392.      */
  393.     public void setAttribute(String name, Object o);
  394.     
  395.     
  396.     
  397.     /**
  398.      *
  399.      * Removes an attribute from this request.  This method is not
  400.      * generally needed as attributes only persist as long as the request
  401.      * is being handled.
  402.      *
  403.      * <p>Attribute names should follow the same conventions as
  404.      * package names. Names beginning with <code>java.*</code>,
  405.      * <code>javax.*</code>, and <code>com.sun.*</code>, are
  406.      * reserved for use by Sun Microsystems.
  407.      *
  408.      *
  409.      * @param name a <code>String</code> specifying 
  410.      * the name of the attribute to remove
  411.      *
  412.      */
  413.     public void removeAttribute(String name);
  414.     
  415.     
  416.     
  417.     /**
  418.      *
  419.      * Returns the preferred <code>Locale</code> that the client will 
  420.      * accept content in, based on the Accept-Language header.
  421.      * If the client request doesn't provide an Accept-Language header,
  422.      * this method returns the default locale for the server.
  423.      *
  424.      *
  425.      * @return the preferred <code>Locale</code> for the client
  426.      *
  427.      */
  428.     public Locale getLocale();
  429.     
  430.     
  431.     
  432.     /**
  433.      *
  434.      * Returns an <code>Enumeration</code> of <code>Locale</code> objects
  435.      * indicating, in decreasing order starting with the preferred locale, the
  436.      * locales that are acceptable to the client based on the Accept-Language
  437.      * header.
  438.      * If the client request doesn't provide an Accept-Language header,
  439.      * this method returns an <code>Enumeration</code> containing one 
  440.      * <code>Locale</code>, the default locale for the server.
  441.      *
  442.      *
  443.      * @return an <code>Enumeration</code> of preferred 
  444.      *                  <code>Locale</code> objects for the client
  445.      *
  446.      */
  447.     public Enumeration getLocales();
  448.     
  449.     
  450.     
  451.     /**
  452.      *
  453.      * Returns a boolean indicating whether this request was made using a
  454.      * secure channel, such as HTTPS.
  455.      *
  456.      *
  457.      * @return a boolean indicating if the request was made using a
  458.      *                  secure channel
  459.      *
  460.      */
  461.     public boolean isSecure();
  462.     
  463.     
  464.     
  465.     /**
  466.      *
  467.      * Returns a {@link RequestDispatcher} object that acts as a wrapper for
  468.      * the resource located at the given path.  
  469.      * A <code>RequestDispatcher</code> object can be used to forward
  470.      * a request to the resource or to include the resource in a response.
  471.      * The resource can be dynamic or static.
  472.      *
  473.      * <p>The pathname specified may be relative, although it cannot extend
  474.      * outside the current servlet context.  If the path begins with 
  475.      * a "/" it is interpreted as relative to the current context root.  
  476.      * This method returns <code>null</code> if the servlet container
  477.      * cannot return a <code>RequestDispatcher</code>.
  478.      *
  479.      * <p>The difference between this method and {@link
  480.      * ServletContext#getRequestDispatcher} is that this method can take a
  481.      * relative path.
  482.      *
  483.      * @param path      a <code>String</code> specifying the pathname
  484.      *                  to the resource
  485.      *
  486.      * @return          a <code>RequestDispatcher</code> object
  487.      *                  that acts as a wrapper for the resource
  488.      *                  at the specified path
  489.      *
  490.      * @see             RequestDispatcher
  491.      * @see             ServletContext#getRequestDispatcher
  492.      *
  493.      */
  494.     public RequestDispatcher getRequestDispatcher(String path);
  495.     
  496.     
  497.     
  498.     /**
  499.      * 
  500.      * @deprecated  As of Version 2.1 of the Java Servlet API,
  501.      *  use {@link ServletContext#getRealPath} instead.
  502.      *
  503.      */
  504.     public String getRealPath(String path);
  505.     
  506.     
  507. }