httpservletrequest.java

RESIN 3.2 最新源码

/*
 * Copyright (c) 1998-2008 Caucho Technology -- all rights reserved
 *
 * This file is part of Resin(R) Open Source
 *
 * Each copy or derived work must preserve the copyright notice and this
 * notice unmodified.
 *
 * Resin Open Source is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * Resin Open Source is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, or any warranty
 * of NON-INFRINGEMENT.  See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Resin Open Source; if not, write to the
 *
 *   Free Software Foundation, Inc.
 *   59 Temple Place, Suite 330
 *   Boston, MA 02111-1307  USA
 *
 * @author Scott Ferguson
 */


package javax.servlet.http;

import javax.servlet.ServletRequest;
import java.security.Principal;
import java.util.Enumeration;

/**
 * HttpServletRequest encapsulates client request data.
 *
 * <h4>URI</h4>
 *
 * The servlet engine splits the URI into three useful
 * sections: the context path (application prefix), the servlet path,
 * and the path info.
 *
 * <p>For example, given an application prefix of '/myapp', the api
 * <code>/myapp/dir/test.jsp/data</code> will be split as follows:
 *
 * <table>
 * <tr><td>/myapp/dir/test.jsp/data<td>getRequestURI()
 * <tr><td>/myapp<td>getContextPath()
 * <tr><td>/dir/test.jsp<td>getServletPath()
 * <tr><td>/data<td>getPathInfo()
 * </table>
 *
 * <h4>Useful headers</h4>
 *
 * <table>
 * <tr><td>User-Agent<td>String describing the browser's version
 * </table>
 *
 * <h4>CGI equivalents</h4>
 *
 * <table>
 * <tr><td>AUTH_TYPE<td>getAuthType()
 * <tr><td>CONTENT_TYPE<td>getContentType()
 * <tr><td>CONTENT_LENGTH<td>getContentLength()
 * <tr><td>PATH_INFO<td>getPathInfo()
 * <tr><td>PATH_TRANSLATED<td>getPathTranslated()
 * <tr><td>QUERY_STRING<td>getQueryString()
 * <tr><td>REMOTE_ADDR<td>getRemoteAddr()
 * <tr><td>REMOTE_HOST<td>getRemoteHost()
 * <tr><td>REMOTE_USER<td>getRemoteUser()
 * <tr><td>REQUEST_METHOD<td>getMethod()
 * <tr><td>SCRIPT_NAME<td>getServletPath()
 * <tr><td>SERVER_NAME<td>getServerName()
 * <tr><td>SERVER_PROTOCOL<td>getProtocol()
 * <tr><td>SERVER_PORT<td>getServerPort()
 * </table>
 *
 * <h4>Form data</h4>
 *
 * For form data, see <code>ServletRequest.getParameter()</code>
 */

