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