+ * The servlet container creates an HttpServletRequest object and
+ * passes it as an argument to the servlet's service methods
+ * (doGet, doPost, 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 null is
+ * returned.
+ *
+ * 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 null if the request was not authenticated.
+ */
+ public String getAuthType();
+
+ /**
+ * Returns an array containing all of the Cookie objects the
+ * client sent with this request. This method returns null if
+ * no cookies were sent.
+ *
+ * @return an array of all the Cookies included with this
+ * request, or null if the request has no cookies
+ */
+ public Cookie[] getCookies();
+
+ /**
+ * Returns the value of the specified request header as a long
+ * value that represents a Date object. Use this method with
+ * headers that contain dates, such as If-Modified-Since.
+ *
+ * The date is returned as the number of milliseconds since January 1, 1970 + * GMT. The header name is case insensitive. + *
+ * 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 IllegalArgumentException.
+ *
+ * @param name
+ * a String specifying the name of the header
+ * @return a long 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
+ * String. If the request did not include a header of the
+ * specified name, this method returns null. 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 String specifying the header name
+ * @return a String containing the value of the requested
+ * header, or null 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
+ * Enumeration of String objects.
+ *
+ * Some headers, such as Accept-Language can be sent by clients
+ * as several headers each with a different value rather than sending the
+ * header as a comma separated list.
+ *
+ * If the request did not include any headers of the specified name, this
+ * method returns an empty
+ * Some servlet containers do not allow servlets to access headers using
+ * this method, in which case this method returns
+ * The header name is case insensitive.
+ *
+ * @param name
+ * a
+ * This method returns
+ * Same as the value of the CGI variable PATH_INFO.
+ *
+ * @return a
+ * If the URL does not have any extra path information, this method returns
+ *
+ * To reconstruct an URL with a scheme and host, use
+ * {@link #getRequestURL}.
+ *
+ * @return a
+ * Because this method returns a
+ * This method is useful for creating redirect messages and for reporting
+ * errors.
+ *
+ * @return a
+ * This method will return an empty string ("") if the servlet used to
+ * process this request was matched using the "/*" pattern.
+ *
+ * @return a
+ * If
+ * 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
+ * Enumeration. The header name is case
+ * insensitive. You can use this method with any request header.
+ *
+ * @param name
+ * a String specifying the header name
+ * @return an Enumeration 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 Enumerationnull
+ *
+ * @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,
+ * null
+ */
+ public Enumerationint.
+ * 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 NumberFormatException.
+ * String 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
+ * int
+ */
+ 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 String 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.
+ * null if there was no extra path
+ * information.
+ * String, 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 null
+ * 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.
+ * null 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 String specifying the real path, or
+ * null 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 String 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 null if the URL does not have a
+ * query string. Same as the value of the CGI variable QUERY_STRING.
+ *
+ * @return a String containing the query string or
+ * null 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 null 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 String specifying the login of the user making
+ * this request, or null 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 false.
+ *
+ * @param role
+ * a String specifying the name of the role
+ * @return a boolean indicating whether the user making this
+ * request belongs to a given role; false if the user
+ * has not been authenticated
+ */
+ public boolean isUserInRole(String role);
+
+ /**
+ * Returns a java.security.Principal object containing the name
+ * of the current authenticated user. If the user has not been
+ * authenticated, the method returns null.
+ *
+ * @return a java.security.Principal containing the name of the
+ * user making this request; null 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 null.
+ *
+ * @return a String specifying the session ID, or
+ * null 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:
+ *
+ *
+ *
+ * First line of HTTP request
+ * Returned Value
+ *
+ * POST /some/path.html HTTP/1.1
+ *
+ * /some/path.html
+ *
+ * GET http://foo.bar/a.html HTTP/1.0
+ *
+ * /a.html
+ *
+ * HEAD /xyz?a=b HTTP/1.1
+ *
+ * /xyz
+ * String 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.
+ * StringBuffer, not a string,
+ * you can modify the URL easily, for example, to append query parameters.
+ * StringBuffer 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.
+ * String 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 HttpSession associated with this request
+ * or, if there is no current session and create is true,
+ * returns a new session.
+ * create is false and the request has no valid
+ * HttpSession, this method returns null.
+ * true to create a new session for this request if
+ * necessary; false to return null if
+ * there's no current session
+ * @return the HttpSession associated with this request or
+ * null if create is false
+ * 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 HttpSession 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 true if this request has an id for a valid session
+ * in the current session context; false otherwise
+ * @see #getRequestedSessionId
+ * @see #getSession
+ */
+ public boolean isRequestedSessionIdValid();
+
+ /**
+ * Checks whether the requested session ID came in as a cookie.
+ *
+ * @return true if the session ID came in as a cookie;
+ * otherwise, false
+ * @see #getSession
+ */
+ public boolean isRequestedSessionIdFromCookie();
+
+ /**
+ * Checks whether the requested session ID came in as part of the request
+ * URL.
+ *
+ * @return true if the session ID came in as part of a URL;
+ * otherwise, false
+ * @see #getSession
+ */
+ public boolean 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 true if the user is successfully authenticated and
+ * false if not
+ *
+ * @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