java/javax/servlet/http/HttpServletRequest.java - tomcat80 - Git at Google

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package javax.servlet.http;

 import java.io.IOException;
 import java.util.Collection;
 import java.util.Enumeration;

 import javax.servlet.ServletException;
 import javax.servlet.ServletRequest;

 /**
  * Extends the {@link javax.servlet.ServletRequest} interface to provide request
  * information for HTTP servlets.
  * <p>
  * The servlet container creates an <code>HttpServletRequest</code> object and
  * passes it as an argument to the servlet's service methods
  * (<code>doGet</code>, <code>doPost</code>, etc).
  */
 public interface HttpServletRequest extends ServletRequest {

     /**
      * String identifier for Basic authentication. Value "BASIC"
      */
     public static final String BASIC_AUTH = "BASIC";
     /**
      * String identifier for Form authentication. Value "FORM"
      */
     public static final String FORM_AUTH = "FORM";
     /**
      * String identifier for Client Certificate authentication. Value
      * "CLIENT_CERT"
      */
     public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
     /**
      * String identifier for Digest authentication. Value "DIGEST"
      */
     public static final String DIGEST_AUTH = "DIGEST";

     /**
      * Returns the name of the authentication scheme used to protect the
      * servlet. All servlet containers support basic, form and client
      * certificate authentication, and may additionally support digest
      * authentication. If the servlet is not authenticated <code>null</code> is
      * returned.
      * <p>
      * Same as the value of the CGI variable AUTH_TYPE.
      *
      * @return one of the static members BASIC_AUTH, FORM_AUTH, CLIENT_CERT_AUTH,
      *         DIGEST_AUTH (suitable for == comparison) or the
      *         container-specific string indicating the authentication scheme,
      *         or <code>null</code> if the request was not authenticated.
      */
     public String getAuthType();

     /**
      * Returns an array containing all of the <code>Cookie</code> objects the
      * client sent with this request. This method returns <code>null</code> if
      * no cookies were sent.
      *
      * @return an array of all the <code>Cookies</code> included with this
      *         request, or <code>null</code> if the request has no cookies
      */
     public Cookie[] getCookies();

     /**
      * Returns the value of the specified request header as a <code>long</code>
      * value that represents a <code>Date</code> object. Use this method with
      * headers that contain dates, such as <code>If-Modified-Since</code>.
      * <p>
      * The date is returned as the number of milliseconds since January 1, 1970
      * GMT. The header name is case insensitive.
      * <p>
      * If the request did not have a header of the specified name, this method
      * returns -1. If the header can't be converted to a date, the method throws
      * an <code>IllegalArgumentException</code>.
      *
      * @param name
      *            a <code>String</code> specifying the name of the header
      * @return a <code>long</code> value representing the date specified in the
      *         header expressed as the number of milliseconds since January 1,
      *         1970 GMT, or -1 if the named header was not included with the
      *         request
      * @exception IllegalArgumentException
      *                If the header value can't be converted to a date
      */
     public long getDateHeader(String name);

     /**
      * Returns the value of the specified request header as a
      * <code>String</code>. If the request did not include a header of the
      * specified name, this method returns <code>null</code>. If there are
      * multiple headers with the same name, this method returns the first head
      * in the request. The header name is case insensitive. You can use this
      * method with any request header.
      *
      * @param name
      *            a <code>String</code> specifying the header name
      * @return a <code>String</code> containing the value of the requested
      *         header, or <code>null</code> if the request does not have a
      *         header of that name
      */
     public String getHeader(String name);

     /**
      * Returns all the values of the specified request header as an
      * <code>Enumeration</code> of <code>String</code> objects.
      * <p>
      * Some headers, such as <code>Accept-Language</code> can be sent by clients
      * as several headers each with a different value rather than sending the
      * header as a comma separated list.
      * <p>
      * If the request did not include any headers of the specified name, this
      * method returns an empty <code>Enumeration</code>. The header name is case
      * insensitive. You can use this method with any request header.
      *
      * @param name
      *            a <code>String</code> specifying the header name
      * @return an <code>Enumeration</code> containing the values of the requested
      *         header. If the request does not have any headers of that name
      *         return an empty enumeration. If the container does not allow
      *         access to header information, return null
      */
     public Enumeration<String> getHeaders(String name);

     /**
      * Returns an enumeration of all the header names this request contains. If
      * the request has no headers, this method returns an empty enumeration.
      * <p>
      * Some servlet containers do not allow servlets to access headers using
      * this method, in which case this method returns <code>null</code>
      *
      * @return an enumeration of all the header names sent with this request; if
      *         the request has no headers, an empty enumeration; if the servlet
      *         container does not allow servlets to use this method,
      *         <code>null</code>
      */
     public Enumeration<String> getHeaderNames();

     /**
      * Returns the value of the specified request header as an <code>int</code>.
      * If the request does not have a header of the specified name, this method
      * returns -1. If the header cannot be converted to an integer, this method
      * throws a <code>NumberFormatException</code>.
      * <p>
      * The header name is case insensitive.
      *
      * @param name
      *            a <code>String</code> specifying the name of a request header
      * @return an integer expressing the value of the request header or -1 if the
      *         request doesn't have a header of this name
      * @exception NumberFormatException
      *                If the header value can't be converted to an
      *                <code>int</code>
      */
     public int getIntHeader(String name);

     /**
      * Returns the name of the HTTP method with which this request was made, for
      * example, GET, POST, or PUT. Same as the value of the CGI variable
      * REQUEST_METHOD.
      *
      * @return a <code>String</code> specifying the name of the method with
      *         which this request was made
      */
     public String getMethod();

     /**
      * Returns any extra path information associated with the URL the client
      * sent when it made this request. The extra path information follows the
      * servlet path but precedes the query string and will start with a "/"
      * character.
      * <p>
      * This method returns <code>null</code> if there was no extra path
      * information.
      * <p>
      * Same as the value of the CGI variable PATH_INFO.
      *
      * @return a <code>String</code>, decoded by the web container, specifying
      *         extra path information that comes after the servlet path but
      *         before the query string in the request URL; or <code>null</code>
      *         if the URL does not have any extra path information
      */
     public String getPathInfo();

     /**
      * Returns any extra path information after the servlet name but before the
      * query string, and translates it to a real path. Same as the value of the
      * CGI variable PATH_TRANSLATED.
      * <p>
      * If the URL does not have any extra path information, this method returns
      * <code>null</code> or the servlet container cannot translate the virtual
      * path to a real path for any reason (such as when the web application is
      * executed from an archive). The web container does not decode this string.
      *
      * @return a <code>String</code> specifying the real path, or
      *         <code>null</code> if the URL does not have any extra path
      *         information
      */
     public String getPathTranslated();

     /**
      * Returns the portion of the request URI that indicates the context of the
      * request. The context path always comes first in a request URI. The path
      * starts with a "/" character but does not end with a "/" character. For
      * servlets in the default (root) context, this method returns "". The
      * container does not decode this string.
      *
      * @return a <code>String</code> specifying the portion of the request URI
      *         that indicates the context of the request
      */
     public String getContextPath();

     /**
      * Returns the query string that is contained in the request URL after the
      * path. This method returns <code>null</code> if the URL does not have a
      * query string. Same as the value of the CGI variable QUERY_STRING.
      *
      * @return a <code>String</code> containing the query string or
      *         <code>null</code> if the URL contains no query string. The value
      *         is not decoded by the container.
      */
     public String getQueryString();

     /**
      * Returns the login of the user making this request, if the user has been
      * authenticated, or <code>null</code> if the user has not been
      * authenticated. Whether the user name is sent with each subsequent request
      * depends on the browser and type of authentication. Same as the value of
      * the CGI variable REMOTE_USER.
      *
      * @return a <code>String</code> specifying the login of the user making
      *         this request, or <code>null</code> if the user login is not known
      */
     public String getRemoteUser();

     /**
      * Returns a boolean indicating whether the authenticated user is included
      * in the specified logical "role". Roles and role membership can be defined
      * using deployment descriptors. If the user has not been authenticated, the
      * method returns <code>false</code>.
      *
      * @param role
      *            a <code>String</code> specifying the name of the role
      * @return a <code>boolean</code> indicating whether the user making this
      *         request belongs to a given role; <code>false</code> if the user
      *         has not been authenticated
      */
     public boolean isUserInRole(String role);

     /**
      * Returns a <code>java.security.Principal</code> object containing the name
      * of the current authenticated user. If the user has not been
      * authenticated, the method returns <code>null</code>.
      *
      * @return a <code>java.security.Principal</code> containing the name of the
      *         user making this request; <code>null</code> if the user has not
      *         been authenticated
      */
     public java.security.Principal getUserPrincipal();

     /**
      * Returns the session ID specified by the client. This may not be the same
      * as the ID of the current valid session for this request. If the client
      * did not specify a session ID, this method returns <code>null</code>.
      *
      * @return a <code>String</code> specifying the session ID, or
      *         <code>null</code> if the request did not specify a session ID
      * @see #isRequestedSessionIdValid
      */
     public String getRequestedSessionId();

     /**
      * Returns the part of this request's URL from the protocol name up to the
      * query string in the first line of the HTTP request. The web container
      * does not decode this String. For example:
      * <table summary="Examples of Returned Values">
      * <tr align=left>
      * <th>First line of HTTP request</th>
      * <th>Returned Value</th>
      * <tr>
      * <td>POST /some/path.html HTTP/1.1
      * <td>
      * <td>/some/path.html
      * <tr>
      * <td>GET http://foo.bar/a.html HTTP/1.0
      * <td>
      * <td>/a.html
      * <tr>
      * <td>HEAD /xyz?a=b HTTP/1.1
      * <td>
      * <td>/xyz
      * </table>
      * <p>
      * To reconstruct an URL with a scheme and host, use
      * {@link #getRequestURL}.
      *
      * @return a <code>String</code> containing the part of the URL from the
      *         protocol name up to the query string
      * @see #getRequestURL
      */
     public String getRequestURI();

     /**
      * Reconstructs the URL the client used to make the request. The returned
      * URL contains a protocol, server name, port number, and server path, but
      * it does not include query string parameters.
      * <p>
      * Because this method returns a <code>StringBuffer</code>, not a string,
      * you can modify the URL easily, for example, to append query parameters.
      * <p>
      * This method is useful for creating redirect messages and for reporting
      * errors.
      *
      * @return a <code>StringBuffer</code> object containing the reconstructed
      *         URL
      */
     public StringBuffer getRequestURL();

     /**
      * Returns the part of this request's URL that calls the servlet. This path
      * starts with a "/" character and includes either the servlet name or a
      * path to the servlet, but does not include any extra path information or a
      * query string. Same as the value of the CGI variable SCRIPT_NAME.
      * <p>
      * This method will return an empty string ("") if the servlet used to
      * process this request was matched using the "/*" pattern.
      *
      * @return a <code>String</code> containing the name or path of the servlet
      *         being called, as specified in the request URL, decoded, or an
      *         empty string if the servlet used to process the request is
      *         matched using the "/*" pattern.
      */
     public String getServletPath();

     /**
      * Returns the current <code>HttpSession</code> associated with this request
      * or, if there is no current session and <code>create</code> is true,
      * returns a new session.
      * <p>
      * If <code>create</code> is <code>false</code> and the request has no valid
      * <code>HttpSession</code>, this method returns <code>null</code>.
      * <p>
      * To make sure the session is properly maintained, you must call this
      * method before the response is committed. If the container is using
      * cookies to maintain session integrity and is asked to create a new
      * session when the response is committed, an IllegalStateException is
      * thrown.
      *
      * @param create
      *            <code>true</code> to create a new session for this request if
      *            necessary; <code>false</code> to return <code>null</code> if
      *            there's no current session
      * @return the <code>HttpSession</code> associated with this request or
      *         <code>null</code> if <code>create</code> is <code>false</code>
      *         and the request has no valid session
      * @see #getSession()
      */
     public HttpSession getSession(boolean create);

     /**
      * Returns the current session associated with this request, or if the
      * request does not have a session, creates one.
      *
      * @return the <code>HttpSession</code> associated with this request
      * @see #getSession(boolean)
      */
     public HttpSession getSession();

     /**
      * Changes the session ID of the session associated with this request. This
      * method does not create a new session object it only changes the ID of the
      * current session.
      *
      * @return the new session ID allocated to the session
      * @see HttpSessionIdListener
      * @since Servlet 3.1
      */
     public String changeSessionId();

     /**
      * Checks whether the requested session ID is still valid.
      *
      * @return <code>true</code> if this request has an id for a valid session
      *         in the current session context; <code>false</code> otherwise
      * @see #getRequestedSessionId
      * @see #getSession
      */
     public boolean isRequestedSessionIdValid();

     /**
      * Checks whether the requested session ID came in as a cookie.
      *
      * @return <code>true</code> if the session ID came in as a cookie;
      *         otherwise, <code>false</code>
      * @see #getSession
      */
     public boolean isRequestedSessionIdFromCookie();

     /**
      * Checks whether the requested session ID came in as part of the request
      * URL.
      *
      * @return <code>true</code> if the session ID came in as part of a URL;
      *         otherwise, <code>false</code>
      * @see #getSession
      */
     public boolean isRequestedSessionIdFromURL();

     /**
      * @return {@link #isRequestedSessionIdFromURL()}
      * @deprecated As of Version 2.1 of the Java Servlet API, use
      *             {@link #isRequestedSessionIdFromURL} instead.
      */
     @SuppressWarnings("dep-ann")
     // Spec API does not use @Deprecated
     public boolean isRequestedSessionIdFromUrl();

     /**
      * Triggers the same authentication process as would be triggered if the
      * request is for a resource that is protected by a security constraint.
      *
      * @param response  The response to use to return any authentication
      *                  challenge
      * @return <code>true</code> if the user is successfully authenticated and
      *         <code>false</code> if not
      *
      * @throws IOException if the authentication process attempted to read from
      *         the request or write to the response and an I/O error occurred
      * @throws IllegalStateException if the authentication process attempted to
      *         write to the response after it had been committed
      * @throws ServletException if the authentication failed and the caller is
      *         expected to handle the failure
      * @since Servlet 3.0
      */
     public boolean authenticate(HttpServletResponse response)
             throws IOException, ServletException;

     /**
      * Authenticate the provided user name and password and then associated the
      * authenticated user with the request.
      *
      * @param username  The user name to authenticate
      * @param password  The password to use to authenticate the user
      *
      * @throws ServletException
      *             If any of {@link #getRemoteUser()},
      *             {@link #getUserPrincipal()} or {@link #getAuthType()} are
      *             non-null, if the configured authenticator does not support
      *             user name and password authentication or if the
      *             authentication fails
      * @since Servlet 3.0
      */
     public void login(String username, String password) throws ServletException;

     /**
      * Removes any authenticated user from the request.
      *
      * @throws ServletException
      *             If the logout fails
      * @since Servlet 3.0
      */
     public void logout() throws ServletException;

     /**
      * Return a collection of all uploaded Parts.
      *
      * @return A collection of all uploaded Parts.
      * @throws IOException
      *             if an I/O error occurs
      * @throws IllegalStateException
      *             if size limits are exceeded or no multipart configuration is
      *             provided
      * @throws ServletException
      *             if the request is not multipart/form-data
      * @since Servlet 3.0
      */
     public Collection<Part> getParts() throws IOException,
             ServletException;

     /**
      * Gets the named Part or null if the Part does not exist. Triggers upload
      * of all Parts.
      *
      * @param name The name of the Part to obtain
      *
      * @return The named Part or null if the Part does not exist
      * @throws IOException
      *             if an I/O error occurs
      * @throws IllegalStateException
      *             if size limits are exceeded
      * @throws ServletException
      *             if the request is not multipart/form-data
      * @since Servlet 3.0
      */
     public Part getPart(String name) throws IOException,
             ServletException;

     /**
      * Start the HTTP upgrade process and pass the connection to the provided
      * protocol handler once the current request/response pair has completed
      * processing. Calling this method sets the response status to {@link
      * HttpServletResponse#SC_SWITCHING_PROTOCOLS} and flushes the response.
      * Protocol specific headers must have already been set before this method
      * is called.
      *
      * @param <T>                     The type of the upgrade handler
      * @param httpUpgradeHandlerClass The class that implements the upgrade
      *                                handler
      *
      * @return A newly created instance of the specified upgrade handler type
      *
      * @throws IOException
      *             if an I/O error occurred during the upgrade
      * @throws ServletException
      *             if the given httpUpgradeHandlerClass fails to be instantiated
      * @since Servlet 3.1
      */
     public <T extends HttpUpgradeHandler> T upgrade(
             Class<T> httpUpgradeHandlerClass) throws java.io.IOException, ServletException;
 }
	/*
	* Licensed to the Apache Software Foundation (ASF) under one or more
	* contributor license agreements. See the NOTICE file distributed with
	* this work for additional information regarding copyright ownership.
	* The ASF licenses this file to You under the Apache License, Version 2.0
	* (the "License"); you may not use this file except in compliance with
	* the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package javax.servlet.http;

	import java.io.IOException;
	import java.util.Collection;
	import java.util.Enumeration;

	import javax.servlet.ServletException;
	import javax.servlet.ServletRequest;

	/**
	* Extends the {@link javax.servlet.ServletRequest} interface to provide request
	* information for HTTP servlets.
	* <p>
	* The servlet container creates an <code>HttpServletRequest</code> object and
	* passes it as an argument to the servlet's service methods
	* (<code>doGet</code>, <code>doPost</code>, etc).
	*/
	public interface HttpServletRequest extends ServletRequest {

	/**
	* String identifier for Basic authentication. Value "BASIC"
	*/
	public static final String BASIC_AUTH = "BASIC";
	/**
	* String identifier for Form authentication. Value "FORM"
	*/
	public static final String FORM_AUTH = "FORM";
	/**
	* String identifier for Client Certificate authentication. Value
	* "CLIENT_CERT"
	*/
	public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
	/**
	* String identifier for Digest authentication. Value "DIGEST"
	*/
	public static final String DIGEST_AUTH = "DIGEST";

	/**
	* Returns the name of the authentication scheme used to protect the
	* servlet. All servlet containers support basic, form and client
	* certificate authentication, and may additionally support digest
	* authentication. If the servlet is not authenticated <code>null</code> is
	* returned.
	* <p>
	* Same as the value of the CGI variable AUTH_TYPE.
	*
	* @return one of the static members BASIC_AUTH, FORM_AUTH, CLIENT_CERT_AUTH,
	* DIGEST_AUTH (suitable for == comparison) or the
	* container-specific string indicating the authentication scheme,
	* or <code>null</code> if the request was not authenticated.
	*/
	public String getAuthType();

	/**
	* Returns an array containing all of the <code>Cookie</code> objects the
	* client sent with this request. This method returns <code>null</code> if
	* no cookies were sent.
	*
	* @return an array of all the <code>Cookies</code> included with this
	* request, or <code>null</code> if the request has no cookies
	*/
	public Cookie[] getCookies();

	/**
	* Returns the value of the specified request header as a <code>long</code>
	* value that represents a <code>Date</code> object. Use this method with
	* headers that contain dates, such as <code>If-Modified-Since</code>.
	* <p>
	* The date is returned as the number of milliseconds since January 1, 1970
	* GMT. The header name is case insensitive.
	* <p>
	* If the request did not have a header of the specified name, this method
	* returns -1. If the header can't be converted to a date, the method throws
	* an <code>IllegalArgumentException</code>.
	*
	* @param name
	* a <code>String</code> specifying the name of the header
	* @return a <code>long</code> value representing the date specified in the
	* header expressed as the number of milliseconds since January 1,
	* 1970 GMT, or -1 if the named header was not included with the
	* request
	* @exception IllegalArgumentException
	* If the header value can't be converted to a date
	*/
	public long getDateHeader(String name);

	/**
	* Returns the value of the specified request header as a
	* <code>String</code>. If the request did not include a header of the
	* specified name, this method returns <code>null</code>. If there are
	* multiple headers with the same name, this method returns the first head
	* in the request. The header name is case insensitive. You can use this
	* method with any request header.
	*
	* @param name
	* a <code>String</code> specifying the header name
	* @return a <code>String</code> containing the value of the requested
	* header, or <code>null</code> if the request does not have a
	* header of that name
	*/
	public String getHeader(String name);

	/**
	* Returns all the values of the specified request header as an
	* <code>Enumeration</code> of <code>String</code> objects.
	* <p>
	* Some headers, such as <code>Accept-Language</code> can be sent by clients
	* as several headers each with a different value rather than sending the
	* header as a comma separated list.
	* <p>
	* If the request did not include any headers of the specified name, this
	* method returns an empty <code>Enumeration</code>. The header name is case
	* insensitive. You can use this method with any request header.
	*
	* @param name
	* a <code>String</code> specifying the header name
	* @return an <code>Enumeration</code> containing the values of the requested
	* header. If the request does not have any headers of that name
	* return an empty enumeration. If the container does not allow
	* access to header information, return null
	*/
	public Enumeration<String> getHeaders(String name);

	/**
	* Returns an enumeration of all the header names this request contains. If
	* the request has no headers, this method returns an empty enumeration.
	* <p>
	* Some servlet containers do not allow servlets to access headers using
	* this method, in which case this method returns <code>null</code>
	*
	* @return an enumeration of all the header names sent with this request; if
	* the request has no headers, an empty enumeration; if the servlet
	* container does not allow servlets to use this method,
	* <code>null</code>
	*/
	public Enumeration<String> getHeaderNames();

	/**
	* Returns the value of the specified request header as an <code>int</code>.
	* If the request does not have a header of the specified name, this method
	* returns -1. If the header cannot be converted to an integer, this method
	* throws a <code>NumberFormatException</code>.
	* <p>
	* The header name is case insensitive.
	*
	* @param name
	* a <code>String</code> specifying the name of a request header
	* @return an integer expressing the value of the request header or -1 if the
	* request doesn't have a header of this name
	* @exception NumberFormatException
	* If the header value can't be converted to an
	* <code>int</code>
	*/
	public int getIntHeader(String name);

	/**
	* Returns the name of the HTTP method with which this request was made, for
	* example, GET, POST, or PUT. Same as the value of the CGI variable
	* REQUEST_METHOD.
	*
	* @return a <code>String</code> specifying the name of the method with
	* which this request was made
	*/
	public String getMethod();

	/**
	* Returns any extra path information associated with the URL the client
	* sent when it made this request. The extra path information follows the
	* servlet path but precedes the query string and will start with a "/"
	* character.
	* <p>
	* This method returns <code>null</code> if there was no extra path
	* information.
	* <p>
	* Same as the value of the CGI variable PATH_INFO.
	*
	* @return a <code>String</code>, decoded by the web container, specifying
	* extra path information that comes after the servlet path but
	* before the query string in the request URL; or <code>null</code>
	* if the URL does not have any extra path information
	*/
	public String getPathInfo();

	/**
	* Returns any extra path information after the servlet name but before the
	* query string, and translates it to a real path. Same as the value of the
	* CGI variable PATH_TRANSLATED.
	* <p>
	* If the URL does not have any extra path information, this method returns
	* <code>null</code> or the servlet container cannot translate the virtual
	* path to a real path for any reason (such as when the web application is
	* executed from an archive). The web container does not decode this string.
	*
	* @return a <code>String</code> specifying the real path, or
	* <code>null</code> if the URL does not have any extra path
	* information
	*/
	public String getPathTranslated();

	/**
	* Returns the portion of the request URI that indicates the context of the
	* request. The context path always comes first in a request URI. The path
	* starts with a "/" character but does not end with a "/" character. For
	* servlets in the default (root) context, this method returns "". The
	* container does not decode this string.
	*
	* @return a <code>String</code> specifying the portion of the request URI
	* that indicates the context of the request
	*/
	public String getContextPath();

	/**
	* Returns the query string that is contained in the request URL after the
	* path. This method returns <code>null</code> if the URL does not have a
	* query string. Same as the value of the CGI variable QUERY_STRING.
	*
	* @return a <code>String</code> containing the query string or
	* <code>null</code> if the URL contains no query string. The value
	* is not decoded by the container.
	*/
	public String getQueryString();

	/**
	* Returns the login of the user making this request, if the user has been
	* authenticated, or <code>null</code> if the user has not been
	* authenticated. Whether the user name is sent with each subsequent request
	* depends on the browser and type of authentication. Same as the value of
	* the CGI variable REMOTE_USER.
	*
	* @return a <code>String</code> specifying the login of the user making
	* this request, or <code>null</code> if the user login is not known
	*/
	public String getRemoteUser();

	/**
	* Returns a boolean indicating whether the authenticated user is included
	* in the specified logical "role". Roles and role membership can be defined
	* using deployment descriptors. If the user has not been authenticated, the
	* method returns <code>false</code>.
	*
	* @param role
	* a <code>String</code> specifying the name of the role
	* @return a <code>boolean</code> indicating whether the user making this
	* request belongs to a given role; <code>false</code> if the user
	* has not been authenticated
	*/
	public boolean isUserInRole(String role);

	/**
	* Returns a <code>java.security.Principal</code> object containing the name
	* of the current authenticated user. If the user has not been
	* authenticated, the method returns <code>null</code>.
	*
	* @return a <code>java.security.Principal</code> containing the name of the
	* user making this request; <code>null</code> if the user has not
	* been authenticated
	*/
	public java.security.Principal getUserPrincipal();

	/**
	* Returns the session ID specified by the client. This may not be the same
	* as the ID of the current valid session for this request. If the client
	* did not specify a session ID, this method returns <code>null</code>.
	*
	* @return a <code>String</code> specifying the session ID, or
	* <code>null</code> if the request did not specify a session ID
	* @see #isRequestedSessionIdValid
	*/
	public String getRequestedSessionId();

	/**
	* Returns the part of this request's URL from the protocol name up to the
	* query string in the first line of the HTTP request. The web container
	* does not decode this String. For example:
	* <table summary="Examples of Returned Values">
	* <tr align=left>
	* <th>First line of HTTP request</th>
	* <th>Returned Value</th>
	* <tr>
	* <td>POST /some/path.html HTTP/1.1
	* <td>
	* <td>/some/path.html
	* <tr>
	* <td>GET http://foo.bar/a.html HTTP/1.0
	* <td>
	* <td>/a.html
	* <tr>
	* <td>HEAD /xyz?a=b HTTP/1.1
	* <td>
	* <td>/xyz
	* </table>
	* <p>
	* To reconstruct an URL with a scheme and host, use
	* {@link #getRequestURL}.
	*
	* @return a <code>String</code> containing the part of the URL from the
	* protocol name up to the query string
	* @see #getRequestURL
	*/
	public String getRequestURI();

	/**
	* Reconstructs the URL the client used to make the request. The returned
	* URL contains a protocol, server name, port number, and server path, but
	* it does not include query string parameters.
	* <p>
	* Because this method returns a <code>StringBuffer</code>, not a string,
	* you can modify the URL easily, for example, to append query parameters.
	* <p>
	* This method is useful for creating redirect messages and for reporting
	* errors.
	*
	* @return a <code>StringBuffer</code> object containing the reconstructed
	* URL
	*/
	public StringBuffer getRequestURL();

	/**
	* Returns the part of this request's URL that calls the servlet. This path
	* starts with a "/" character and includes either the servlet name or a
	* path to the servlet, but does not include any extra path information or a
	* query string. Same as the value of the CGI variable SCRIPT_NAME.
	* <p>
	* This method will return an empty string ("") if the servlet used to
	* process this request was matched using the "/*" pattern.
	*
	* @return a <code>String</code> containing the name or path of the servlet
	* being called, as specified in the request URL, decoded, or an
	* empty string if the servlet used to process the request is
	* matched using the "/*" pattern.
	*/
	public String getServletPath();

	/**
	* Returns the current <code>HttpSession</code> associated with this request
	* or, if there is no current session and <code>create</code> is true,
	* returns a new session.
	* <p>
	* If <code>create</code> is <code>false</code> and the request has no valid
	* <code>HttpSession</code>, this method returns <code>null</code>.
	* <p>
	* To make sure the session is properly maintained, you must call this
	* method before the response is committed. If the container is using
	* cookies to maintain session integrity and is asked to create a new
	* session when the response is committed, an IllegalStateException is
	* thrown.
	*
	* @param create
	* <code>true</code> to create a new session for this request if
	* necessary; <code>false</code> to return <code>null</code> if
	* there's no current session
	* @return the <code>HttpSession</code> associated with this request or
	* <code>null</code> if <code>create</code> is <code>false</code>
	* and the request has no valid session
	* @see #getSession()
	*/
	public HttpSession getSession(boolean create);

	/**
	* Returns the current session associated with this request, or if the
	* request does not have a session, creates one.
	*
	* @return the <code>HttpSession</code> associated with this request
	* @see #getSession(boolean)
	*/
	public HttpSession getSession();

	/**
	* Changes the session ID of the session associated with this request. This
	* method does not create a new session object it only changes the ID of the
	* current session.
	*
	* @return the new session ID allocated to the session
	* @see HttpSessionIdListener
	* @since Servlet 3.1
	*/
	public String changeSessionId();

	/**
	* Checks whether the requested session ID is still valid.
	*
	* @return <code>true</code> if this request has an id for a valid session
	* in the current session context; <code>false</code> otherwise
	* @see #getRequestedSessionId
	* @see #getSession
	*/
	public boolean isRequestedSessionIdValid();

	/**
	* Checks whether the requested session ID came in as a cookie.
	*
	* @return <code>true</code> if the session ID came in as a cookie;
	* otherwise, <code>false</code>
	* @see #getSession
	*/
	public boolean isRequestedSessionIdFromCookie();

	/**
	* Checks whether the requested session ID came in as part of the request
	* URL.
	*
	* @return <code>true</code> if the session ID came in as part of a URL;
	* otherwise, <code>false</code>
	* @see #getSession
	*/
	public boolean isRequestedSessionIdFromURL();

	/**
	* @return {@link #isRequestedSessionIdFromURL()}
	* @deprecated As of Version 2.1 of the Java Servlet API, use
	* {@link #isRequestedSessionIdFromURL} instead.
	*/
	@SuppressWarnings("dep-ann")
	// Spec API does not use @Deprecated
	public boolean isRequestedSessionIdFromUrl();

	/**
	* Triggers the same authentication process as would be triggered if the
	* request is for a resource that is protected by a security constraint.
	*
	* @param response The response to use to return any authentication
	* challenge
	* @return <code>true</code> if the user is successfully authenticated and
	* <code>false</code> if not
	*
	* @throws IOException if the authentication process attempted to read from
	* the request or write to the response and an I/O error occurred
	* @throws IllegalStateException if the authentication process attempted to
	* write to the response after it had been committed
	* @throws ServletException if the authentication failed and the caller is
	* expected to handle the failure
	* @since Servlet 3.0
	*/
	public boolean authenticate(HttpServletResponse response)
	throws IOException, ServletException;

	/**
	* Authenticate the provided user name and password and then associated the
	* authenticated user with the request.
	*
	* @param username The user name to authenticate
	* @param password The password to use to authenticate the user
	*
	* @throws ServletException
	* If any of {@link #getRemoteUser()},
	* {@link #getUserPrincipal()} or {@link #getAuthType()} are
	* non-null, if the configured authenticator does not support
	* user name and password authentication or if the
	* authentication fails
	* @since Servlet 3.0
	*/
	public void login(String username, String password) throws ServletException;

	/**
	* Removes any authenticated user from the request.
	*
	* @throws ServletException
	* If the logout fails
	* @since Servlet 3.0
	*/
	public void logout() throws ServletException;

	/**
	* Return a collection of all uploaded Parts.
	*
	* @return A collection of all uploaded Parts.
	* @throws IOException
	* if an I/O error occurs
	* @throws IllegalStateException
	* if size limits are exceeded or no multipart configuration is
	* provided
	* @throws ServletException
	* if the request is not multipart/form-data
	* @since Servlet 3.0
	*/
	public Collection<Part> getParts() throws IOException,
	ServletException;

	/**
	* Gets the named Part or null if the Part does not exist. Triggers upload
	* of all Parts.
	*
	* @param name The name of the Part to obtain
	*
	* @return The named Part or null if the Part does not exist
	* @throws IOException
	* if an I/O error occurs
	* @throws IllegalStateException
	* if size limits are exceeded
	* @throws ServletException
	* if the request is not multipart/form-data
	* @since Servlet 3.0
	*/
	public Part getPart(String name) throws IOException,
	ServletException;

	/**
	* Start the HTTP upgrade process and pass the connection to the provided
	* protocol handler once the current request/response pair has completed
	* processing. Calling this method sets the response status to {@link
	* HttpServletResponse#SC_SWITCHING_PROTOCOLS} and flushes the response.
	* Protocol specific headers must have already been set before this method
	* is called.
	*
	* @param <T> The type of the upgrade handler
	* @param httpUpgradeHandlerClass The class that implements the upgrade
	* handler
	*
	* @return A newly created instance of the specified upgrade handler type
	*
	* @throws IOException
	* if an I/O error occurred during the upgrade
	* @throws ServletException
	* if the given httpUpgradeHandlerClass fails to be instantiated
	* @since Servlet 3.1
	*/
	public <T extends HttpUpgradeHandler> T upgrade(
	Class<T> httpUpgradeHandlerClass) throws java.io.IOException, ServletException;
	}