All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.servlet.http.HttpServletRequest Maven / Gradle / Ivy

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License.  You can
 * obtain a copy of the License at
 * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
 * or packager/legal/LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 *
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at packager/legal/LICENSE.txt.
 *
 * GPL Classpath Exception:
 * Oracle designates this particular file as subject to the "Classpath"
 * exception as provided by Oracle in the GPL Version 2 section of the License
 * file that accompanied this code.
 *
 * Modifications:
 * If applicable, add the following below the License Header, with the fields
 * enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyright [year] [name of copyright owner]"
 *
 * Contributor(s):
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.
 *
 *
 * This file incorporates work covered by the following copyright and
 * permission notice:
 *
 * Copyright 2004 The Apache Software Foundation
 *
 * Licensed 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.*;
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). * * * @author Various */ 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. * *

It is possible that a servlet container may match a context by * more than one context path. In such cases this method will return the * actual context path used by the request and it may differ from the * path returned by the * {@link javax.servlet.ServletContext#getContextPath()} method. * The context path returned by * {@link javax.servlet.ServletContext#getContextPath()} * should be considered as the prime or preferred context path of the * application. * * @return a String specifying the * portion of the request URI that indicates the context * of the request * * @see javax.servlet.ServletContext#getContextPath() */ 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 *
* *

To reconstruct an URL with a scheme and host, use * {@link HttpUtils#getRequestURL}. * * @return a String containing * the part of the URL from the * protocol name up to the query string * * @see HttpUtils#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. * *

If this request has been forwarded using * {@link javax.servlet.RequestDispatcher#forward}, the server path in the * reconstructed URL must reflect the path used to obtain the * RequestDispatcher, and not the server path specified by the client. * *

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(); /** * * Checks whether the requested session ID is still valid. * *

If the client did not specify any session ID, this method returns * false. * * @return true if this * request has an id for a valid session * in the current session context; * false otherwise * * @see #getRequestedSessionId * @see #getSession * @see HttpSessionContext * */ 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. * */ public boolean isRequestedSessionIdFromUrl(); /** * Use the container login mechanism configured for the * ServletContext to authenticate the user making * this request. * *

This method may modify and commit the argument * HttpServletResponse. * * @param response The HttpServletResponse * associated with this HttpServletRequest * * @return true when non-null values were or have been * established as the values returned by getUserPrincipal, * getRemoteUser, and getAuthType. Return * false if authentication is incomplete and the underlying * login mechanism has committed, in the response, the message (e.g., * challenge) and HTTP status code to be returned to the user. * * @throws IOException if an input or output error occurred while * reading from this request or writing to the given response * * @throws IllegalStateException if the login mechanism attempted to * modify the response and it was already committed * * @throws ServletException if the authentication failed and * the caller is responsible for handling the error (i.e., the * underlying login mechanism did NOT establish the message and * HTTP status code to be returned to the user) * * @since Servlet 3.0 */ public boolean authenticate(HttpServletResponse response) throws IOException,ServletException; /** * Validate the provided username and password in the password validation * realm used by the web container login mechanism configured for the * ServletContext. * *

This method returns without throwing a ServletException * when the login mechanism configured for the ServletContext * supports username password validation, and when, at the time of the * call to login, the identity of the caller of the request had * not been established (i.e, all of getUserPrincipal, * getRemoteUser, and getAuthType return null), * and when validation of the provided credentials is successful. * Otherwise, this method throws a ServletException as * described below. * *

When this method returns without throwing an exception, it must * have established non-null values as the values returned by * getUserPrincipal, getRemoteUser, and * getAuthType. * * @param username The String value corresponding to * the login identifier of the user. * * @param password The password String corresponding * to the identified user. * * @exception ServletException if the configured login mechanism * does not support username * password authentication, or if a * non-null caller identity had * already been established (prior * to the call to login), or if * validation of the provided * username and password fails. * * @since Servlet 3.0 */ public void login(String username, String password) throws ServletException; /** * Establish null as the value returned when * getUserPrincipal, getRemoteUser, * and getAuthType is called on the request. * * @exception ServletException if logout fails * * @since Servlet 3.0 */ public void logout() throws ServletException; /** * Gets all the {@link Part} components of this request, provided * that it is of type multipart/form-data. * *

If this request is of type multipart/form-data, but * does not contain any Part components, the returned * Collection will be empty. * *

Any changes to the returned Collection must not * affect this HttpServletRequest. * * @return a (possibly empty) Collection of the * Part components of this request * * @throws IOException if an I/O error occurred during the retrieval * of the {@link Part} components of this request * * @throws ServletException if this request is not of type * multipart/form-data * * @throws IllegalStateException if the request body is larger than * maxRequestSize, or any Part in the request is larger than * maxFileSize * * @see javax.servlet.annotation.MultipartConfig#maxFileSize * @see javax.servlet.annotation.MultipartConfig#maxRequestSize * * @since Servlet 3.0 */ public Collection getParts() throws IOException, ServletException; /** * Gets the {@link Part} with the given name. * * @param name the name of the requested Part * * @return The Part with the given name, or null if this * request is of type multipart/form-data, but does not * contain the requested Part * * @throws IOException if an I/O error occurred during the retrieval * of the requested Part * @throws ServletException if this request is not of type * multipart/form-data * @throws IllegalStateException if the request body is larger than * maxRequestSize, or any Part in the request is larger than * maxFileSize * * @see javax.servlet.annotation.MultipartConfig#maxFileSize * @see javax.servlet.annotation.MultipartConfig#maxRequestSize * * @since Servlet 3.0 */ public Part getPart(String name) throws IOException, ServletException; }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy