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