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 }