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