2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
18 package javax.servlet.http;
20 import java.io.IOException;
21 import java.util.Collection;
22 import java.util.Enumeration;
24 import javax.servlet.ServletException;
25 import javax.servlet.ServletRequest;
28 * Extends the {@link javax.servlet.ServletRequest} interface to provide request
29 * information for HTTP servlets.
31 * The servlet container creates an <code>HttpServletRequest</code> object and
32 * passes it as an argument to the servlet's service methods
33 * (<code>doGet</code>, <code>doPost</code>, etc).
35 public interface HttpServletRequest extends ServletRequest {
38 * String identifier for Basic authentication. Value "BASIC"
40 public static final String BASIC_AUTH = "BASIC";
42 * String identifier for Form authentication. Value "FORM"
44 public static final String FORM_AUTH = "FORM";
46 * String identifier for Client Certificate authentication. Value
49 public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
51 * String identifier for Digest authentication. Value "DIGEST"
53 public static final String DIGEST_AUTH = "DIGEST";
56 * Returns the name of the authentication scheme used to protect the
57 * servlet. All servlet containers support basic, form and client
58 * certificate authentication, and may additionally support digest
59 * authentication. If the servlet is not authenticated <code>null</code> is
62 * Same as the value of the CGI variable AUTH_TYPE.
64 * @return one of the static members BASIC_AUTH, FORM_AUTH, CLIENT_CERT_AUTH,
65 * DIGEST_AUTH (suitable for == comparison) or the
66 * container-specific string indicating the authentication scheme,
67 * or <code>null</code> if the request was not authenticated.
69 public String getAuthType();
72 * Returns an array containing all of the <code>Cookie</code> objects the
73 * client sent with this request. This method returns <code>null</code> if
74 * no cookies were sent.
76 * @return an array of all the <code>Cookies</code> included with this
77 * request, or <code>null</code> if the request has no cookies
79 public Cookie[] getCookies();
82 * Returns the value of the specified request header as a <code>long</code>
83 * value that represents a <code>Date</code> object. Use this method with
84 * headers that contain dates, such as <code>If-Modified-Since</code>.
86 * The date is returned as the number of milliseconds since January 1, 1970
87 * GMT. The header name is case insensitive.
89 * If the request did not have a header of the specified name, this method
90 * returns -1. If the header can't be converted to a date, the method throws
91 * an <code>IllegalArgumentException</code>.
94 * a <code>String</code> specifying the name of the header
95 * @return a <code>long</code> value representing the date specified in the
96 * header expressed as the number of milliseconds since January 1,
97 * 1970 GMT, or -1 if the named header was not included with the
99 * @exception IllegalArgumentException
100 * If the header value can't be converted to a date
102 public long getDateHeader(String name);
105 * Returns the value of the specified request header as a
106 * <code>String</code>. If the request did not include a header of the
107 * specified name, this method returns <code>null</code>. If there are
108 * multiple headers with the same name, this method returns the first head
109 * in the request. The header name is case insensitive. You can use this
110 * method with any request header.
113 * a <code>String</code> specifying the header name
114 * @return a <code>String</code> containing the value of the requested
115 * header, or <code>null</code> if the request does not have a
116 * header of that name
118 public String getHeader(String name);
121 * Returns all the values of the specified request header as an
122 * <code>Enumeration</code> of <code>String</code> objects.
124 * Some headers, such as <code>Accept-Language</code> can be sent by clients
125 * as several headers each with a different value rather than sending the
126 * header as a comma separated list.
128 * If the request did not include any headers of the specified name, this
129 * method returns an empty <code>Enumeration</code>. The header name is case
130 * insensitive. You can use this method with any request header.
133 * a <code>String</code> specifying the header name
134 * @return an <code>Enumeration</code> containing the values of the requested
135 * header. If the request does not have any headers of that name
136 * return an empty enumeration. If the container does not allow
137 * access to header information, return null
139 public Enumeration<String> getHeaders(String name);
142 * Returns an enumeration of all the header names this request contains. If
143 * the request has no headers, this method returns an empty enumeration.
145 * Some servlet containers do not allow servlets to access headers using
146 * this method, in which case this method returns <code>null</code>
148 * @return an enumeration of all the header names sent with this request; if
149 * the request has no headers, an empty enumeration; if the servlet
150 * container does not allow servlets to use this method,
153 public Enumeration<String> getHeaderNames();
156 * Returns the value of the specified request header as an <code>int</code>.
157 * If the request does not have a header of the specified name, this method
158 * returns -1. If the header cannot be converted to an integer, this method
159 * throws a <code>NumberFormatException</code>.
161 * The header name is case insensitive.
164 * a <code>String</code> specifying the name of a request header
165 * @return an integer expressing the value of the request header or -1 if the
166 * request doesn't have a header of this name
167 * @exception NumberFormatException
168 * If the header value can't be converted to an
171 public int getIntHeader(String name);
174 * Returns the name of the HTTP method with which this request was made, for
175 * example, GET, POST, or PUT. Same as the value of the CGI variable
178 * @return a <code>String</code> specifying the name of the method with
179 * which this request was made
181 public String getMethod();
184 * Returns any extra path information associated with the URL the client
185 * sent when it made this request. The extra path information follows the
186 * servlet path but precedes the query string and will start with a "/"
189 * This method returns <code>null</code> if there was no extra path
192 * Same as the value of the CGI variable PATH_INFO.
194 * @return a <code>String</code>, decoded by the web container, specifying
195 * extra path information that comes after the servlet path but
196 * before the query string in the request URL; or <code>null</code>
197 * if the URL does not have any extra path information
199 public String getPathInfo();
202 * Returns any extra path information after the servlet name but before the
203 * query string, and translates it to a real path. Same as the value of the
204 * CGI variable PATH_TRANSLATED.
206 * If the URL does not have any extra path information, this method returns
207 * <code>null</code> or the servlet container cannot translate the virtual
208 * path to a real path for any reason (such as when the web application is
209 * executed from an archive). The web container does not decode this string.
211 * @return a <code>String</code> specifying the real path, or
212 * <code>null</code> if the URL does not have any extra path
215 public String getPathTranslated();
218 * Returns the portion of the request URI that indicates the context of the
219 * request. The context path always comes first in a request URI. The path
220 * starts with a "/" character but does not end with a "/" character. For
221 * servlets in the default (root) context, this method returns "". The
222 * container does not decode this string.
224 * @return a <code>String</code> specifying the portion of the request URI
225 * that indicates the context of the request
227 public String getContextPath();
230 * Returns the query string that is contained in the request URL after the
231 * path. This method returns <code>null</code> if the URL does not have a
232 * query string. Same as the value of the CGI variable QUERY_STRING.
234 * @return a <code>String</code> containing the query string or
235 * <code>null</code> if the URL contains no query string. The value
236 * is not decoded by the container.
238 public String getQueryString();
241 * Returns the login of the user making this request, if the user has been
242 * authenticated, or <code>null</code> if the user has not been
243 * authenticated. Whether the user name is sent with each subsequent request
244 * depends on the browser and type of authentication. Same as the value of
245 * the CGI variable REMOTE_USER.
247 * @return a <code>String</code> specifying the login of the user making
248 * this request, or <code>null</code> if the user login is not known
250 public String getRemoteUser();
253 * Returns a boolean indicating whether the authenticated user is included
254 * in the specified logical "role". Roles and role membership can be defined
255 * using deployment descriptors. If the user has not been authenticated, the
256 * method returns <code>false</code>.
259 * a <code>String</code> specifying the name of the role
260 * @return a <code>boolean</code> indicating whether the user making this
261 * request belongs to a given role; <code>false</code> if the user
262 * has not been authenticated
264 public boolean isUserInRole(String role);
267 * Returns a <code>java.security.Principal</code> object containing the name
268 * of the current authenticated user. If the user has not been
269 * authenticated, the method returns <code>null</code>.
271 * @return a <code>java.security.Principal</code> containing the name of the
272 * user making this request; <code>null</code> if the user has not
275 public java.security.Principal getUserPrincipal();
278 * Returns the session ID specified by the client. This may not be the same
279 * as the ID of the current valid session for this request. If the client
280 * did not specify a session ID, this method returns <code>null</code>.
282 * @return a <code>String</code> specifying the session ID, or
283 * <code>null</code> if the request did not specify a session ID
284 * @see #isRequestedSessionIdValid
286 public String getRequestedSessionId();
289 * Returns the part of this request's URL from the protocol name up to the
290 * query string in the first line of the HTTP request. The web container
291 * does not decode this String. For example:
292 * <table summary="Examples of Returned Values">
294 * <th>First line of HTTP request</th>
295 * <th>Returned Value</th>
297 * <td>POST /some/path.html HTTP/1.1
299 * <td>/some/path.html
301 * <td>GET http://foo.bar/a.html HTTP/1.0
305 * <td>HEAD /xyz?a=b HTTP/1.1
310 * To reconstruct an URL with a scheme and host, use
311 * {@link #getRequestURL}.
313 * @return a <code>String</code> containing the part of the URL from the
314 * protocol name up to the query string
315 * @see #getRequestURL
317 public String getRequestURI();
320 * Reconstructs the URL the client used to make the request. The returned
321 * URL contains a protocol, server name, port number, and server path, but
322 * it does not include query string parameters.
324 * Because this method returns a <code>StringBuffer</code>, not a string,
325 * you can modify the URL easily, for example, to append query parameters.
327 * This method is useful for creating redirect messages and for reporting
330 * @return a <code>StringBuffer</code> object containing the reconstructed
333 public StringBuffer getRequestURL();
336 * Returns the part of this request's URL that calls the servlet. This path
337 * starts with a "/" character and includes either the servlet name or a
338 * path to the servlet, but does not include any extra path information or a
339 * query string. Same as the value of the CGI variable SCRIPT_NAME.
341 * This method will return an empty string ("") if the servlet used to
342 * process this request was matched using the "/*" pattern.
344 * @return a <code>String</code> containing the name or path of the servlet
345 * being called, as specified in the request URL, decoded, or an
346 * empty string if the servlet used to process the request is
347 * matched using the "/*" pattern.
349 public String getServletPath();
352 * Returns the current <code>HttpSession</code> associated with this request
353 * or, if there is no current session and <code>create</code> is true,
354 * returns a new session.
356 * If <code>create</code> is <code>false</code> and the request has no valid
357 * <code>HttpSession</code>, this method returns <code>null</code>.
359 * To make sure the session is properly maintained, you must call this
360 * method before the response is committed. If the container is using
361 * cookies to maintain session integrity and is asked to create a new
362 * session when the response is committed, an IllegalStateException is
366 * <code>true</code> to create a new session for this request if
367 * necessary; <code>false</code> to return <code>null</code> if
368 * there's no current session
369 * @return the <code>HttpSession</code> associated with this request or
370 * <code>null</code> if <code>create</code> is <code>false</code>
371 * and the request has no valid session
374 public HttpSession getSession(boolean create);
377 * Returns the current session associated with this request, or if the
378 * request does not have a session, creates one.
380 * @return the <code>HttpSession</code> associated with this request
381 * @see #getSession(boolean)
383 public HttpSession getSession();
386 * Changes the session ID of the session associated with this request. This
387 * method does not create a new session object it only changes the ID of the
390 * @return the new session ID allocated to the session
391 * @see HttpSessionIdListener
394 public String changeSessionId();
397 * Checks whether the requested session ID is still valid.
399 * @return <code>true</code> if this request has an id for a valid session
400 * in the current session context; <code>false</code> otherwise
401 * @see #getRequestedSessionId
404 public boolean isRequestedSessionIdValid();
407 * Checks whether the requested session ID came in as a cookie.
409 * @return <code>true</code> if the session ID came in as a cookie;
410 * otherwise, <code>false</code>
413 public boolean isRequestedSessionIdFromCookie();
416 * Checks whether the requested session ID came in as part of the request
419 * @return <code>true</code> if the session ID came in as part of a URL;
420 * otherwise, <code>false</code>
423 public boolean isRequestedSessionIdFromURL();
426 * @deprecated As of Version 2.1 of the Java Servlet API, use
427 * {@link #isRequestedSessionIdFromURL} instead.
429 @SuppressWarnings("dep-ann")
430 // Spec API does not use @Deprecated
431 public boolean isRequestedSessionIdFromUrl();
434 * Triggers the same authentication process as would be triggered if the
435 * request is for a resource that is protected by a security constraint.
437 * @param response The response to use to return any authentication
439 * @return <code>true</code> if the user is successfully authenticated and
440 * <code>false</code> if not
444 public boolean authenticate(HttpServletResponse response)
445 throws IOException, ServletException;
448 * Authenticate the provided user name and password and then associated the
449 * authenticated user with the request.
451 * @param username The user name to authenticate
452 * @param password The password to use to authenticate the user
454 * @throws ServletException
455 * If any of {@link #getRemoteUser()},
456 * {@link #getUserPrincipal()} or {@link #getAuthType()} are
457 * non-null, if the configured authenticator does not support
458 * user name and password authentication or if the
459 * authentication fails
462 public void login(String username, String password) throws ServletException;
465 * Removes any authenticated user from the request.
467 * @throws ServletException
468 * If the logout fails
471 public void logout() throws ServletException;
474 * Return a collection of all uploaded Parts.
476 * @return A collection of all uploaded Parts.
477 * @throws IOException
478 * if an I/O error occurs
479 * @throws IllegalStateException
480 * if size limits are exceeded or no multipart configuration is
482 * @throws ServletException
483 * if the request is not multipart/form-data
486 public Collection<Part> getParts() throws IOException,
490 * Gets the named Part or null if the Part does not exist. Triggers upload
494 * @return The named Part or null if the Part does not exist
495 * @throws IOException
496 * if an I/O error occurs
497 * @throws IllegalStateException
498 * if size limits are exceeded
499 * @throws ServletException
500 * if the request is not multipart/form-data
503 public Part getPart(String name) throws IOException,
507 * Start the HTTP upgrade process and pass the connection to the provided
508 * protocol handler once the current request/response pair has completed
509 * processing. Calling this method sets the response status to {@link
510 * HttpServletResponse#SC_SWITCHING_PROTOCOLS} and flushes the response.
511 * Protocol specific headers must have already been set before this method
514 * @throws IOException
515 * if an I/O error occurred during the upgrade
516 * @throws ServletException
517 * if the given httpUpgradeHandlerClass fails to be instantiated
520 public <T extends HttpUpgradeHandler> T upgrade(
521 Class<T> httpUpgradeHandlerClass) throws java.io.IOException, ServletException;