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; 21 22 import java.io.BufferedReader; 23 import java.io.IOException; 24 import java.util.Enumeration; 25 import java.util.Locale; 26 import java.util.Map; 27 28 29 30 /** 31 * Defines an object to provide client request information to a servlet. The 32 * servlet container creates a <code>ServletRequest</code> object and passes 33 * it as an argument to the servlet's <code>service</code> method. 34 * 35 * <p>A <code>ServletRequest</code> object provides data including 36 * parameter name and values, attributes, and an input stream. 37 * Interfaces that extend <code>ServletRequest</code> can provide 38 * additional protocol-specific data (for example, HTTP data is 39 * provided by {@link javax.servlet.http.HttpServletRequest}. 40 * 41 * @author Various 42 * @version $Version$ 43 * 44 * @see javax.servlet.http.HttpServletRequest 45 * 46 */ 47 48 public interface ServletRequest { 49 50 51 52 53 /** 54 * 55 * Returns the value of the named attribute as an <code>Object</code>, 56 * or <code>null</code> if no attribute of the given name exists. 57 * 58 * <p> Attributes can be set two ways. The servlet container may set 59 * attributes to make available custom information about a request. 60 * For example, for requests made using HTTPS, the attribute 61 * <code>javax.servlet.request.X509Certificate</code> can be used to 62 * retrieve information on the certificate of the client. Attributes 63 * can also be set programatically using 64 * {@link ServletRequest#setAttribute}. This allows information to be 65 * embedded into a request before a {@link RequestDispatcher} call. 66 * 67 * <p>Attribute names should follow the same conventions as package 68 * names. This specification reserves names matching <code>java.*</code>, 69 * <code>javax.*</code>, and <code>sun.*</code>. 70 * 71 * @param name a <code>String</code> specifying the name of 72 * the attribute 73 * 74 * @return an <code>Object</code> containing the value 75 * of the attribute, or <code>null</code> if 76 * the attribute does not exist 77 * 78 */ 79 80 public Object getAttribute(String name); 81 82 83 84 /** 85 * Returns an <code>Enumeration</code> containing the 86 * names of the attributes available to this request. 87 * This method returns an empty <code>Enumeration</code> 88 * if the request has no attributes available to it. 89 * 90 * 91 * @return an <code>Enumeration</code> of strings 92 * containing the names 93 * of the request's attributes 94 * 95 */ 96 97 public Enumeration getAttributeNames(); 98 99 100 101 102 /** 103 * Returns the name of the character encoding used in the body of this 104 * request. This method returns <code>null</code> if the request 105 * does not specify a character encoding 106 * 107 * 108 * @return a <code>String</code> containing the name of 109 * the character encoding, or <code>null</code> 110 * if the request does not specify a character encoding 111 * 112 */ 113 114 public String getCharacterEncoding(); 115 116 /** 117 * Overrides the name of the character encoding used in the body of this 118 * request. This method must be called prior to reading request parameters 119 * or reading input using getReader(). 120 * 121 * 122 * @param env a <code>String</code> containing the name of 123 * the character encoding. 124 * @throws java.io.UnsupportedEncodingException if this is not a valid encoding 125 */ 126 127 public void setCharacterEncoding(String env) throws java.io.UnsupportedEncodingException; 128 129 130 131 132 133 /** 134 * Returns the length, in bytes, of the request body 135 * and made available by the input stream, or -1 if the 136 * length is not known. For HTTP servlets, same as the value 137 * of the CGI variable CONTENT_LENGTH. 138 * 139 * @return an integer containing the length of the 140 * request body or -1 if the length is not known 141 * 142 */ 143 144 public int getContentLength(); 145 146 147 148 149 /** 150 * Returns the MIME type of the body of the request, or 151 * <code>null</code> if the type is not known. For HTTP servlets, 152 * same as the value of the CGI variable CONTENT_TYPE. 153 * 154 * @return a <code>String</code> containing the name 155 * of the MIME type of 156 * the request, or null if the type is not known 157 * 158 */ 159 160 public String getContentType(); 161 162 163 164 165 /** 166 * Retrieves the body of the request as binary data using 167 * a {@link ServletInputStream}. Either this method or 168 * {@link #getReader} may be called to read the body, not both. 169 * 170 * @return a {@link ServletInputStream} object containing 171 * the body of the request 172 * 173 * @exception IllegalStateException if the {@link #getReader} method 174 * has already been called for this request 175 * 176 * @exception IOException if an input or output exception occurred 177 * 178 */ 179 180 public ServletInputStream getInputStream() throws IOException; 181 182 183 184 185 /** 186 * Returns the value of a request parameter as a <code>String</code>, 187 * or <code>null</code> if the parameter does not exist. Request parameters 188 * are extra information sent with the request. For HTTP servlets, 189 * parameters are contained in the query string or posted form data. 190 * 191 * <p>You should only use this method when you are sure the 192 * parameter has only one value. If the parameter might have 193 * more than one value, use {@link #getParameterValues}. 194 * 195 * <p>If you use this method with a multivalued 196 * parameter, the value returned is equal to the first value 197 * in the array returned by <code>getParameterValues</code>. 198 * 199 * <p>If the parameter data was sent in the request body, such as occurs 200 * with an HTTP POST request, then reading the body directly via {@link 201 * #getInputStream} or {@link #getReader} can interfere 202 * with the execution of this method. 203 * 204 * @param name a <code>String</code> specifying the 205 * name of the parameter 206 * 207 * @return a <code>String</code> representing the 208 * single value of the parameter 209 * 210 * @see #getParameterValues 211 * 212 */ 213 214 public String getParameter(String name); 215 216 217 218 219 /** 220 * 221 * Returns an <code>Enumeration</code> of <code>String</code> 222 * objects containing the names of the parameters contained 223 * in this request. If the request has 224 * no parameters, the method returns an 225 * empty <code>Enumeration</code>. 226 * 227 * @return an <code>Enumeration</code> of <code>String</code> 228 * objects, each <code>String</code> containing 229 * the name of a request parameter; or an 230 * empty <code>Enumeration</code> if the 231 * request has no parameters 232 * 233 */ 234 235 public Enumeration getParameterNames(); 236 237 238 239 240 /** 241 * Returns an array of <code>String</code> objects containing 242 * all of the values the given request parameter has, or 243 * <code>null</code> if the parameter does not exist. 244 * 245 * <p>If the parameter has a single value, the array has a length 246 * of 1. 247 * 248 * @param name a <code>String</code> containing the name of 249 * the parameter whose value is requested 250 * 251 * @return an array of <code>String</code> objects 252 * containing the parameter's values 253 * 254 * @see #getParameter 255 * 256 */ 257 258 public String[] getParameterValues(String name); 259 260 /** Returns a java.util.Map of the parameters of this request. 261 * Request parameters 262 * are extra information sent with the request. For HTTP servlets, 263 * parameters are contained in the query string or posted form data. 264 * 265 * @return an immutable java.util.Map containing parameter names as 266 * keys and parameter values as map values. The keys in the parameter 267 * map are of type String. The values in the parameter map are of type 268 * String array. 269 * 270 */ 271 272 public Map getParameterMap(); 273 274 275 276 /** 277 * Returns the name and version of the protocol the request uses 278 * in the form <i>protocol/majorVersion.minorVersion</i>, for 279 * example, HTTP/1.1. For HTTP servlets, the value 280 * returned is the same as the value of the CGI variable 281 * <code>SERVER_PROTOCOL</code>. 282 * 283 * @return a <code>String</code> containing the protocol 284 * name and version number 285 * 286 */ 287 288 public String getProtocol(); 289 290 291 292 293 /** 294 * Returns the name of the scheme used to make this request, 295 * for example, 296 * <code>http</code>, <code>https</code>, or <code>ftp</code>. 297 * Different schemes have different rules for constructing URLs, 298 * as noted in RFC 1738. 299 * 300 * @return a <code>String</code> containing the name 301 * of the scheme used to make this request 302 * 303 */ 304 305 public String getScheme(); 306 307 308 309 310 /** 311 * Returns the host name of the server to which the request was sent. 312 * It is the value of the part before ":" in the <code>Host</code> 313 * header value, if any, or the resolved server name, or the server IP address. 314 * 315 * @return a <code>String</code> containing the name 316 * of the server 317 */ 318 319 public String getServerName(); 320 321 322 323 324 /** 325 * Returns the port number to which the request was sent. 326 * It is the value of the part after ":" in the <code>Host</code> 327 * header value, if any, or the server port where the client connection 328 * was accepted on. 329 * 330 * @return an integer specifying the port number 331 * 332 */ 333 334 public int getServerPort(); 335 336 337 338 /** 339 * Retrieves the body of the request as character data using 340 * a <code>BufferedReader</code>. The reader translates the character 341 * data according to the character encoding used on the body. 342 * Either this method or {@link #getInputStream} may be called to read the 343 * body, not both. 344 * 345 * 346 * @return a <code>BufferedReader</code> 347 * containing the body of the request 348 * 349 * @exception UnsupportedEncodingException if the character set encoding 350 * used is not supported and the 351 * text cannot be decoded 352 * 353 * @exception IllegalStateException if {@link #getInputStream} method 354 * has been called on this request 355 * 356 * @exception IOException if an input or output exception occurred 357 * 358 * @see #getInputStream 359 * 360 */ 361 362 public BufferedReader getReader() throws IOException; 363 364 365 366 367 /** 368 * Returns the Internet Protocol (IP) address of the client 369 * or last proxy that sent the request. 370 * For HTTP servlets, same as the value of the 371 * CGI variable <code>REMOTE_ADDR</code>. 372 * 373 * @return a <code>String</code> containing the 374 * IP address of the client that sent the request 375 * 376 */ 377 378 public String getRemoteAddr(); 379 380 381 382 383 /** 384 * Returns the fully qualified name of the client 385 * or the last proxy that sent the request. 386 * If the engine cannot or chooses not to resolve the hostname 387 * (to improve performance), this method returns the dotted-string form of 388 * the IP address. For HTTP servlets, same as the value of the CGI variable 389 * <code>REMOTE_HOST</code>. 390 * 391 * @return a <code>String</code> containing the fully 392 * qualified name of the client 393 * 394 */ 395 396 public String getRemoteHost(); 397 398 399 400 401 /** 402 * 403 * Stores an attribute in this request. 404 * Attributes are reset between requests. This method is most 405 * often used in conjunction with {@link RequestDispatcher}. 406 * 407 * <p>Attribute names should follow the same conventions as 408 * package names. Names beginning with <code>java.*</code>, 409 * <code>javax.*</code>, and <code>com.sun.*</code>, are 410 * reserved for use by Sun Microsystems. 411 *<br> If the object passed in is null, the effect is the same as 412 * calling {@link #removeAttribute}. 413 * <br> It is warned that when the request is dispatched from the 414 * servlet resides in a different web application by 415 * <code>RequestDispatcher</code>, the object set by this method 416 * may not be correctly retrieved in the caller servlet. 417 * 418 * 419 * @param name a <code>String</code> specifying 420 * the name of the attribute 421 * 422 * @param o the <code>Object</code> to be stored 423 * 424 */ 425 426 public void setAttribute(String name, Object o); 427 428 429 430 431 /** 432 * 433 * Removes an attribute from this request. This method is not 434 * generally needed as attributes only persist as long as the request 435 * is being handled. 436 * 437 * <p>Attribute names should follow the same conventions as 438 * package names. Names beginning with <code>java.*</code>, 439 * <code>javax.*</code>, and <code>com.sun.*</code>, are 440 * reserved for use by Sun Microsystems. 441 * 442 * 443 * @param name a <code>String</code> specifying 444 * the name of the attribute to remove 445 * 446 */ 447 448 public void removeAttribute(String name); 449 450 451 452 453 /** 454 * 455 * Returns the preferred <code>Locale</code> that the client will 456 * accept content in, based on the Accept-Language header. 457 * If the client request doesn't provide an Accept-Language header, 458 * this method returns the default locale for the server. 459 * 460 * 461 * @return the preferred <code>Locale</code> for the client 462 * 463 */ 464 465 public Locale getLocale(); 466 467 468 469 470 /** 471 * 472 * Returns an <code>Enumeration</code> of <code>Locale</code> objects 473 * indicating, in decreasing order starting with the preferred locale, the 474 * locales that are acceptable to the client based on the Accept-Language 475 * header. 476 * If the client request doesn't provide an Accept-Language header, 477 * this method returns an <code>Enumeration</code> containing one 478 * <code>Locale</code>, the default locale for the server. 479 * 480 * 481 * @return an <code>Enumeration</code> of preferred 482 * <code>Locale</code> objects for the client 483 * 484 */ 485 486 public Enumeration getLocales(); 487 488 489 490 491 /** 492 * 493 * Returns a boolean indicating whether this request was made using a 494 * secure channel, such as HTTPS. 495 * 496 * 497 * @return a boolean indicating if the request was made using a 498 * secure channel 499 * 500 */ 501 502 public boolean isSecure(); 503 504 505 506 507 /** 508 * 509 * Returns a {@link RequestDispatcher} object that acts as a wrapper for 510 * the resource located at the given path. 511 * A <code>RequestDispatcher</code> object can be used to forward 512 * a request to the resource or to include the resource in a response. 513 * The resource can be dynamic or static. 514 * 515 * <p>The pathname specified may be relative, although it cannot extend 516 * outside the current servlet context. If the path begins with 517 * a "/" it is interpreted as relative to the current context root. 518 * This method returns <code>null</code> if the servlet container 519 * cannot return a <code>RequestDispatcher</code>. 520 * 521 * <p>The difference between this method and {@link 522 * ServletContext#getRequestDispatcher} is that this method can take a 523 * relative path. 524 * 525 * @param path a <code>String</code> specifying the pathname 526 * to the resource. If it is relative, it must be 527 * relative against the current servlet. 528 * 529 * @return a <code>RequestDispatcher</code> object 530 * that acts as a wrapper for the resource 531 * at the specified path, or <code>null</code> 532 * if the servlet container cannot return a 533 * <code>RequestDispatcher</code> 534 * 535 * @see RequestDispatcher 536 * @see ServletContext#getRequestDispatcher 537 * 538 */ 539 540 public RequestDispatcher getRequestDispatcher(String path); 541 542 543 544 545 /** 546 * 547 * @deprecated As of Version 2.1 of the Java Servlet API, 548 * use {@link ServletContext#getRealPath} instead. 549 * 550 */ 551 552 public String getRealPath(String path); 553 554 555 /** 556 * Returns the Internet Protocol (IP) source port of the client 557 * or last proxy that sent the request. 558 * 559 * @return an integer specifying the port number 560 * 561 * @since 2.4 562 */ 563 public int getRemotePort(); 564 565 566 /** 567 * Returns the host name of the Internet Protocol (IP) interface on 568 * which the request was received. 569 * 570 * @return a <code>String</code> containing the host 571 * name of the IP on which the request was received. 572 * 573 * @since 2.4 574 */ 575 public String getLocalName(); 576 577 /** 578 * Returns the Internet Protocol (IP) address of the interface on 579 * which the request was received. 580 * 581 * @return a <code>String</code> containing the 582 * IP address on which the request was received. 583 * 584 * @since 2.4 585 * 586 */ 587 public String getLocalAddr(); 588 589 590 /** 591 * Returns the Internet Protocol (IP) port number of the interface 592 * on which the request was received. 593 * 594 * @return an integer specifying the port number 595 * 596 * @since 2.4 597 */ 598 public int getLocalPort(); 599 600 601 602 /** 603 * Suspend the processing of the request and associated {@link ServletResponse}. 604 * 605 * <p>After this method has been called, the lifecycle of the request 606 * will be extended beyond the return to the container from the 607 * {@link Servlet#service(ServletRequest, ServletResponse)} method and 608 * {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)} calls. If a 609 * request is suspended, then the container will not commit the associated response 610 * when the call to the filter chain and/or servlet service method returns to the 611 * container. Any exceptions thrown to the container by a filter chain and/or 612 * servlet for a suspended requests are silently ignored.</p> 613 * 614 * <p>When the thread calling the filter chain and/or servlet has returned to the 615 * container with a suspended request, the thread is freed for other tasks and 616 * the request is held pending either: <ul> 617 * <li>a call to {@link ServletRequest#resume()}.</li> 618 * <li>a call to {@link ServletRequest#complete()}.</li> 619 * <li>the passed or default timeout expires.</li> 620 * <li>there is IO activity on the connection that received the request, such 621 * as the close of the connection or the receipt of a pipelined request. 622 * </ul> 623 * <p>After any of the events listed above, the suspended request will be 624 * redispatched via the filter and servlet processing. 625 * </p> 626 * 627 * <p>If a request is already suspended, any subsequent calls to suspend will set 628 * the timeout to the minimum of the previous timeout and the newly passed 629 * timeout</p> 630 * 631 * <p>Suspend may only be called by a thread that is within the service calling 632 * stack of {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)} 633 * and/or {@link Servlet#service(ServletRequest, ServletResponse)}. A request that has 634 * been dispatched for error handling may not be suspended. 635 * </p> 636 * 637 * @see {@link #resume()} 638 * @see {@link #complete()} 639 * @since 3.0 640 * 641 * @param timeoutMs The time in milliseconds to wait before retrying this request. 642 * 643 * @exception IllegalStateException If the calling thread is not within the calling 644 * stack of {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)} 645 * and/or {@link Servlet#service(ServletRequest, ServletResponse)} or if the request 646 * has been dispatched for error handling. 647 */ 648 void suspend(long timeoutMs); 649 650 /** 651 * Suspend the processing of the request and associated {@link ServletResponse}. 652 * 653 * <p>Acts as a call to {@link #suspend(long)} but with a container supplied 654 * timeout. The timeout the container will use may be obtained or set as a Long 655 * context attribute with the name "javax.servlet.suspendTimeoutMs"</p> 656 * @see suspend(long) 657 */ 658 void suspend(); 659 660 /** 661 * Resume a suspended request. 662 * 663 * <p>This method can be called by any thread that has been passed a reference to 664 * a suspended request. When called the request is redispatched to the normal filter 665 * chain and servlet processing.</p> 666 * 667 * <p>If resume is called before a suspended request is returned to the container 668 * (ie the thread that called {@link #suspend(long)} is still within the filter 669 * chain and/or servlet service method), then the resume does not take effect until 670 * the call to the filter chain and/or servlet returns to the container. In this 671 * case both {@link #isSuspended()} and {@link isResumed()} return true.</p> 672 * 673 * <p>Multiple calls to resume are ignored</p> 674 * 675 * @see {@link #suspend()} 676 * @since 3.0 677 * @exception IllegalStateException if the request is not suspended. 678 * 679 */ 680 void resume(); 681 682 /** 683 * Complete a suspended request. 684 * 685 * <p>This method can be called by any thread that has been passed a reference to 686 * a suspended request. When a request is completed, the associated response object 687 * commited and flushed. The request is not redispatched.</p> 688 * 689 * <p>If complete is called before a suspended request is returned to the container 690 * (ie the thread that called {@link #suspend(long)} is still within the filter 691 * chain and/or servlet service method), then the complete does not take effect until 692 * the call to the filter chain and/or servlet returns to the container. In this 693 * case both {@link #isSuspended()} and {@link isResumed()} return true.</p> 694 * 695 * <p>Once complete has been called and any thread calling the filter chain and/or 696 * servlet chain has returned to the container, the request lifecycle is complete. 697 * The container is able to recycle request objects, so it is not valid hold a request 698 * reference after the end of the life cycle or to call any request methods. 699 * 700 * @see {@link #suspend()} 701 * @since 3.0 702 * @exception IllegalStateException if the request is not suspended. 703 * 704 */ 705 void complete() throws IOException; 706 707 /** 708 * @return true after {@link #suspend(long)} has been called and before the request 709 * has been resumed, completed, timed out or reactived due to IO activity. 710 * @since 3.0 711 */ 712 boolean isSuspended(); 713 714 /** 715 * @return true if the request has been redispatched by a call to {@link #resume()}. Returns false after any subsequent call to suspend 716 * @since 3.0 717 */ 718 boolean isResumed(); 719 720 /** 721 * @return true after a request has been redispatched as the result of a timeout. 722 * Returns false after any subsequent call to suspend. 723 * @since 3.0 724 */ 725 boolean isTimeout(); 726 727 /** 728 * @return true while the request is within the initial dispatch to the filter chain 729 * and/or servlet. Will return false once the calling thread has returned to the 730 * container after suspend has been called and during any subsequent redispatch. 731 * @since 3.0 732 */ 733 boolean isInitial(); 734 735 /** 736 * Gets the servlet response with which this servlet request has been 737 * associated. 738 * 739 * @return the servlet response with which this servlet request has been 740 * associated 741 * 742 * @since 3.0 743 */ 744 ServletResponse getServletResponse(); 745 746 /** 747 * Gets the servlet context to which this servlet request was last 748 * dispatched. 749 * 750 * @return the servlet context to which this servlet request was last 751 * dispatched 752 * 753 * @since 3.0 754 */ 755 ServletContext getServletContext(); 756 757 } 758