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-24 21:01:51 -0700 (Tue, 24 Oct 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 }