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