001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019 020 // 021 // This source code implements specifications defined by the Java 022 // Community Process. In order to remain compliant with the specification 023 // DO NOT add / change / or delete method signatures! 024 // 025 026 package javax.servlet; 027 028 import java.io.BufferedReader; 029 import java.io.IOException; 030 import java.util.Enumeration; 031 import java.util.Locale; 032 import java.util.Map; 033 034 035 /** 036 * Defines an object to provide client request information to a servlet. The 037 * servlet container creates a <code>ServletRequest</code> object and passes 038 * it as an argument to the servlet's <code>service</code> method. 039 * 040 * <p>A <code>ServletRequest</code> object provides data including 041 * parameter name and values, attributes, and an input stream. 042 * Interfaces that extend <code>ServletRequest</code> can provide 043 * additional protocol-specific data (for example, HTTP data is 044 * provided by {@link javax.servlet.http.HttpServletRequest}. 045 * 046 * @see javax.servlet.http.HttpServletRequest 047 * 048 * @version $Rev: 467553 $ $Date: 2006-10-25 06:01:51 +0200 (Mi, 25. Okt 2006) $ 049 */ 050 public interface ServletRequest { 051 /** 052 * Returns the value of the named attribute as an <code>Object</code>, 053 * or <code>null</code> if no attribute of the given name exists. 054 * 055 * <p> Attributes can be set two ways. The servlet container may set 056 * attributes to make available custom information about a request. 057 * For example, for requests made using HTTPS, the attribute 058 * <code>javax.servlet.request.X509Certificate</code> can be used to 059 * retrieve information on the certificate of the client. Attributes 060 * can also be set programatically using 061 * {@link ServletRequest#setAttribute}. This allows information to be 062 * embedded into a request before a {@link RequestDispatcher} call. 063 * 064 * <p>Attribute names should follow the same conventions as package 065 * names. This specification reserves names matching <code>java.*</code>, 066 * <code>javax.*</code>, and <code>sun.*</code>. 067 * 068 * @param name a <code>String</code> specifying the name of 069 * the attribute 070 * 071 * @return an <code>Object</code> containing the value 072 * of the attribute, or <code>null</code> if the attribute does not exist 073 */ 074 public Object getAttribute(String name); 075 076 /** 077 * Returns an <code>Enumeration</code> containing the 078 * names of the attributes available to this request. 079 * This method returns an empty <code>Enumeration</code> 080 * if the request has no attributes available to it. 081 * 082 * 083 * @return an <code>Enumeration</code> of strings 084 * containing the names of the request's attributes 085 */ 086 public Enumeration getAttributeNames(); 087 088 /** 089 * Returns the name of the character encoding used in the body of this 090 * request. This method returns <code>null</code> if the request 091 * does not specify a character encoding 092 * 093 * @return a <code>String</code> containing the name of 094 * the chararacter encoding, or <code>null</code> 095 * if the request does not specify a character encoding 096 */ 097 public String getCharacterEncoding(); 098 099 /** 100 * Overrides the name of the character encoding used in the body of this 101 * request. This method must be called prior to reading request parameters 102 * or reading input using getReader(). 103 * 104 * @param env a <code>String</code> containing the name of 105 * the chararacter encoding. 106 * 107 * @throws java.io.UnsupportedEncodingException if this is not a valid encoding 108 */ 109 public void setCharacterEncoding(String env) throws java.io.UnsupportedEncodingException; 110 111 /** 112 * Returns the length, in bytes, of the request body 113 * and made available by the input stream, or -1 if the 114 * length is not known. For HTTP servlets, same as the value 115 * of the CGI variable CONTENT_LENGTH. 116 * 117 * @return an integer containing the length of the 118 * request body or -1 if the length is not known 119 */ 120 public int getContentLength(); 121 122 /** 123 * Returns the MIME type of the body of the request, or 124 * <code>null</code> if the type is not known. For HTTP servlets, 125 * same as the value of the CGI variable CONTENT_TYPE. 126 * 127 * @return a <code>String</code> containing the name 128 * of the MIME type of the request, or null if the type is not known 129 */ 130 public String getContentType(); 131 132 /** 133 * Retrieves the body of the request as binary data using 134 * a {@link ServletInputStream}. Either this method or 135 * {@link #getReader} may be called to read the body, not both. 136 * 137 * @return a {@link ServletInputStream} object containing 138 * the body of the request 139 * 140 * @exception IllegalStateException if the {@link #getReader} method 141 * has already been called for this request 142 * 143 * @exception IOException if an input or output exception occurred 144 */ 145 public ServletInputStream getInputStream() throws IOException; 146 147 /** 148 * Returns the value of a request parameter as a <code>String</code>, 149 * or <code>null</code> if the parameter does not exist. Request parameters 150 * are extra information sent with the request. For HTTP servlets, 151 * parameters are contained in the query string or posted form data. 152 * 153 * <p>You should only use this method when you are sure the 154 * parameter has only one value. If the parameter might have 155 * more than one value, use {@link #getParameterValues}. 156 * 157 * <p>If you use this method with a multivalued 158 * parameter, the value returned is equal to the first value 159 * in the array returned by <code>getParameterValues</code>. 160 * 161 * <p>If the parameter data was sent in the request body, such as occurs 162 * with an HTTP POST request, then reading the body directly via {@link 163 * #getInputStream} or {@link #getReader} can interfere 164 * with the execution of this method. 165 * 166 * @param name a <code>String</code> specifying the 167 * name of the parameter 168 * 169 * @return a <code>String</code> representing the 170 * single value of the parameter 171 * 172 * @see #getParameterValues 173 */ 174 public String getParameter(String name); 175 176 /** 177 * Returns an <code>Enumeration</code> of <code>String</code> 178 * objects containing the names of the parameters contained 179 * in this request. If the request has 180 * no parameters, the method returns an 181 * empty <code>Enumeration</code>. 182 * 183 * @return an <code>Enumeration</code> of <code>String</code> 184 * objects, each <code>String</code> containing 185 * the name of a request parameter; or an 186 * empty <code>Enumeration</code> if the 187 * request has no parameters 188 */ 189 public Enumeration getParameterNames(); 190 191 /** 192 * Returns an array of <code>String</code> objects containing 193 * all of the values the given request parameter has, or 194 * <code>null</code> if the parameter does not exist. 195 * 196 * <p>If the parameter has a single value, the array has a length 197 * of 1. 198 * 199 * @param name a <code>String</code> containing the name of 200 * the parameter whose value is requested 201 * 202 * @return an array of <code>String</code> objects 203 * containing the parameter's values 204 * 205 * @see #getParameter 206 */ 207 public String[] getParameterValues(String name); 208 209 /** 210 * Returns a java.util.Map of the parameters of this request. 211 * Request parameters are extra information sent with the request. 212 * For HTTP servlets, parameters are contained in the query 213 * string or posted form data. 214 * 215 * @return an immutable java.util.Map containing parameter names as 216 * keys and parameter values as map values. The keys in the parameter 217 * map are of type String. The values in the parameter map are of type 218 * String array. 219 */ 220 public Map getParameterMap(); 221 222 /** 223 * Returns the name and version of the protocol the request uses 224 * in the form <i>protocol/majorVersion.minorVersion</i>, for 225 * example, HTTP/1.1. For HTTP servlets, the value 226 * returned is the same as the value of the CGI variable 227 * <code>SERVER_PROTOCOL</code>. 228 * 229 * @return a <code>String</code> containing the protocol 230 * name and version number 231 */ 232 public String getProtocol(); 233 234 /** 235 * Returns the name of the scheme used to make this request, 236 * for example, 237 * <code>http</code>, <code>https</code>, or <code>ftp</code>. 238 * Different schemes have different rules for constructing URLs, 239 * as noted in RFC 1738. 240 * 241 * @return a <code>String</code> containing the name 242 * of the scheme used to make this request 243 */ 244 public String getScheme(); 245 246 /** 247 * Returns the host name of the server to which the request was sent. 248 * It is the value of the part before ":" in the <code>Host</code> 249 * header, if any, or the resolved server name, or the server IP address. 250 * 251 * @return a <code>String</code> containing the name 252 * of the server 253 */ 254 public String getServerName(); 255 256 /** 257 * Returns the port number to which the request was sent. 258 * It is the value of the part after ":" in the <code>Host</code> 259 * header, if any, or the server port where the client connection 260 * was accepted on. 261 * 262 * @return an integer specifying the port number 263 */ 264 public int getServerPort(); 265 266 /** 267 * Retrieves the body of the request as character data using 268 * a <code>BufferedReader</code>. The reader translates the character 269 * data according to the character encoding used on the body. 270 * Either this method or {@link #getInputStream} may be called to read the 271 * body, not both. 272 * 273 * @return a <code>BufferedReader</code> containing the body of the request 274 * 275 * @exception UnsupportedEncodingException if the character set encoding 276 * used is not supported and the text cannot be decoded 277 * 278 * @exception IllegalStateException if {@link #getInputStream} method 279 * has been called on this request 280 * 281 * @exception IOException if an input or output exception occurred 282 * 283 * @see #getInputStream 284 */ 285 public BufferedReader getReader() throws IOException; 286 287 /** 288 * Returns the Internet Protocol (IP) address of the client 289 * or last proxy that sent the request. 290 * For HTTP servlets, same as the value of the 291 * CGI variable <code>REMOTE_ADDR</code>. 292 * 293 * @return a <code>String</code> containing the 294 * IP address of the client that sent the request 295 */ 296 public String getRemoteAddr(); 297 298 /** 299 * Returns the fully qualified name of the client 300 * or the last proxy that sent the request. 301 * If the engine cannot or chooses not to resolve the hostname 302 * (to improve performance), this method returns the dotted-string form of 303 * the IP address. For HTTP servlets, same as the value of the CGI variable 304 * <code>REMOTE_HOST</code>. 305 * 306 * @return a <code>String</code> containing the fully 307 * qualified name of the client 308 */ 309 public String getRemoteHost(); 310 311 /** 312 * Stores an attribute in this request. 313 * Attributes are reset between requests. This method is most 314 * often used in conjunction with {@link RequestDispatcher}. 315 * 316 * <p>Attribute names should follow the same conventions as 317 * package names. Names beginning with <code>java.*</code>, 318 * <code>javax.*</code>, and <code>com.sun.*</code>, are 319 * reserved for use by Sun Microsystems. 320 *<br> If the object passed in is null, the effect is the same as 321 * calling {@link #removeAttribute}. 322 * 323 * @param name a <code>String</code> specifying the name of the attribute 324 * 325 * @param o the <code>Object</code> to be stored 326 */ 327 public void setAttribute(String name, Object o); 328 329 /** 330 * Removes an attribute from this request. This method is not 331 * generally needed as attributes only persist as long as the request 332 * is being handled. 333 * 334 * <p>Attribute names should follow the same conventions as 335 * package names. Names beginning with <code>java.*</code>, 336 * <code>javax.*</code>, and <code>com.sun.*</code>, are 337 * reserved for use by Sun Microsystems. 338 * 339 * @param name a <code>String</code> specifying 340 * the name of the attribute to remove 341 */ 342 public void removeAttribute(String name); 343 344 /** 345 * Returns the preferred <code>Locale</code> that the client will 346 * accept content in, based on the Accept-Language header. 347 * If the client request doesn't provide an Accept-Language header, 348 * this method returns the default locale for the server. 349 * 350 * @return the preferred <code>Locale</code> for the client 351 */ 352 public Locale getLocale(); 353 354 /** 355 * Returns an <code>Enumeration</code> of <code>Locale</code> objects 356 * indicating, in decreasing order starting with the preferred locale, the 357 * locales that are acceptable to the client based on the Accept-Language 358 * header. 359 * If the client request doesn't provide an Accept-Language header, 360 * this method returns an <code>Enumeration</code> containing one 361 * <code>Locale</code>, the default locale for the server. 362 * 363 * @return an <code>Enumeration</code> of preferred 364 * <code>Locale</code> objects for the client 365 */ 366 public Enumeration getLocales(); 367 368 /** 369 * Returns a boolean indicating whether this request was made using a 370 * secure channel, such as HTTPS. 371 * 372 * @return a boolean indicating if the request was made using a 373 * secure channel 374 */ 375 public boolean isSecure(); 376 377 /** 378 * Returns a {@link RequestDispatcher} object that acts as a wrapper for 379 * the resource located at the given path. 380 * A <code>RequestDispatcher</code> object can be used to forward 381 * a request to the resource or to include the resource in a response. 382 * The resource can be dynamic or static. 383 * 384 * <p>The pathname specified may be relative, although it cannot extend 385 * outside the current servlet context. If the path begins with 386 * a "/" it is interpreted as relative to the current context root. 387 * This method returns <code>null</code> if the servlet container 388 * cannot return a <code>RequestDispatcher</code>. 389 * 390 * <p>The difference between this method and {@link 391 * ServletContext#getRequestDispatcher} is that this method can take a 392 * relative path. 393 * 394 * @param path a <code>String</code> specifying the pathname to the 395 * resource. If it is relative, it must be relative against the 396 * current servlet. 397 * 398 * @return a <code>RequestDispatcher</code> object that acts as a 399 * wrapper for the resource at the specified path, or <code>null</code> 400 * if the servlet container cannot return a 401 * <code>RequestDispatcher</code> 402 * 403 * @see RequestDispatcher 404 * @see ServletContext#getRequestDispatcher 405 */ 406 public RequestDispatcher getRequestDispatcher(String path); 407 408 /** 409 * @deprecated As of Version 2.1 of the Java Servlet API, 410 * use {@link ServletContext#getRealPath} instead. 411 */ 412 public String getRealPath(String path); 413 414 /** 415 * Returns the Internet Protocol (IP) source port of the client 416 * or last proxy that sent the request. 417 * 418 * @since Servlet 2.4 419 */ 420 public int getRemotePort(); 421 422 /** 423 * Returns the host name of the Internet Protocol (IP) interface on 424 * which the request was received. 425 * 426 * @return a <code>String</code> containing the host 427 * name of the IP on which the request was received. 428 * 429 * @since Servlet 2.4 430 */ 431 public String getLocalName(); 432 433 /** 434 * Returns the Internet Protocol (IP) address of the interface on 435 * which the request was received. 436 * 437 * @return a <code>String</code> containing the 438 * IP address on which the request was received. 439 * 440 * @since Servlet 2.4 441 */ 442 public String getLocalAddr(); 443 444 /** 445 * Returns the Internet Protocol (IP) port number of the interface 446 * on which the request was received. 447 * 448 * @return an integer specifying the port number 449 * 450 * @since Servlet 2.4 451 */ 452 public int getLocalPort(); 453 } 454