HttpServletRequest.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.http;
  61. import javax.servlet.ServletRequest;
  62. import java.util.Enumeration;
  63. /**
  64.  *
  65.  * Extends the {@link javax.servlet.ServletRequest} interface
  66.  * to provide request information for HTTP servlets. 
  67.  *
  68.  * <p>The servlet container creates an <code>HttpServletRequest</code> 
  69.  * object and passes it as an argument to the servlet's service
  70.  * methods (<code>doGet</code>, <code>doPost</code>, etc).
  71.  *
  72.  *
  73.  * @author  Various
  74.  * @version $Version$
  75.  *
  76.  *
  77.  */
  78. public interface HttpServletRequest extends ServletRequest {
  79.     /**
  80.      * Returns the name of the authentication scheme used to protect
  81.      * the servlet, for example, "BASIC" or "SSL," or <code>null</code>
  82.      * if the servlet was not protected. 
  83.      *
  84.      * <p>Same as the value of the CGI variable AUTH_TYPE.
  85.      *
  86.      *
  87.      * @return a <code>String</code> specifying the name of
  88.      * the authentication scheme, or
  89.      * <code>null</code> if the request was not
  90.      * authenticated
  91.      *
  92.      */
  93.    
  94.     public String getAuthType();
  95.     
  96.    
  97.     
  98.     /**
  99.      *
  100.      * Returns an array containing all of the <code>Cookie</code>
  101.      * objects the client sent with this request.
  102.      * This method returns <code>null</code> if no cookies were sent.
  103.      *
  104.      * @return an array of all the <code>Cookies</code>
  105.      * included with this request, or <code>null</code>
  106.      * if the request has no cookies
  107.      *
  108.      *
  109.      */
  110.     public Cookie[] getCookies();
  111.     
  112.     
  113.     
  114.     /**
  115.      *
  116.      * Returns the value of the specified request header
  117.      * as a <code>long</code> value that represents a 
  118.      * <code>Date</code> object. Use this method with
  119.      * headers that contain dates, such as
  120.      * <code>If-Modified-Since</code>. 
  121.      *
  122.      * <p>The date is returned as
  123.      * the number of milliseconds since January 1, 1970 GMT.
  124.      * The header name is case insensitive.
  125.      *
  126.      * <p>If the request did not have a header of the
  127.      * specified name, this method returns -1. If the header
  128.      * can't be converted to a date, the method throws
  129.      * an <code>IllegalArgumentException</code>.
  130.      *
  131.      * @param name a <code>String</code> specifying the
  132.      * name of the header
  133.      *
  134.      * @return a <code>long</code> value
  135.      * representing the date specified
  136.      * in the header expressed as
  137.      * the number of milliseconds
  138.      * since January 1, 1970 GMT,
  139.      * or -1 if the named header
  140.      * was not included with the
  141.      * reqest
  142.      *
  143.      * @exception IllegalArgumentException If the header value
  144.      * can't be converted
  145.      * to a date
  146.      *
  147.      */
  148.     public long getDateHeader(String name);
  149.     
  150.     
  151.     
  152.     /**
  153.      *
  154.      * Returns the value of the specified request header
  155.      * as a <code>String</code>. If the request did not include a header
  156.      * of the specified name, this method returns <code>null</code>.
  157.      * The header name is case insensitive. You can use
  158.      * this method with any request header.
  159.      *
  160.      * @param name a <code>String</code> specifying the
  161.      * header name
  162.      *
  163.      * @return a <code>String</code> containing the
  164.      * value of the requested
  165.      * header, or <code>null</code>
  166.      * if the request does not
  167.      * have a header of that name
  168.      *
  169.      */
  170.     public String getHeader(String name); 
  171.     /**
  172.      *
  173.      * Returns all the values of the specified request header
  174.      * as an <code>Enumeration</code> of <code>String</code> objects.
  175.      *
  176.      * <p>Some headers, such as <code>Accept-Language</code> can be sent
  177.      * by clients as several headers each with a different value rather than
  178.      * sending the header as a comma separated list.
  179.      *
  180.      * <p>If the request did not include any headers
  181.      * of the specified name, this method returns an empty
  182.      * <code>Enumeration</code>.
  183.      * The header name is case insensitive. You can use
  184.      * this method with any request header.
  185.      *
  186.      * @param name a <code>String</code> specifying the
  187.      * header name
  188.      *
  189.      * @return a <code>Enumeration</code> containing the
  190.      * values of the requested
  191.      * header, or <code>null</code>
  192.      * if the request does not
  193.      * have any headers of that name
  194.      *
  195.      */
  196.     public Enumeration getHeaders(String name); 
  197.     
  198.     
  199.     
  200.     
  201.     /**
  202.      *
  203.      * Returns an enumeration of all the header names
  204.      * this request contains. If the request has no
  205.      * headers, this method returns an empty enumeration.
  206.      *
  207.      * <p>Some servlet containers do not allow do not allow
  208.      * servlets to access headers using this method, in
  209.      * which case this method returns <code>null</code>
  210.      *
  211.      * @return an enumeration of all the
  212.      * header names sent with this
  213.      * request; if the request has
  214.      * no headers, an empty enumeration;
  215.      * if the servlet container does not
  216.      * allow servlets to use this method,
  217.      * <code>null</code>
  218.      *
  219.      */
  220.     public Enumeration getHeaderNames();
  221.     
  222.     
  223.     
  224.     /**
  225.      *
  226.      * Returns the value of the specified request header
  227.      * as an <code>int</code>. If the request does not have a header
  228.      * of the specified name, this method returns -1. If the
  229.      * header cannot be converted to an integer, this method
  230.      * throws a <code>NumberFormatException</code>.
  231.      *
  232.      * <p>The header name is case insensitive.
  233.      *
  234.      * @param name a <code>String</code> specifying the name
  235.      * of a request header
  236.      *
  237.      * @return an integer expressing the value 
  238.      *  of the request header or -1
  239.      * if the request doesn't have a
  240.      * header of this name
  241.      *
  242.      * @exception NumberFormatException If the header value
  243.      * can't be converted
  244.      * to an <code>int</code>
  245.      */
  246.     public int getIntHeader(String name);
  247.     
  248.     
  249.     
  250.     /**
  251.      *
  252.      * Returns the name of the HTTP method with which this 
  253.      * request was made, for example, GET, POST, or PUT.
  254.      * Same as the value of the CGI variable REQUEST_METHOD.
  255.      *
  256.      * @return a <code>String</code> 
  257.      * specifying the name
  258.      * of the method with which
  259.      * this request was made
  260.      *
  261.      */
  262.  
  263.     public String getMethod();
  264.     
  265.     
  266.     
  267.     /**
  268.      *
  269.      * Returns any extra path information associated with
  270.      * the URL the client sent when it made this request.
  271.      * The extra path information follows the servlet path
  272.      * but precedes the query string.
  273.      * This method returns <code>null</code> if there
  274.      * was no extra path information.
  275.      *
  276.      * <p>Same as the value of the CGI variable PATH_INFO.
  277.      *
  278.      *
  279.      * @return a <code>String</code> specifying 
  280.      * extra path information that comes
  281.      * after the servlet path but before
  282.      * the query string in the request URL;
  283.      * or <code>null</code> if the URL does not have
  284.      * any extra path information
  285.      *
  286.      */
  287.      
  288.     public String getPathInfo();
  289.     
  290.  
  291.     /**
  292.      *
  293.      * Returns any extra path information after the servlet name
  294.      * but before the query string, and translates it to a real
  295.      * path. Same as the value of the CGI variable PATH_TRANSLATED.
  296.      *
  297.      * <p>If the URL does not have any extra path information,
  298.      * this method returns <code>null</code>.
  299.      *
  300.      *
  301.      * @return a <code>String</code> specifying the
  302.      * real path, or <code>null</code> if
  303.      * the URL does not have any extra path
  304.      * information
  305.      *
  306.      *
  307.      */
  308.     public String getPathTranslated();
  309.     
  310.  
  311.     /**
  312.      *
  313.      * Returns the portion of the request URI that indicates the context
  314.      * of the request.  The context path always comes first in a request
  315.      * URI.  The path starts with a "/" character but does not end with a "/"
  316.      * character.  For servlets in the default (root) context, this method
  317.      * returns "".
  318.      *
  319.      *
  320.      * @return a <code>String</code> specifying the
  321.      * portion of the request URI that indicates the context
  322.      * of the request
  323.      *
  324.      *
  325.      */
  326.     public String getContextPath();
  327.     
  328.     
  329.     
  330.     /**
  331.      *
  332.      * Returns the query string that is contained in the request
  333.      * URL after the path. This method returns <code>null</code>
  334.      * if the URL does not have a query string. Same as the value
  335.      * of the CGI variable QUERY_STRING.
  336.      *
  337.      * @return a <code>String</code> containing the query
  338.      * string or <code>null</code> if the URL 
  339.      * contains no query string
  340.      *
  341.      */
  342.     public String getQueryString();
  343.     
  344.     
  345.     
  346.     /**
  347.      *
  348.      * Returns the login of the user making this request, if the
  349.      * user has been authenticated, or <code>null</code> if the user 
  350.      * has not been authenticated.
  351.      * Whether the user name is sent with each subsequent request
  352.      * depends on the browser and type of authentication. Same as the 
  353.      * value of the CGI variable REMOTE_USER.
  354.      *
  355.      * @return a <code>String</code> specifying the login
  356.      * of the user making this request, or <code>null</code
  357.      * if the user login is not known
  358.      *
  359.      */
  360.     public String getRemoteUser();
  361.     
  362.     
  363.     
  364.     /**
  365.      *
  366.      * Returns a boolean indicating whether the authenticated user is included
  367.      * in the specified logical "role".  Roles and role membership can be
  368.      * defined using deployment descriptors.  If the user has not been
  369.      * authenticated, the method returns <code>false</code>.
  370.      *
  371.      * @param role a <code>String</code> specifying the name
  372.      * of the role
  373.      *
  374.      * @return a <code>boolean</code> indicating whether
  375.      * the user making this request belongs to a given role;
  376.      * <code>false</code> if the user has not been 
  377.      * authenticated
  378.      *
  379.      */
  380.     public boolean isUserInRole(String role);
  381.     
  382.     
  383.     
  384.     /**
  385.      *
  386.      * Returns a <code>java.security.Principal</code> object containing
  387.      * the name of the current authenticated user. If the user has not been
  388.      * authenticated, the method returns <code>null</code>.
  389.      *
  390.      * @return a <code>java.security.Principal</code> containing
  391.      * the name of the user making this request;
  392.      * <code>null</code> if the user has not been 
  393.      * authenticated
  394.      *
  395.      */
  396.     public java.security.Principal getUserPrincipal();
  397.     
  398.     
  399.     
  400.     /**
  401.      *
  402.      * Returns the session ID specified by the client. This may
  403.      * not be the same as the ID of the actual session in use.
  404.      * For example, if the request specified an old (expired)
  405.      * session ID and the server has started a new session, this
  406.      * method gets a new session with a new ID. If the request
  407.      * did not specify a session ID, this method returns
  408.      * <code>null</code>.
  409.      *
  410.      *
  411.      * @return a <code>String</code> specifying the session
  412.      * ID, or <code>null</code> if the request did
  413.      * not specify a session ID
  414.      *
  415.      * @see #isRequestedSessionIdValid
  416.      *
  417.      */
  418.     public String getRequestedSessionId();
  419.     
  420.     
  421.     
  422.     
  423.     /**
  424.      *
  425.      * Returns the part of this request's URL from the protocol
  426.      * name up to the query string in the first line of the HTTP request.
  427.      * For example:
  428.      *
  429.      * <blockquote>
  430.      * <table>
  431.      * <tr align=left><th>First line of HTTP request<th>
  432.      * <th>Returned Value
  433.      * <tr><td>POST /some/path.html HTTP/1.1<td><td>/some/path.html
  434.      * <tr><td>GET http://foo.bar/a.html HTTP/1.0
  435.      * <td><td>http://foo.bar/a.html
  436.      * <tr><td>HEAD /xyz?a=b HTTP/1.1<td><td>/xyz
  437.      * </table>
  438.      * </blockquote>
  439.      *
  440.      * <p>To reconstruct an URL with a scheme and host, use
  441.      * {@link HttpUtils#getRequestURL}.
  442.      *
  443.      * @return a <code>String</code> containing
  444.      * the part of the URL from the 
  445.      * protocol name up to the query string
  446.      *
  447.      * @see HttpUtils#getRequestURL
  448.      *
  449.      */
  450.     public String getRequestURI();
  451.     
  452.     
  453.     
  454.     /**
  455.      *
  456.      * Returns the part of this request's URL that calls
  457.      * the servlet. This includes either the servlet name or
  458.      * a path to the servlet, but does not include any extra
  459.      * path information or a query string. Same as the value 
  460.      * of the CGI variable SCRIPT_NAME.
  461.      *
  462.      *
  463.      * @return a <code>String</code> containing
  464.      * the name or path of the servlet being
  465.      * called, as specified in the request URL 
  466.      *
  467.      *
  468.      */
  469.     public String getServletPath();
  470.     
  471.     
  472.     
  473.     /**
  474.      *
  475.      * Returns the current <code>HttpSession</code>
  476.      * associated with this request or, if if there is no
  477.      * current session and <code>create</code> is true, returns 
  478.      * a new session.
  479.      *
  480.      * <p>If <code>create</code> is <code>false</code>
  481.      * and the request has no valid <code>HttpSession</code>,
  482.      * this method returns <code>null</code>.
  483.      *
  484.      * <p>To make sure the session is properly maintained,
  485.      * you must call this method before 
  486.      * the response is committed.
  487.      *
  488.      *
  489.      *
  490.      *
  491.      * @param <code>true</code> to create
  492.      * a new session for this request if necessary; 
  493.      * <code>false</code> to return <code>null</code>
  494.      * if there's no current session
  495.      *
  496.      *
  497.      * @return  the <code>HttpSession</code> associated 
  498.      * with this request or <code>null</code> if
  499.      *  <code>create</code> is <code>false</code>
  500.      * and the request has no valid session
  501.      *
  502.      * @see #getSession()
  503.      *
  504.      *
  505.      */
  506.     public HttpSession getSession(boolean create);
  507.     
  508.     
  509.     
  510.    
  511.     /**
  512.      *
  513.      * Returns the current session associated with this request,
  514.      * or if the request does not have a session, creates one.
  515.      * 
  516.      * @return the <code>HttpSession</code> associated
  517.      * with this request
  518.      *
  519.      * @see #getSession(boolean)
  520.      *
  521.      */
  522.     public HttpSession getSession();
  523.     
  524.     
  525.     
  526.     
  527.     
  528.     /**
  529.      *
  530.      * Checks whether the requested session ID is still valid.
  531.      *
  532.      * @return <code>true</code> if this
  533.      * request has an id for a valid session
  534.      * in the current session context;
  535.      * <code>false</code> otherwise
  536.      *
  537.      * @see #getRequestedSessionId
  538.      * @see #getSession
  539.      * @see HttpSessionContext
  540.      *
  541.      */
  542.     public boolean isRequestedSessionIdValid();
  543.     
  544.     
  545.     
  546.     /**
  547.      *
  548.      * Checks whether the requested session ID came in as a cookie.
  549.      *
  550.      * @return <code>true</code> if the session ID
  551.      * came in as a
  552.      * cookie; otherwise, <code>false</code>
  553.      *
  554.      *
  555.      * @see #getSession
  556.      *
  557.      */ 
  558.     public boolean isRequestedSessionIdFromCookie();
  559.     
  560.     
  561.     
  562.     /**
  563.      *
  564.      * Checks whether the requested session ID came in as part of the 
  565.      * request URL.
  566.      *
  567.      * @return <code>true</code> if the session ID
  568.      * came in as part of a URL; otherwise,
  569.      * <code>false</code>
  570.      *
  571.      *
  572.      * @see #getSession
  573.      *
  574.      */
  575.     
  576.     public boolean isRequestedSessionIdFromURL();
  577.     
  578.     
  579.     
  580.     
  581.     
  582.     /**
  583.      *
  584.      * @deprecated As of Version 2.1 of the Java Servlet
  585.      * API, use {@link #isRequestedSessionIdFromURL}
  586.      * instead.
  587.      *
  588.      */
  589.     public boolean isRequestedSessionIdFromUrl();
  590.     
  591. }