1 /*
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
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
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.
16 */
17
18 package javax.servlet.http;
19
20 import javax.servlet.ServletRequest;
21 import java.util.Enumeration;
22
23 /**
24 *
25 * Extends the {@link javax.servlet.ServletRequest} interface
26 * to provide request information for HTTP servlets.
27 *
28 * <p>The servlet container creates an <code>HttpServletRequest</code>
29 * object and passes it as an argument to the servlet's service
30 * methods (<code>doGet</code>, <code>doPost</code>, etc).
31 *
32 *
33 * @author Various
34 * @version $Version$
35 *
36 *
37 */
38
39 public interface HttpServletRequest extends ServletRequest {
40
41 /**
42 * String identifier for Basic authentication. Value "BASIC"
43 */
44 public static final String BASIC_AUTH = "BASIC";
45 /**
46 * String identifier for Form authentication. Value "FORM"
47 */
48 public static final String FORM_AUTH = "FORM";
49 /**
50 * String identifier for Client Certificate authentication. Value "CLIENT_CERT"
51 */
52 public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
53 /**
54 * String identifier for Digest authentication. Value "DIGEST"
55 */
56 public static final String DIGEST_AUTH = "DIGEST";
57
58 /**
59 * Returns the name of the authentication scheme used to protect
60 * the servlet. All servlet containers support basic, form and client
61 * certificate authentication, and may additionally support digest
62 * authentication.
63 * If the servlet is not authenticated <code>null</code> is returned.
64 *
65 * <p>Same as the value of the CGI variable AUTH_TYPE.
66 *
67 *
68 * @return one of the static members BASIC_AUTH,
69 * FORM_AUTH, CLIENT_CERT_AUTH, DIGEST_AUTH
70 * (suitable for == comparison) or
71 * the container-specific string indicating
72 * the authentication scheme, or
73 * <code>null</code> if the request was
74 * not authenticated.
75 *
76 */
77
78 public String getAuthType();
79
80
81
82
83 /**
84 *
85 * Returns an array containing all of the <code>Cookie</code>
86 * objects the client sent with this request.
87 * This method returns <code>null</code> if no cookies were sent.
88 *
89 * @return an array of all the <code>Cookies</code>
90 * included with this request, or <code>null</code>
91 * if the request has no cookies
92 *
93 *
94 */
95
96 public Cookie[] getCookies();
97
98
99
100
101 /**
102 *
103 * Returns the value of the specified request header
104 * as a <code>long</code> value that represents a
105 * <code>Date</code> object. Use this method with
106 * headers that contain dates, such as
107 * <code>If-Modified-Since</code>.
108 *
109 * <p>The date is returned as
110 * the number of milliseconds since January 1, 1970 GMT.
111 * The header name is case insensitive.
112 *
113 * <p>If the request did not have a header of the
114 * specified name, this method returns -1. If the header
115 * can't be converted to a date, the method throws
116 * an <code>IllegalArgumentException</code>.
117 *
118 * @param name a <code>String</code> specifying the
119 * name of the header
120 *
121 * @return a <code>long</code> value
122 * representing the date specified
123 * in the header expressed as
124 * the number of milliseconds
125 * since January 1, 1970 GMT,
126 * or -1 if the named header
127 * was not included with the
128 * request
129 *
130 * @exception IllegalArgumentException If the header value
131 * can't be converted
132 * to a date
133 *
134 */
135
136 public long getDateHeader(String name);
137
138
139
140
141 /**
142 *
143 * Returns the value of the specified request header
144 * as a <code>String</code>. If the request did not include a header
145 * of the specified name, this method returns <code>null</code>.
146 * If there are multiple headers with the same name, this method
147 * returns the first head in the request.
148 * The header name is case insensitive. You can use
149 * this method with any request header.
150 *
151 * @param name a <code>String</code> specifying the
152 * header name
153 *
154 * @return a <code>String</code> containing the
155 * value of the requested
156 * header, or <code>null</code>
157 * if the request does not
158 * have a header of that name
159 *
160 */
161
162 public String getHeader(String name);
163
164
165
166
167 /**
168 *
169 * Returns all the values of the specified request header
170 * as an <code>Enumeration</code> of <code>String</code> objects.
171 *
172 * <p>Some headers, such as <code>Accept-Language</code> can be sent
173 * by clients as several headers each with a different value rather than
174 * sending the header as a comma separated list.
175 *
176 * <p>If the request did not include any headers
177 * of the specified name, this method returns an empty
178 * <code>Enumeration</code>.
179 * The header name is case insensitive. You can use
180 * this method with any request header.
181 *
182 * @param name a <code>String</code> specifying the
183 * header name
184 *
185 * @return an <code>Enumeration</code> containing
186 * the values of the requested header. If
187 * the request does not have any headers of
188 * that name return an empty
189 * enumeration. If
190 * the container does not allow access to
191 * header information, return null
192 *
193 */
194
195 public Enumeration getHeaders(String name);
196
197
198
199
200
201 /**
202 *
203 * Returns an enumeration of all the header names
204 * this request contains. If the request has no
205 * headers, this method returns an empty enumeration.
206 *
207 * <p>Some servlet containers do not allow
208 * servlets to access headers using this method, in
209 * which case this method returns <code>null</code>
210 *
211 * @return an enumeration of all the
212 * header names sent with this
213 * request; if the request has
214 * no headers, an empty enumeration;
215 * if the servlet container does not
216 * allow servlets to use this method,
217 * <code>null</code>
218 *
219 *
220 */
221
222 public Enumeration getHeaderNames();
223
224
225
226
227 /**
228 *
229 * Returns the value of the specified request header
230 * as an <code>int</code>. If the request does not have a header
231 * of the specified name, this method returns -1. If the
232 * header cannot be converted to an integer, this method
233 * throws a <code>NumberFormatException</code>.
234 *
235 * <p>The header name is case insensitive.
236 *
237 * @param name a <code>String</code> specifying the name
238 * of a request header
239 *
240 * @return an integer expressing the value
241 * of the request header or -1
242 * if the request doesn't have a
243 * header of this name
244 *
245 * @exception NumberFormatException If the header value
246 * can't be converted
247 * to an <code>int</code>
248 */
249
250 public int getIntHeader(String name);
251
252
253
254
255 /**
256 *
257 * Returns the name of the HTTP method with which this
258 * request was made, for example, GET, POST, or PUT.
259 * Same as the value of the CGI variable REQUEST_METHOD.
260 *
261 * @return a <code>String</code>
262 * specifying the name
263 * of the method with which
264 * this request was made
265 *
266 */
267
268 public String getMethod();
269
270
271
272
273 /**
274 *
275 * Returns any extra path information associated with
276 * the URL the client sent when it made this request.
277 * The extra path information follows the servlet path
278 * but precedes the query string and will start with
279 * a "/" character.
280 *
281 * <p>This method returns <code>null</code> if there
282 * was no extra path information.
283 *
284 * <p>Same as the value of the CGI variable PATH_INFO.
285 *
286 *
287 * @return a <code>String</code>, decoded by the
288 * web container, specifying
289 * extra path information that comes
290 * after the servlet path but before
291 * the query string in the request URL;
292 * or <code>null</code> if the URL does not have
293 * any extra path information
294 *
295 */
296
297 public String getPathInfo();
298
299
300
301
302 /**
303 *
304 * Returns any extra path information after the servlet name
305 * but before the query string, and translates it to a real
306 * path. Same as the value of the CGI variable PATH_TRANSLATED.
307 *
308 * <p>If the URL does not have any extra path information,
309 * this method returns <code>null</code> or the servlet container
310 * cannot translate the virtual path to a real path for any reason
311 * (such as when the web application is executed from an archive).
312 *
313 * The web container does not decode this string.
314 *
315 *
316 * @return a <code>String</code> specifying the
317 * real path, or <code>null</code> if
318 * the URL does not have any extra path
319 * information
320 *
321 *
322 */
323
324 public String getPathTranslated();
325
326
327
328
329 /**
330 *
331 * Returns the portion of the request URI that indicates the context
332 * of the request. The context path always comes first in a request
333 * URI. The path starts with a "/" character but does not end with a "/"
334 * character. For servlets in the default (root) context, this method
335 * returns "". The container does not decode this string.
336 *
337 *
338 * @return a <code>String</code> specifying the
339 * portion of the request URI that indicates the context
340 * of the request
341 *
342 *
343 */
344
345 public String getContextPath();
346
347
348
349
350 /**
351 *
352 * Returns the query string that is contained in the request
353 * URL after the path. This method returns <code>null</code>
354 * if the URL does not have a query string. Same as the value
355 * of the CGI variable QUERY_STRING.
356 *
357 * @return a <code>String</code> containing the query
358 * string or <code>null</code> if the URL
359 * contains no query string. The value is not
360 * decoded by the container.
361 *
362 */
363
364 public String getQueryString();
365
366
367
368
369 /**
370 *
371 * Returns the login of the user making this request, if the
372 * user has been authenticated, or <code>null</code> if the user
373 * has not been authenticated.
374 * Whether the user name is sent with each subsequent request
375 * depends on the browser and type of authentication. Same as the
376 * value of the CGI variable REMOTE_USER.
377 *
378 * @return a <code>String</code> specifying the login
379 * of the user making this request, or <code>null</code>
380 * if the user login is not known
381 *
382 */
383
384 public String getRemoteUser();
385
386
387
388
389 /**
390 *
391 * Returns a boolean indicating whether the authenticated user is included
392 * in the specified logical "role". Roles and role membership can be
393 * defined using deployment descriptors. If the user has not been
394 * authenticated, the method returns <code>false</code>.
395 *
396 * @param role a <code>String</code> specifying the name
397 * of the role
398 *
399 * @return a <code>boolean</code> indicating whether
400 * the user making this request belongs to a given role;
401 * <code>false</code> if the user has not been
402 * authenticated
403 *
404 */
405
406 public boolean isUserInRole(String role);
407
408
409
410
411 /**
412 *
413 * Returns a <code>java.security.Principal</code> object containing
414 * the name of the current authenticated user. If the user has not been
415 * authenticated, the method returns <code>null</code>.
416 *
417 * @return a <code>java.security.Principal</code> containing
418 * the name of the user making this request;
419 * <code>null</code> if the user has not been
420 * authenticated
421 *
422 */
423
424 public java.security.Principal getUserPrincipal();
425
426
427
428
429 /**
430 *
431 * Returns the session ID specified by the client. This may
432 * not be the same as the ID of the current valid session
433 * for this request.
434 * If the client did not specify a session ID, this method returns
435 * <code>null</code>.
436 *
437 *
438 * @return a <code>String</code> specifying the session
439 * ID, or <code>null</code> if the request did
440 * not specify a session ID
441 *
442 * @see #isRequestedSessionIdValid
443 *
444 */
445
446 public String getRequestedSessionId();
447
448
449
450
451 /**
452 *
453 * Returns the part of this request's URL from the protocol
454 * name up to the query string in the first line of the HTTP request.
455 * The web container does not decode this String.
456 * For example:
457 *
458 *
459
460 * <table summary="Examples of Returned Values">
461 * <tr align=left><th>First line of HTTP request </th>
462 * <th> Returned Value</th>
463 * <tr><td>POST /some/path.html HTTP/1.1<td><td>/some/path.html
464 * <tr><td>GET http://foo.bar/a.html HTTP/1.0
465 * <td><td>/a.html
466 * <tr><td>HEAD /xyz?a=b HTTP/1.1<td><td>/xyz
467 * </table>
468 *
469 * <p>To reconstruct an URL with a scheme and host, use
470 * {@link HttpUtils#getRequestURL}.
471 *
472 * @return a <code>String</code> containing
473 * the part of the URL from the
474 * protocol name up to the query string
475 *
476 * @see HttpUtils#getRequestURL
477 *
478 */
479
480 public String getRequestURI();
481
482 /**
483 *
484 * Reconstructs the URL the client used to make the request.
485 * The returned URL contains a protocol, server name, port
486 * number, and server path, but it does not include query
487 * string parameters.
488 *
489 * <p>Because this method returns a <code>StringBuffer</code>,
490 * not a string, you can modify the URL easily, for example,
491 * to append query parameters.
492 *
493 * <p>This method is useful for creating redirect messages
494 * and for reporting errors.
495 *
496 * @return a <code>StringBuffer</code> object containing
497 * the reconstructed URL
498 *
499 */
500 public StringBuffer getRequestURL();
501
502
503 /**
504 *
505 * Returns the part of this request's URL that calls
506 * the servlet. This path starts with a "/" character
507 * and includes either the servlet name or a path to
508 * the servlet, but does not include any extra path
509 * information or a query string. Same as the value of
510 * the CGI variable SCRIPT_NAME.
511 *
512 * <p>This method will return an empty string ("") if the
513 * servlet used to process this request was matched using
514 * the "/*" pattern.
515 *
516 * @return a <code>String</code> containing
517 * the name or path of the servlet being
518 * called, as specified in the request URL,
519 * decoded, or an empty string if the servlet
520 * used to process the request is matched
521 * using the "/*" pattern.
522 *
523 */
524
525 public String getServletPath();
526
527
528
529
530 /**
531 *
532 * Returns the current <code>HttpSession</code>
533 * associated with this request or, if there is no
534 * current session and <code>create</code> is true, returns
535 * a new session.
536 *
537 * <p>If <code>create</code> is <code>false</code>
538 * and the request has no valid <code>HttpSession</code>,
539 * this method returns <code>null</code>.
540 *
541 * <p>To make sure the session is properly maintained,
542 * you must call this method before
543 * the response is committed. If the container is using cookies
544 * to maintain session integrity and is asked to create a new session
545 * when the response is committed, an IllegalStateException is thrown.
546 *
547 *
548 *
549 *
550 * @param create <code>true</code> to create
551 * a new session for this request if necessary;
552 * <code>false</code> to return <code>null</code>
553 * if there's no current session
554 *
555 *
556 * @return the <code>HttpSession</code> associated
557 * with this request or <code>null</code> if
558 * <code>create</code> is <code>false</code>
559 * and the request has no valid session
560 *
561 * @see #getSession()
562 *
563 *
564 */
565
566 public HttpSession getSession(boolean create);
567
568
569
570
571
572 /**
573 *
574 * Returns the current session associated with this request,
575 * or if the request does not have a session, creates one.
576 *
577 * @return the <code>HttpSession</code> associated
578 * with this request
579 *
580 * @see #getSession(boolean)
581 *
582 */
583
584 public HttpSession getSession();
585
586
587
588
589
590
591 /**
592 *
593 * Checks whether the requested session ID is still valid.
594 *
595 * @return <code>true</code> if this
596 * request has an id for a valid session
597 * in the current session context;
598 * <code>false</code> otherwise
599 *
600 * @see #getRequestedSessionId
601 * @see #getSession
602 * @see HttpSessionContext
603 *
604 */
605
606 public boolean isRequestedSessionIdValid();
607
608
609
610
611 /**
612 *
613 * Checks whether the requested session ID came in as a cookie.
614 *
615 * @return <code>true</code> if the session ID
616 * came in as a
617 * cookie; otherwise, <code>false</code>
618 *
619 *
620 * @see #getSession
621 *
622 */
623
624 public boolean isRequestedSessionIdFromCookie();
625
626
627
628
629 /**
630 *
631 * Checks whether the requested session ID came in as part of the
632 * request URL.
633 *
634 * @return <code>true</code> if the session ID
635 * came in as part of a URL; otherwise,
636 * <code>false</code>
637 *
638 *
639 * @see #getSession
640 *
641 */
642
643 public boolean isRequestedSessionIdFromURL();
644
645
646
647
648
649 /**
650 *
651 * @deprecated As of Version 2.1 of the Java Servlet
652 * API, use {@link #isRequestedSessionIdFromURL}
653 * instead.
654 *
655 */
656
657 public boolean isRequestedSessionIdFromUrl();
658
659
660
661 }