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 package javax.servlet; 29 30 import java.io.BufferedReader; 31 import java.io.IOException; 32 import java.util.Enumeration; 33 import java.util.Locale; 34 import java.util.Map; 35 36 37 38 /** 39 * Defines an object to provide client request information to a servlet. The 40 * servlet container creates a <code>ServletRequest</code> object and passes 41 * it as an argument to the servlet's <code>service</code> method. 42 * 43 * <p>A <code>ServletRequest</code> object provides data including 44 * parameter name and values, attributes, and an input stream. 45 * Interfaces that extend <code>ServletRequest</code> can provide 46 * additional protocol-specific data (for example, HTTP data is 47 * provided by {@link javax.servlet.http.HttpServletRequest}. 48 * 49 * @author Various 50 * 51 * @see javax.servlet.http.HttpServletRequest 52 * 53 */ 54 55 public interface ServletRequest { 56 57 58 59 60 /** 61 * 62 * Returns the value of the named attribute as an <code>Object</code>, 63 * or <code>null</code> if no attribute of the given name exists. 64 * 65 * <p> Attributes can be set two ways. The servlet container may set 66 * attributes to make available custom information about a request. 67 * For example, for requests made using HTTPS, the attribute 68 * <code>javax.servlet.request.X509Certificate</code> can be used to 69 * retrieve information on the certificate of the client. Attributes 70 * can also be set programatically using 71 * {@link ServletRequest#setAttribute}. This allows information to be 72 * embedded into a request before a {@link RequestDispatcher} call. 73 * 74 * <p>Attribute names should follow the same conventions as package 75 * names. This specification reserves names matching <code>java.*</code>, 76 * <code>javax.*</code>, and <code>sun.*</code>. 77 * 78 * @param name a <code>String</code> specifying the name of 79 * the attribute 80 * 81 * @return an <code>Object</code> containing the value 82 * of the attribute, or <code>null</code> if 83 * the attribute does not exist 84 * 85 */ 86 getAttribute(String name)87 public Object getAttribute(String name); 88 89 90 91 /** 92 * Returns an <code>Enumeration</code> containing the 93 * names of the attributes available to this request. 94 * This method returns an empty <code>Enumeration</code> 95 * if the request has no attributes available to it. 96 * 97 * 98 * @return an <code>Enumeration</code> of strings 99 * containing the names 100 * of the request's attributes 101 * 102 */ 103 getAttributeNames()104 public Enumeration getAttributeNames(); 105 106 107 108 109 /** 110 * Returns the name of the character encoding used in the body of this 111 * request. This method returns <code>null</code> if the request 112 * does not specify a character encoding 113 * 114 * 115 * @return a <code>String</code> containing the name of 116 * the character encoding, or <code>null</code> 117 * if the request does not specify a character encoding 118 * 119 */ 120 getCharacterEncoding()121 public String getCharacterEncoding(); 122 123 124 /** 125 * Overrides the name of the character encoding used in the body of this 126 * request. This method must be called prior to reading request parameters 127 * or reading input using getReader(). Otherwise, it has no effect. 128 * 129 * @param env <code>String</code> containing the name of 130 * the character encoding. 131 * @throws java.io.UnsupportedEncodingException if this 132 * ServletRequest is still in a state where a 133 * character encoding may be set, but the specified 134 * encoding is invalid 135 */ setCharacterEncoding(String env)136 public void setCharacterEncoding(String env) throws java.io.UnsupportedEncodingException; 137 138 139 140 141 142 /** 143 * Returns the length, in bytes, of the request body 144 * and made available by the input stream, or -1 if the 145 * length is not known. For HTTP servlets, same as the value 146 * of the CGI variable CONTENT_LENGTH. 147 * 148 * @return an integer containing the length of the 149 * request body or -1 if the length is not known 150 * 151 */ 152 getContentLength()153 public int getContentLength(); 154 155 156 157 158 /** 159 * Returns the MIME type of the body of the request, or 160 * <code>null</code> if the type is not known. For HTTP servlets, 161 * same as the value of the CGI variable CONTENT_TYPE. 162 * 163 * @return a <code>String</code> containing the name 164 * of the MIME type of 165 * the request, or null if the type is not known 166 * 167 */ 168 getContentType()169 public String getContentType(); 170 171 172 173 174 /** 175 * Retrieves the body of the request as binary data using 176 * a {@link ServletInputStream}. Either this method or 177 * {@link #getReader} may be called to read the body, not both. 178 * 179 * @return a {@link ServletInputStream} object containing 180 * the body of the request 181 * 182 * @exception IllegalStateException if the {@link #getReader} method 183 * has already been called for this request 184 * 185 * @exception IOException if an input or output exception occurred 186 * 187 */ 188 getInputStream()189 public ServletInputStream getInputStream() throws IOException; 190 191 192 193 194 /** 195 * Returns the value of a request parameter as a <code>String</code>, 196 * or <code>null</code> if the parameter does not exist. Request parameters 197 * are extra information sent with the request. For HTTP servlets, 198 * parameters are contained in the query string or posted form data. 199 * 200 * <p>You should only use this method when you are sure the 201 * parameter has only one value. If the parameter might have 202 * more than one value, use {@link #getParameterValues}. 203 * 204 * <p>If you use this method with a multivalued 205 * parameter, the value returned is equal to the first value 206 * in the array returned by <code>getParameterValues</code>. 207 * 208 * <p>If the parameter data was sent in the request body, such as occurs 209 * with an HTTP POST request, then reading the body directly via {@link 210 * #getInputStream} or {@link #getReader} can interfere 211 * with the execution of this method. 212 * 213 * @param name a <code>String</code> specifying the 214 * name of the parameter 215 * 216 * @return a <code>String</code> representing the 217 * single value of the parameter 218 * 219 * @see #getParameterValues 220 * 221 */ 222 getParameter(String name)223 public String getParameter(String name); 224 225 226 227 228 /** 229 * 230 * Returns an <code>Enumeration</code> of <code>String</code> 231 * objects containing the names of the parameters contained 232 * in this request. If the request has 233 * no parameters, the method returns an 234 * empty <code>Enumeration</code>. 235 * 236 * @return an <code>Enumeration</code> of <code>String</code> 237 * objects, each <code>String</code> containing 238 * the name of a request parameter; or an 239 * empty <code>Enumeration</code> if the 240 * request has no parameters 241 * 242 */ 243 getParameterNames()244 public Enumeration getParameterNames(); 245 246 247 248 249 /** 250 * Returns an array of <code>String</code> objects containing 251 * all of the values the given request parameter has, or 252 * <code>null</code> if the parameter does not exist. 253 * 254 * <p>If the parameter has a single value, the array has a length 255 * of 1. 256 * 257 * @param name a <code>String</code> containing the name of 258 * the parameter whose value is requested 259 * 260 * @return an array of <code>String</code> objects 261 * containing the parameter's values 262 * 263 * @see #getParameter 264 * 265 */ 266 getParameterValues(String name)267 public String[] getParameterValues(String name); 268 269 /** Returns a java.util.Map of the parameters of this request. 270 * Request parameters 271 * are extra information sent with the request. For HTTP servlets, 272 * parameters are contained in the query string or posted form data. 273 * 274 * @return an immutable java.util.Map containing parameter names as 275 * keys and parameter values as map values. The keys in the parameter 276 * map are of type String. The values in the parameter map are of type 277 * String array. 278 * 279 */ 280 getParameterMap()281 public Map getParameterMap(); 282 283 284 285 /** 286 * Returns the name and version of the protocol the request uses 287 * in the form <i>protocol/majorVersion.minorVersion</i>, for 288 * example, HTTP/1.1. For HTTP servlets, the value 289 * returned is the same as the value of the CGI variable 290 * <code>SERVER_PROTOCOL</code>. 291 * 292 * @return a <code>String</code> containing the protocol 293 * name and version number 294 * 295 */ 296 getProtocol()297 public String getProtocol(); 298 299 300 301 302 /** 303 * Returns the name of the scheme used to make this request, 304 * for example, 305 * <code>http</code>, <code>https</code>, or <code>ftp</code>. 306 * Different schemes have different rules for constructing URLs, 307 * as noted in RFC 1738. 308 * 309 * @return a <code>String</code> containing the name 310 * of the scheme used to make this request 311 * 312 */ 313 getScheme()314 public String getScheme(); 315 316 317 318 319 /** 320 * Returns the host name of the server to which the request was sent. 321 * It is the value of the part before ":" in the <code>Host</code> 322 * header value, if any, or the resolved server name, or the server IP address. 323 * 324 * @return a <code>String</code> containing the name 325 * of the server 326 */ 327 getServerName()328 public String getServerName(); 329 330 331 332 333 /** 334 * Returns the port number to which the request was sent. 335 * It is the value of the part after ":" in the <code>Host</code> 336 * header value, if any, or the server port where the client connection 337 * was accepted on. 338 * 339 * @return an integer specifying the port number 340 * 341 */ 342 getServerPort()343 public int getServerPort(); 344 345 346 347 /** 348 * Retrieves the body of the request as character data using 349 * a <code>BufferedReader</code>. The reader translates the character 350 * data according to the character encoding used on the body. 351 * Either this method or {@link #getInputStream} may be called to read the 352 * body, not both. 353 * 354 * 355 * @return a <code>BufferedReader</code> 356 * containing the body of the request 357 * 358 * @exception UnsupportedEncodingException if the character set encoding 359 * used is not supported and the 360 * text cannot be decoded 361 * 362 * @exception IllegalStateException if {@link #getInputStream} method 363 * has been called on this request 364 * 365 * @exception IOException if an input or output exception occurred 366 * 367 * @see #getInputStream 368 * 369 */ 370 getReader()371 public BufferedReader getReader() throws IOException; 372 373 374 375 376 /** 377 * Returns the Internet Protocol (IP) address of the client 378 * or last proxy that sent the request. 379 * For HTTP servlets, same as the value of the 380 * CGI variable <code>REMOTE_ADDR</code>. 381 * 382 * @return a <code>String</code> containing the 383 * IP address of the client that sent the request 384 * 385 */ 386 getRemoteAddr()387 public String getRemoteAddr(); 388 389 390 391 392 /** 393 * Returns the fully qualified name of the client 394 * or the last proxy that sent the request. 395 * If the engine cannot or chooses not to resolve the hostname 396 * (to improve performance), this method returns the dotted-string form of 397 * the IP address. For HTTP servlets, same as the value of the CGI variable 398 * <code>REMOTE_HOST</code>. 399 * 400 * @return a <code>String</code> containing the fully 401 * qualified name of the client 402 * 403 */ 404 getRemoteHost()405 public String getRemoteHost(); 406 407 408 409 410 /** 411 * 412 * Stores an attribute in this request. 413 * Attributes are reset between requests. This method is most 414 * often used in conjunction with {@link RequestDispatcher}. 415 * 416 * <p>Attribute names should follow the same conventions as 417 * package names. Names beginning with <code>java.*</code>, 418 * <code>javax.*</code>, and <code>com.sun.*</code>, are 419 * reserved for use by Sun Microsystems. 420 *<br> If the object passed in is null, the effect is the same as 421 * calling {@link #removeAttribute}. 422 * <br> It is warned that when the request is dispatched from the 423 * servlet resides in a different web application by 424 * <code>RequestDispatcher</code>, the object set by this method 425 * may not be correctly retrieved in the caller servlet. 426 * 427 * 428 * @param name a <code>String</code> specifying 429 * the name of the attribute 430 * 431 * @param o the <code>Object</code> to be stored 432 * 433 */ 434 setAttribute(String name, Object o)435 public void setAttribute(String name, Object o); 436 437 438 439 440 /** 441 * 442 * Removes an attribute from this request. This method is not 443 * generally needed as attributes only persist as long as the request 444 * is being handled. 445 * 446 * <p>Attribute names should follow the same conventions as 447 * package names. Names beginning with <code>java.*</code>, 448 * <code>javax.*</code>, and <code>com.sun.*</code>, are 449 * reserved for use by Sun Microsystems. 450 * 451 * 452 * @param name a <code>String</code> specifying 453 * the name of the attribute to remove 454 * 455 */ 456 removeAttribute(String name)457 public void removeAttribute(String name); 458 459 460 461 462 /** 463 * 464 * Returns the preferred <code>Locale</code> that the client will 465 * accept content in, based on the Accept-Language header. 466 * If the client request doesn't provide an Accept-Language header, 467 * this method returns the default locale for the server. 468 * 469 * 470 * @return the preferred <code>Locale</code> for the client 471 * 472 */ 473 getLocale()474 public Locale getLocale(); 475 476 477 478 479 /** 480 * 481 * Returns an <code>Enumeration</code> of <code>Locale</code> objects 482 * indicating, in decreasing order starting with the preferred locale, the 483 * locales that are acceptable to the client based on the Accept-Language 484 * header. 485 * If the client request doesn't provide an Accept-Language header, 486 * this method returns an <code>Enumeration</code> containing one 487 * <code>Locale</code>, the default locale for the server. 488 * 489 * 490 * @return an <code>Enumeration</code> of preferred 491 * <code>Locale</code> objects for the client 492 * 493 */ 494 getLocales()495 public Enumeration getLocales(); 496 497 498 499 500 /** 501 * 502 * Returns a boolean indicating whether this request was made using a 503 * secure channel, such as HTTPS. 504 * 505 * 506 * @return a boolean indicating if the request was made using a 507 * secure channel 508 * 509 */ 510 isSecure()511 public boolean isSecure(); 512 513 514 515 516 /** 517 * 518 * Returns a {@link RequestDispatcher} object that acts as a wrapper for 519 * the resource located at the given path. 520 * A <code>RequestDispatcher</code> object can be used to forward 521 * a request to the resource or to include the resource in a response. 522 * The resource can be dynamic or static. 523 * 524 * <p>The pathname specified may be relative, although it cannot extend 525 * outside the current servlet context. If the path begins with 526 * a "/" it is interpreted as relative to the current context root. 527 * This method returns <code>null</code> if the servlet container 528 * cannot return a <code>RequestDispatcher</code>. 529 * 530 * <p>The difference between this method and {@link 531 * ServletContext#getRequestDispatcher} is that this method can take a 532 * relative path. 533 * 534 * @param path a <code>String</code> specifying the pathname 535 * to the resource. If it is relative, it must be 536 * relative against the current servlet. 537 * 538 * @return a <code>RequestDispatcher</code> object 539 * that acts as a wrapper for the resource 540 * at the specified path, or <code>null</code> 541 * if the servlet container cannot return a 542 * <code>RequestDispatcher</code> 543 * 544 * @see RequestDispatcher 545 * @see ServletContext#getRequestDispatcher 546 * 547 */ 548 getRequestDispatcher(String path)549 public RequestDispatcher getRequestDispatcher(String path); 550 551 552 553 554 /** 555 * 556 * @deprecated As of Version 2.1 of the Java Servlet API, 557 * use {@link ServletContext#getRealPath} instead. 558 * 559 */ 560 getRealPath(String path)561 public String getRealPath(String path); 562 563 564 /** 565 * Returns the Internet Protocol (IP) source port of the client 566 * or last proxy that sent the request. 567 * 568 * @return an integer specifying the port number 569 * 570 * @since 2.4 571 */ getRemotePort()572 public int getRemotePort(); 573 574 575 /** 576 * Returns the host name of the Internet Protocol (IP) interface on 577 * which the request was received. 578 * 579 * @return a <code>String</code> containing the host 580 * name of the IP on which the request was received. 581 * 582 * @since 2.4 583 */ getLocalName()584 public String getLocalName(); 585 586 /** 587 * Returns the Internet Protocol (IP) address of the interface on 588 * which the request was received. 589 * 590 * @return a <code>String</code> containing the 591 * IP address on which the request was received. 592 * 593 * @since 2.4 594 * 595 */ getLocalAddr()596 public String getLocalAddr(); 597 598 599 /** 600 * Returns the Internet Protocol (IP) port number of the interface 601 * on which the request was received. 602 * 603 * @return an integer specifying the port number 604 * 605 * @since 2.4 606 */ getLocalPort()607 public int getLocalPort(); 608 609 } 610 611