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