/* * 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. *

* 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 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 Enumeration 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. *

* Some servlet containers do not allow servlets to access headers using * this method, in which case this method returns null * * @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 Enumeration getHeaderNames(); /** * Returns the value of the specified request header as an int. * 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. *

* The header name is case insensitive. * * @param name * a 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. *

* This method returns null if there was no extra path * information. *

* Same as the value of the CGI variable PATH_INFO. * * @return a 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. *

* If the URL does not have any extra path information, this method returns * 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: * * * * * * * * *
Examples of Returned Values
First line of HTTP requestReturned 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 *
*

* To reconstruct a URL with a scheme and host, use * {@link #getRequestURL}. * * @return a 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. *

* Because this method returns a StringBuffer, not a string, * you can modify the URL easily, for example, to append query parameters. *

* This method is useful for creating redirect messages and for reporting * errors. * * @return a 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. *

* This method will return an empty string ("") if the servlet used to * process this request was matched using the "/*" pattern. * * @return a 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. *

* If create is false and the request has no valid * HttpSession, this method returns null. *

* 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 * 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(); /** * @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 true if the user is successfully authenticated and * false 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 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 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 upgrade( Class httpUpgradeHandlerClass) throws java.io.IOException, ServletException; }