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.http; 027 028 import java.util.Enumeration; 029 import javax.servlet.ServletRequest; 030 031 /** 032 * Extends the {@link javax.servlet.ServletRequest} interface 033 * to provide request information for HTTP servlets. 034 * 035 * <p>The servlet container creates an <code>HttpServletRequest</code> 036 * object and passes it as an argument to the servlet's service 037 * methods (<code>doGet</code>, <code>doPost</code>, etc). 038 * 039 * @version $Rev: 467553 $ $Date: 2006-10-25 06:01:51 +0200 (Mi, 25. Okt 2006) $ 040 */ 041 public interface HttpServletRequest extends ServletRequest { 042 043 /** 044 * String identifier for Basic authentication. Value "BASIC" 045 */ 046 public static final String BASIC_AUTH = "BASIC"; 047 048 /** 049 * String identifier for Form authentication. Value "FORM" 050 */ 051 public static final String FORM_AUTH = "FORM"; 052 053 /** 054 * String identifier for Client Certificate authentication. Value "CLIENT_CERT" 055 */ 056 public static final String CLIENT_CERT_AUTH = "CLIENT_CERT"; 057 058 /** 059 * String identifier for Digest authentication. Value "DIGEST" 060 */ 061 public static final String DIGEST_AUTH = "DIGEST"; 062 063 /** 064 * Returns the name of the authentication scheme used to protect 065 * the servlet. All servlet containers support basic, form and client 066 * certificate authentication, and may additionally support digest 067 * authentication. 068 * If the servlet is not authenticated <code>null</code> is returned. 069 * 070 * <p>Same as the value of the CGI variable AUTH_TYPE. 071 * 072 * @return one of the static members BASIC_AUTH, FORM_AUTH, CLIENT_CERT_AUTH, 073 * DIGEST_AUTH (suitable for == comparison) or the container-specific string 074 * indicating the authentication scheme, or <code>null</code> if the request 075 * was not authenticated. 076 */ 077 public String getAuthType(); 078 079 /** 080 * Returns an array containing all of the <code>Cookie</code> 081 * objects the client sent with this request. 082 * This method returns <code>null</code> if no cookies were sent. 083 * 084 * @return an array of all the <code>Cookies</code> 085 * included with this request, or <code>null</code> 086 * if the request has no cookies 087 */ 088 public Cookie[] getCookies(); 089 090 /** 091 * Returns the value of the specified request header 092 * as a <code>long</code> value that represents a 093 * <code>Date</code> object. Use this method with 094 * headers that contain dates, such as 095 * <code>If-Modified-Since</code>. 096 * 097 * <p>The date is returned as 098 * the number of milliseconds since January 1, 1970 GMT. 099 * The header name is case insensitive. 100 * 101 * <p>If the request did not have a header of the 102 * specified name, this method returns -1. If the header 103 * can't be converted to a date, the method throws 104 * an <code>IllegalArgumentException</code>. 105 * 106 * @param name a <code>String</code> specifying the 107 * name of the header 108 * 109 * @return a <code>long</code> value representing the 110 * date specified in the header expressed as the number 111 * of milliseconds since January 1, 1970 GMT, or -1 if 112 * the named header was not included with the reqest 113 * 114 * @exception IllegalArgumentException If the header value 115 * can't be converted to a date 116 */ 117 public long getDateHeader(String name); 118 119 /** 120 * Returns the value of the specified request header 121 * as a <code>String</code>. If the request did not include a header 122 * of the specified name, this method returns <code>null</code>. 123 * If there are multiple headers with the same name, this method 124 * returns the first head in the request. 125 * The header name is case insensitive. You can use 126 * this method with any request header. 127 * 128 * @param name a <code>String</code> specifying the header name 129 * 130 * @return a <code>String</code> containing the value of the 131 * requested header, or <code>null</code> if the request does not 132 * have a header of that name 133 */ 134 public String getHeader(String name); 135 136 /** 137 * Returns all the values of the specified request header 138 * as an <code>Enumeration</code> of <code>String</code> objects. 139 * 140 * <p>Some headers, such as <code>Accept-Language</code> can be sent 141 * by clients as several headers each with a different value rather than 142 * sending the header as a comma separated list. 143 * 144 * <p>If the request did not include any headers 145 * of the specified name, this method returns an empty 146 * <code>Enumeration</code>. 147 * The header name is case insensitive. You can use 148 * this method with any request header. 149 * 150 * @param name a <code>String</code> specifying the 151 * header name 152 * 153 * @return an <code>Enumeration</code> containing the values of the 154 * requested header. If the request does not have any headers of 155 * that name return an empty enumeration. If the container does not 156 * allow access to header information, return null 157 */ 158 public Enumeration getHeaders(String name); 159 160 /** 161 * Returns an enumeration of all the header names this request 162 * contains. If the request has no headers, this method returns an 163 * empty enumeration. 164 * 165 * <p>Some servlet containers do not allow servlets to access headers 166 * using this method, in which case this method returns <code>null</code> 167 * 168 * @return an enumeration of all the header names sent with this 169 * request; if the request has no headers, an empty enumeration; 170 * if the servlet container does not allow servlets to use this method, 171 * <code>null</code> 172 */ 173 public Enumeration getHeaderNames(); 174 175 /** 176 * Returns the value of the specified request header 177 * as an <code>int</code>. If the request does not have a header 178 * of the specified name, this method returns -1. If the 179 * header cannot be converted to an integer, this method 180 * throws a <code>NumberFormatException</code>. 181 * 182 * <p>The header name is case insensitive. 183 * 184 * @param name a <code>String</code> specifying the name 185 * of a request header 186 * 187 * @return an integer expressing the value of the request header or -1 188 * if the request doesn't have a header of this name 189 * 190 * @exception NumberFormatException If the header value can't be 191 * converted to an <code>int</code> 192 */ 193 public int getIntHeader(String name); 194 195 /** 196 * Returns the name of the HTTP method with which this request was made, 197 * for example, GET, POST, or PUT. Same as the value of the CGI variable 198 * REQUEST_METHOD. 199 * 200 * @return a <code>String</code> specifying the name of the method with 201 * which this request was made 202 */ 203 public String getMethod(); 204 205 /** 206 * Returns any extra path information associated with the URL the client 207 * sent when it made this request. The extra path information follows the 208 * servlet path but precedes the query string and will start with a "/" 209 * character. 210 * 211 * <p>This method returns <code>null</code> if there was no extra path 212 * information. 213 * 214 * <p>Same as the value of the CGI variable PATH_INFO. 215 * 216 * @return a <code>String</code>, decoded by the web container, specifying 217 * extra path information that comes after the servlet path but before the 218 * query string in the request URL; or <code>null</code> if the URL does 219 * not have any extra path information 220 */ 221 public String getPathInfo(); 222 223 /** 224 * Returns any extra path information after the servlet name but before 225 * the query string, and translates it to a real path. Same as the value 226 * of the CGI variable PATH_TRANSLATED. 227 * 228 * <p>If the URL does not have any extra path information, this method 229 * returns <code>null</code> or the servlet container cannot translate the 230 * virtual path to a real path for any reason (such as when the web 231 * application is executed from an archive). 232 * 233 * The web container does not decode this string. 234 * 235 * @return a <code>String</code> specifying the real path, or 236 * <code>null</code> if the URL does not have any extra path information 237 */ 238 public String getPathTranslated(); 239 240 /** 241 * Returns the portion of the request URI that indicates the context 242 * of the request. The context path always comes first in a request 243 * URI. The path starts with a "/" character but does not end with a "/" 244 * character. For servlets in the default (root) context, this method 245 * returns "". The container does not decode this string. 246 * 247 * @return a <code>String</code> specifying the portion of the request 248 * URI that indicates the context of the request 249 */ 250 public String getContextPath(); 251 252 /** 253 * Returns the query string that is contained in the request URL after 254 * the path. This method returns <code>null</code> if the URL does not 255 * have a query string. Same as the value of the CGI variable QUERY_STRING. 256 * 257 * @return a <code>String</code> containing the query string or 258 * <code>null</code> if the URL contains no query string. The value is not 259 * decoded by the container. 260 */ 261 public String getQueryString(); 262 263 /** 264 * Returns the login of the user making this request, if the user has been 265 * authenticated, or <code>null</code> if the user has not been 266 * authenticated. Whether the user name is sent with each subsequent 267 * request depends on the browser and type of authentication. Same as the 268 * value of the CGI variable REMOTE_USER. 269 * 270 * @return a <code>String</code> specifying the login of the user making 271 * this request, or <code>null</code> if the user login is not known 272 */ 273 public String getRemoteUser(); 274 275 /** 276 * Returns a boolean indicating whether the authenticated user is included 277 * in the specified logical "role". Roles and role membership can be 278 * defined using deployment descriptors. If the user has not been 279 * authenticated, the method returns <code>false</code>. 280 * 281 * @param role a <code>String</code> specifying the name of the role 282 * 283 * @return a <code>boolean</code> indicating whether the user 284 * making this request belongs to a given role; <code>false</code> 285 * if the user has not been authenticated 286 */ 287 public boolean isUserInRole(String role); 288 289 /** 290 * Returns a <code>java.security.Principal</code> object containing 291 * the name of the current authenticated user. If the user has not been 292 * authenticated, the method returns <code>null</code>. 293 * 294 * @return a <code>java.security.Principal</code> containing the name 295 * of the user making this request; <code>null</code> if the user has 296 * not been authenticated 297 */ 298 public java.security.Principal getUserPrincipal(); 299 300 /** 301 * Returns the session ID specified by the client. This may not be the 302 * same as the ID of the current valid session for this request. 303 * If the client did not specify a session ID, this method returns 304 * <code>null</code>. 305 * 306 * @return a <code>String</code> specifying the session ID, or 307 * <code>null</code> if the request did not specify a session ID 308 * 309 * @see #isRequestedSessionIdValid 310 */ 311 public String getRequestedSessionId(); 312 313 /** 314 * Returns the part of this request's URL from the protocol 315 * name up to the query string in the first line of the HTTP request. 316 * The web container does not decode this String. 317 * For example: 318 * 319 * <table summary="Examples of Returned Values"> 320 * <tr align=left><th>First line of HTTP request </th> 321 * <th> Returned Value</th> 322 * <tr><td>POST /some/path.html HTTP/1.1<td><td>/some/path.html 323 * <tr><td>GET http://foo.bar/a.html HTTP/1.0 324 * <td><td>/a.html 325 * <tr><td>HEAD /xyz?a=b HTTP/1.1<td><td>/xyz 326 * </table> 327 * 328 * <p>To reconstruct an URL with a scheme and host, use 329 * {@link HttpUtils#getRequestURL}. 330 * 331 * @return a <code>String</code> containing the part of the URL 332 * from the protocol name up to the query string 333 * 334 * @see HttpUtils#getRequestURL 335 */ 336 public String getRequestURI(); 337 338 /** 339 * Reconstructs the URL the client used to make the request. The returned 340 * URL contains a protocol, server name, port number, and server path, but 341 * it does not include query string parameters. 342 * 343 * <p>Because this method returns a <code>StringBuffer</code>, not a string, 344 * you can modify the URL easily, for example, to append query parameters. 345 * 346 * <p>This method is useful for creating redirect messages and for reporting 347 * errors. 348 * 349 * @return a <code>StringBuffer</code> object containing the reconstructed URL 350 */ 351 public StringBuffer getRequestURL(); 352 353 /** 354 * Returns the part of this request's URL that calls the servlet. This 355 * path starts with a "/" character and includes either the servlet name 356 * or a path to the servlet, but does not include any extra path 357 * information or a query string. Same as the value of the CGI variable 358 * SCRIPT_NAME. 359 * 360 * <p>This method will return an empty string ("") if the servlet used to 361 * process this request was matched using the "/*" pattern. 362 * 363 * @return a <code>String</code> containing the name or path of the servlet 364 * being called, as specified in the request URL, decoded, or an empty 365 * string if the servlet used to process the request is matched using the 366 * "/*" pattern. 367 */ 368 public String getServletPath(); 369 370 /** 371 * Returns the current <code>HttpSession</code> associated with this 372 * request or, if there is no current session and <code>create</code> is 373 * true, returns a new session. 374 * 375 * <p>If <code>create</code> is <code>false</code> and the request has no 376 * valid <code>HttpSession</code>, this method returns <code>null</code>. 377 * 378 * <p>To make sure the session is properly maintained, you must call this 379 * method before the response is committed. If the container is using cookies 380 * to maintain session integrity and is asked to create a new session 381 * when the response is committed, an IllegalStateException is thrown. 382 * 383 * @param create <code>true</code> to create a new session for this request 384 * if necessary; <code>false</code> to return <code>null</code> if there's 385 * no current session 386 * 387 * @return the <code>HttpSession</code> associated with this request or 388 * <code>null</code> if <code>create</code> is <code>false</code> and the 389 * request has no valid session 390 * 391 * @see #getSession() 392 */ 393 public HttpSession getSession(boolean create); 394 395 /** 396 * Returns the current session associated with this request, or if the 397 * request does not have a session, creates one. 398 * 399 * @return the <code>HttpSession</code> associated with this request 400 * 401 * @see #getSession(boolean) 402 */ 403 public HttpSession getSession(); 404 405 /** 406 * Checks whether the requested session ID is still valid. 407 * 408 * @return <code>true</code> if this request has an id for a valid session 409 * in the current session context; <code>false</code> otherwise 410 * 411 * @see #getRequestedSessionId 412 * @see #getSession 413 * @see HttpSessionContext 414 */ 415 public boolean isRequestedSessionIdValid(); 416 417 /** 418 * Checks whether the requested session ID came in as a cookie. 419 * 420 * @return <code>true</code> if the session ID came in as a cookie; 421 * otherwise, <code>false</code> 422 * 423 * @see #getSession 424 */ 425 public boolean isRequestedSessionIdFromCookie(); 426 427 /** 428 * Checks whether the requested session ID came in as part of the request 429 * URL. 430 * 431 * @return <code>true</code> if the session ID came in as part of a URL; 432 * otherwise, <code>false</code> 433 * 434 * @see #getSession 435 */ 436 public boolean isRequestedSessionIdFromURL(); 437 438 /** 439 * @deprecated As of Version 2.1 of the Java Servlet API, use 440 * {@link #isRequestedSessionIdFromURL} instead. 441 */ 442 public boolean isRequestedSessionIdFromUrl(); 443 }