public interface HttpServletRequest extends ServletRequest {
  /**
   * String identifier for basic authentication. Value "BASIC".
   */
  public final static String BASIC_AUTH = "BASIC";
  /**
   * String identifier for client cert authentication. Value "CLIENT_CERT".
   */
  public final static String CLIENT_CERT_AUTH = "CLIENT_CERT";
  /**
   * String identifier for digest authenciation. Value "DIGEST".
   */
  public final static String DIGEST_AUTH = "DIGEST";
  /**
   * String identifier for form authenciation. Value "FORM".
   */
  public final static String FORM_AUTH = "FORM";
  /**
   * Returns the HTTP method, e.g. "GET" or "POST"
   *
   * <p/>Equivalent to CGI's <code>REQUEST_METHOD</code>
   */
  public String getMethod();
  /**
   * Returns the entire request URI
   */
  public String getRequestURI();
  /**
   * Reconstructs the URL the client used for the request.
   *
   * @since Servlet 2.3
   */
  public StringBuffer getRequestURL();
  /**
   * Returns the part of the URI corresponding to the application's
   * prefix.  The first part of the URI selects applications
   * (ServletContexts).
   *
   * <p><code>getContextPath()</code> is /myapp for the uri
   * /myapp/servlet/Hello,
   */
  public String getContextPath();
  /**
   * Returns the URI part corresponding to the selected servlet.
   * The URI is relative to the application.
   *
   * <p/>Corresponds to CGI's <code>SCRIPT_NAME</code>
   *
   * <code>getServletPath()</code> is /servlet/Hello for the uri
   * /myapp/servlet/Hello/foo.
   *
   * <code>getServletPath()</code> is /dir/hello.jsp
   * for the uri /myapp/dir/hello.jsp/foo,
   */
  public String getServletPath();
  /**
   * Returns the URI part after the selected servlet and null if there
   * is no suffix.
   *
   * <p/>Corresponds to CGI's <code>PATH_INFO</code>
   *
   * <p><code>getPathInfo()</code> is /foo for
   * the uri /myapp/servlet/Hello/foo.
   *
   * <code>getPathInfo()</code> is /hello.jsp for for the uri
   * /myapp/dir/hello.jsp/foo.
   */
  public String getPathInfo();
  /**
   * Returns the physical path name for the path info.
   *
   * <p/>Corresponds to CGI's <code>PATH_TRANSLATED</code>
   *
   * @return null if there is no path info.
   */
  public String getPathTranslated();
  /**
   * Returns the request's query string.  Form based servlets will use
   * <code>ServletRequest.getParameter()</code> to decode the form values.
   *
   * <p/>Corresponds to CGI's <code>PATH_TRANSLATED</code>
   */
  public String getQueryString();
  /**
   * Returns the first value for a request header.
   *
   * <p/>Corresponds to CGI's <code>HTTP_*</code>
   *
   * <code><pre>
   * String userAgent = request.getHeader("User-Agent");
   * </pre></code>
   *
   * @param name the header name
   * @return the header value
   */
  public String getHeader(String name);
  /**
   * Returns all the values for a request header.  In some rare cases,
   * like cookies, browsers may return multiple headers.
   *
   * @param name the header name
   * @return an enumeration of the header values.
   */
  public Enumeration getHeaders(String name);
  /**
   * Returns an enumeration of all headers sent by the client.
   */
  public Enumeration getHeaderNames();
  /**
   * Converts a header value to an integer.
   *
   * @param name the header name
   * @return the header value converted to an integer
   */
  public int getIntHeader(String name);
  /**
   * Converts a date header to milliseconds since the epoch.
   *
   * <pre><code>
   * long mod = request.getDateHeader("If-Modified-Since");
   * </code></pre>
   *
   * @param name the header name
   * @return the header value converted to an date
   */
  public long getDateHeader(String name);
  /**
   * Returns an array of all cookies sent by the client.
   */
  public Cookie []getCookies();
  /**
   * Returns a session.  If no session exists and create is true, then
   * create a new session, otherwise return null.
   *
   * @param create If true, then create a new session if none exists.
   */
  public HttpSession getSession(boolean create);
  /**
   * Returns the current session, creating one if necessary.
   * Sessions are a convenience for keeping user state
   * across requests.
   */
  public HttpSession getSession();
  /**
   * Returns the session id.  Sessions are a convenience for keeping
   * user state across requests.
   *
   * <p/>The session id is the value of the JSESSION cookie.
   */
  public String getRequestedSessionId();
  /**
   * Returns true if the session is valid.
   */
  public boolean isRequestedSessionIdValid();
  /**
   * Returns true if the session came from a cookie.
   */
  public boolean isRequestedSessionIdFromCookie();
  /**
   * Returns true if the session came URL-encoding.
   */
  public boolean isRequestedSessionIdFromURL();
  /**
   * Returns the auth type, i.e. BASIC, CLIENT-CERT, DIGEST, or FORM.
   */
  public String getAuthType();
  /**
   * Returns the remote user if authenticated.
   */
  public String getRemoteUser();
  /**
   * Returns true if the user is in the given role.
   */
  public boolean isUserInRole(String role);
  /**
   * Returns the equivalent principal object for the authenticated user.
   */
  public Principal getUserPrincipal();
  /**
   * @deprecated
   */
  public boolean isRequestedSessionIdFromUrl();
}