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