001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019
020 package javax.servlet.http;
021
022 import java.io.IOException;
023 import java.util.Collection;
024 import java.util.Enumeration;
025
026 import javax.servlet.ServletException;
027 import javax.servlet.ServletRequest;
028
029 /**
030 * Extends the {@link javax.servlet.ServletRequest} interface
031 * to provide request information for HTTP servlets.
032 * <p/>
033 * <p>The servlet container creates an <code>HttpServletRequest</code>
034 * object and passes it as an argument to the servlet's service
035 * methods (<code>doGet</code>, <code>doPost</code>, etc).
036 *
037 * @version $Rev: 835965 $ $Date: 2009-11-13 14:40:44 -0500 (Fri, 13 Nov 2009) $
038 */
039
040 public interface HttpServletRequest extends ServletRequest {
041
042 /**
043 * String identifier for Basic authentication. Value "BASIC"
044 */
045 String BASIC_AUTH = "BASIC";
046 /**
047 * String identifier for Form authentication. Value "FORM"
048 */
049 String FORM_AUTH = "FORM";
050 /**
051 * String identifier for Client Certificate authentication. Value "CLIENT_CERT"
052 */
053 String CLIENT_CERT_AUTH = "CLIENT_CERT";
054 /**
055 * String identifier for Digest authentication. Value "DIGEST"
056 */
057 String DIGEST_AUTH = "DIGEST";
058
059 /**
060 * authenticate user using container facilities
061 *
062 * @param response response to use to conduct a dialog if necessary
063 * @return whether authentication was successful
064 * @throws javax.servlet.ServletException if something goes wrong
065 * @throws java.io.IOException if something IO related goes wrong
066 * @since 3.0
067 */
068 boolean authenticate(HttpServletResponse response) throws IOException, ServletException;
069
070 /**
071 * Returns the name of the authentication scheme used to protect
072 * the servlet. All servlet containers support basic, form and client
073 * certificate authentication, and may additionally support digest
074 * authentication.
075 * If the servlet is not authenticated <code>null</code> is returned.
076 * <p/>
077 * <p>Same as the value of the CGI variable AUTH_TYPE.
078 *
079 * @return one of the static members BASIC_AUTH,
080 * FORM_AUTH, CLIENT_CERT_AUTH, DIGEST_AUTH
081 * (suitable for == comparison) or
082 * the container-specific string indicating
083 * the authentication scheme, or
084 * <code>null</code> if the request was
085 * not authenticated.
086 */
087 String getAuthType();
088
089 /**
090 * Returns the portion of the request URI that indicates the context
091 * of the request. The context path always comes first in a request
092 * URI. The path starts with a "/" character but does not end with a "/"
093 * character. For servlets in the default (root) context, this method
094 * returns "". The container does not decode this string.
095 *
096 * @return a <code>String</code> specifying the
097 * portion of the request URI that indicates the context
098 * of the request
099 */
100 String getContextPath();
101
102 /**
103 * Returns an array containing all of the <code>Cookie</code>
104 * objects the client sent with this request.
105 * This method returns <code>null</code> if no cookies were sent.
106 *
107 * @return an array of all the <code>Cookies</code>
108 * included with this request, or <code>null</code>
109 * if the request has no cookies
110 */
111 Cookie[] getCookies();
112
113 /**
114 * Returns the value of the specified request header
115 * as a <code>long</code> value that represents a
116 * <code>Date</code> object. Use this method with
117 * headers that contain dates, such as
118 * <code>If-Modified-Since</code>.
119 * <p/>
120 * <p>The date is returned as
121 * the number of milliseconds since January 1, 1970 GMT.
122 * The header name is case insensitive.
123 * <p/>
124 * <p>If the request did not have a header of the
125 * specified name, this method returns -1. If the header
126 * can't be converted to a date, the method throws
127 * an <code>IllegalArgumentException</code>.
128 *
129 * @param name a <code>String</code> specifying the
130 * name of the header
131 * @return a <code>long</code> value
132 * representing the date specified
133 * in the header expressed as
134 * the number of milliseconds
135 * since January 1, 1970 GMT,
136 * or -1 if the named header
137 * was not included with the
138 * request
139 * @throws IllegalArgumentException If the header value
140 * can't be converted
141 * to a date
142 */
143 long getDateHeader(String name);
144
145 /**
146 * Returns the value of the specified request header
147 * as a <code>String</code>. If the request did not include a header
148 * of the specified name, this method returns <code>null</code>.
149 * If there are multiple headers with the same name, this method
150 * returns the first head in the request.
151 * The header name is case insensitive. You can use
152 * this method with any request header.
153 *
154 * @param name a <code>String</code> specifying the
155 * header name
156 * @return a <code>String</code> containing the
157 * value of the requested
158 * header, or <code>null</code>
159 * if the request does not
160 * have a header of that name
161 */
162 String getHeader(String name);
163
164 /**
165 * Returns an enumeration of all the header names
166 * this request contains. If the request has no
167 * headers, this method returns an empty enumeration.
168 * <p/>
169 * <p>Some servlet containers do not allow
170 * servlets to access headers using this method, in
171 * which case this method returns <code>null</code>
172 *
173 * @return an enumeration of all the
174 * header names sent with this
175 * request; if the request has
176 * no headers, an empty enumeration;
177 * if the servlet container does not
178 * allow servlets to use this method,
179 * <code>null</code>
180 */
181 Enumeration<String> getHeaderNames();
182
183 /**
184 * Returns all the values of the specified request header
185 * as an <code>Enumeration</code> of <code>String</code> objects.
186 * <p/>
187 * <p>Some headers, such as <code>Accept-Language</code> can be sent
188 * by clients as several headers each with a different value rather than
189 * sending the header as a comma separated list.
190 * <p/>
191 * <p>If the request did not include any headers
192 * of the specified name, this method returns an empty
193 * <code>Enumeration</code>.
194 * The header name is case insensitive. You can use
195 * this method with any request header.
196 *
197 * @param name a <code>String</code> specifying the
198 * header name
199 * @return an <code>Enumeration</code> containing
200 * the values of the requested header. If
201 * the request does not have any headers of
202 * that name return an empty
203 * enumeration. If
204 * the container does not allow access to
205 * header information, return null
206 */
207 Enumeration<String> getHeaders(String name);
208
209 /**
210 * Returns the value of the specified request header
211 * as an <code>int</code>. If the request does not have a header
212 * of the specified name, this method returns -1. If the
213 * header cannot be converted to an integer, this method
214 * throws a <code>NumberFormatException</code>.
215 * <p/>
216 * <p>The header name is case insensitive.
217 *
218 * @param name a <code>String</code> specifying the name
219 * of a request header
220 * @return an integer expressing the value
221 * of the request header or -1
222 * if the request doesn't have a
223 * header of this name
224 * @throws NumberFormatException If the header value
225 * can't be converted
226 * to an <code>int</code>
227 */
228 int getIntHeader(String name);
229
230 /**
231 * Returns the name of the HTTP method with which this
232 * request was made, for example, GET, POST, or PUT.
233 * Same as the value of the CGI variable REQUEST_METHOD.
234 *
235 * @return a <code>String</code>
236 * specifying the name
237 * of the method with which
238 * this request was made
239 */
240 String getMethod();
241
242 /**
243 * @param name part name
244 * @return named part
245 * @throws java.io.IOException if something IO related goes wrong
246 * @throws javax.servlet.ServletException if something goes wrong
247 * @since 3.0
248 */
249 Part getPart(String name) throws IOException, ServletException;
250
251 /**
252 * @return all the parts
253 * @throws java.io.IOException if something IO related goes wrong
254 * @throws javax.servlet.ServletException if something goes wrong
255 * @since 3.0
256 */
257 Collection<Part> getParts() throws IOException, ServletException;
258
259 /**
260 * Returns any extra path information associated with
261 * the URL the client sent when it made this request.
262 * The extra path information follows the servlet path
263 * but precedes the query string and will start with
264 * a "/" character.
265 * <p/>
266 * <p>This method returns <code>null</code> if there
267 * was no extra path information.
268 * <p/>
269 * <p>Same as the value of the CGI variable PATH_INFO.
270 *
271 * @return a <code>String</code>, decoded by the
272 * web container, specifying
273 * extra path information that comes
274 * after the servlet path but before
275 * the query string in the request URL;
276 * or <code>null</code> if the URL does not have
277 * any extra path information
278 */
279 String getPathInfo();
280
281 /**
282 * Returns any extra path information after the servlet name
283 * but before the query string, and translates it to a real
284 * path. Same as the value of the CGI variable PATH_TRANSLATED.
285 * <p/>
286 * <p>If the URL does not have any extra path information,
287 * this method returns <code>null</code> or the servlet container
288 * cannot translate the virtual path to a real path for any reason
289 * (such as when the web application is executed from an archive).
290 * <p/>
291 * The web container does not decode this string.
292 *
293 * @return a <code>String</code> specifying the
294 * real path, or <code>null</code> if
295 * the URL does not have any extra path
296 * information
297 */
298 String getPathTranslated();
299
300 /**
301 * Returns the query string that is contained in the request
302 * URL after the path. This method returns <code>null</code>
303 * if the URL does not have a query string. Same as the value
304 * of the CGI variable QUERY_STRING.
305 *
306 * @return a <code>String</code> containing the query
307 * string or <code>null</code> if the URL
308 * contains no query string. The value is not
309 * decoded by the container.
310 */
311 String getQueryString();
312
313 /**
314 * Returns the login of the user making this request, if the
315 * user has been authenticated, or <code>null</code> if the user
316 * has not been authenticated.
317 * Whether the user name is sent with each subsequent request
318 * depends on the browser and type of authentication. Same as the
319 * value of the CGI variable REMOTE_USER.
320 *
321 * @return a <code>String</code> specifying the login
322 * of the user making this request, or <code>null</code>
323 * if the user login is not known
324 */
325 String getRemoteUser();
326
327 /**
328 * Returns the session ID specified by the client. This may
329 * not be the same as the ID of the current valid session
330 * for this request.
331 * If the client did not specify a session ID, this method returns
332 * <code>null</code>.
333 *
334 * @return a <code>String</code> specifying the session
335 * ID, or <code>null</code> if the request did
336 * not specify a session ID
337 * @see #isRequestedSessionIdValid
338 */
339 String getRequestedSessionId();
340
341 /**
342 * Returns the part of this request's URL from the protocol
343 * name up to the query string in the first line of the HTTP request.
344 * The web container does not decode this String.
345 * For example:
346 * <p/>
347 * <p/>
348 * <table summary="Examples of Returned Values">
349 * <tr align=left><th>First line of HTTP request </th>
350 * <th> Returned Value</th>
351 * <tr><td>POST /some/path.html HTTP/1.1<td><td>/some/path.html
352 * <tr><td>GET http://foo.bar/a.html HTTP/1.0
353 * <td><td>/a.html
354 * <tr><td>HEAD /xyz?a=b HTTP/1.1<td><td>/xyz
355 * </table>
356 * <p/>
357 * <p>To reconstruct an URL with a scheme and host, use
358 * {@link HttpUtils#getRequestURL}.
359 *
360 * @return a <code>String</code> containing
361 * the part of the URL from the
362 * protocol name up to the query string
363 * @see HttpUtils#getRequestURL
364 */
365 String getRequestURI();
366
367 /**
368 * Reconstructs the URL the client used to make the request.
369 * The returned URL contains a protocol, server name, port
370 * number, and server path, but it does not include query
371 * string parameters.
372 * <p/>
373 * <p>Because this method returns a <code>StringBuffer</code>,
374 * not a string, you can modify the URL easily, for example,
375 * to append query parameters.
376 * <p/>
377 * <p>This method is useful for creating redirect messages
378 * and for reporting errors.
379 *
380 * @return a <code>StringBuffer</code> object containing
381 * the reconstructed URL
382 */
383 StringBuffer getRequestURL();
384
385 /**
386 * Returns the part of this request's URL that calls
387 * the servlet. This path starts with a "/" character
388 * and includes either the servlet name or a path to
389 * the servlet, but does not include any extra path
390 * information or a query string. Same as the value of
391 * the CGI variable SCRIPT_NAME.
392 * <p/>
393 * <p>This method will return an empty string ("") if the
394 * servlet used to process this request was matched using
395 * the "/*" pattern.
396 *
397 * @return a <code>String</code> containing
398 * the name or path of the servlet being
399 * called, as specified in the request URL,
400 * decoded, or an empty string if the servlet
401 * used to process the request is matched
402 * using the "/*" pattern.
403 */
404 String getServletPath();
405
406 /**
407 * Returns the current session associated with this request,
408 * or if the request does not have a session, creates one.
409 *
410 * @return the <code>HttpSession</code> associated
411 * with this request
412 * @see #getSession(boolean)
413 */
414 HttpSession getSession();
415
416 /**
417 * Returns the current <code>HttpSession</code>
418 * associated with this request or, if there is no
419 * current session and <code>create</code> is true, returns
420 * a new session.
421 * <p/>
422 * <p>If <code>create</code> is <code>false</code>
423 * and the request has no valid <code>HttpSession</code>,
424 * this method returns <code>null</code>.
425 * <p/>
426 * <p>To make sure the session is properly maintained,
427 * you must call this method before
428 * the response is committed. If the container is using cookies
429 * to maintain session integrity and is asked to create a new session
430 * when the response is committed, an IllegalStateException is thrown.
431 *
432 * @param create <code>true</code> to create
433 * a new session for this request if necessary;
434 * <code>false</code> to return <code>null</code>
435 * if there's no current session
436 * @return the <code>HttpSession</code> associated
437 * with this request or <code>null</code> if
438 * <code>create</code> is <code>false</code>
439 * and the request has no valid session
440 * @see #getSession()
441 */
442 HttpSession getSession(boolean create);
443
444 /**
445 * Returns a <code>java.security.Principal</code> object containing
446 * the name of the current authenticated user. If the user has not been
447 * authenticated, the method returns <code>null</code>.
448 *
449 * @return a <code>java.security.Principal</code> containing
450 * the name of the user making this request;
451 * <code>null</code> if the user has not been
452 * authenticated
453 */
454 java.security.Principal getUserPrincipal();
455
456 /**
457 * Checks whether the requested session ID came in as a cookie.
458 *
459 * @return <code>true</code> if the session ID
460 * came in as a
461 * cookie; otherwise, <code>false</code>
462 * @see #getSession
463 */
464 boolean isRequestedSessionIdFromCookie();
465
466 /**
467 * @deprecated As of Version 2.1 of the Java Servlet
468 * API, use {@link #isRequestedSessionIdFromURL}
469 * instead.
470 */
471 boolean isRequestedSessionIdFromUrl();
472
473 /**
474 * Checks whether the requested session ID came in as part of the
475 * request URL.
476 *
477 * @return <code>true</code> if the session ID
478 * came in as part of a URL; otherwise,
479 * <code>false</code>
480 * @see #getSession
481 */
482 boolean isRequestedSessionIdFromURL();
483
484 /**
485 * Checks whether the requested session ID is still valid.
486 *
487 * @return <code>true</code> if this
488 * request has an id for a valid session
489 * in the current session context;
490 * <code>false</code> otherwise
491 * @see #getRequestedSessionId
492 * @see #getSession
493 * @see HttpSessionContext
494 */
495 boolean isRequestedSessionIdValid();
496
497 /**
498 * Returns a boolean indicating whether the authenticated user is included
499 * in the specified logical "role". Roles and role membership can be
500 * defined using deployment descriptors. If the user has not been
501 * authenticated, the method returns <code>false</code>.
502 *
503 * @param role a <code>String</code> specifying the name
504 * of the role
505 * @return a <code>boolean</code> indicating whether
506 * the user making this request belongs to a given role;
507 * <code>false</code> if the user has not been
508 * authenticated
509 */
510 boolean isUserInRole(String role);
511
512 /**
513 * @param username username
514 * @param password password
515 * @since 3.0
516 * @throws javax.servlet.ServletException if username/password authentication not supported,
517 * if a user has already been established, or if authentication fails.
518 */
519 void login(String username, String password) throws ServletException;
520
521 /**
522 * @since 3.0
523 * @throws javax.servlet.ServletException if logout fails
524 */
525 void logout() throws ServletException;
526
527 }