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