View Javadoc

1   /**
2    *
3    * Copyright 2003-2004 The Apache Software Foundation
4    *
5    *  Licensed under the Apache License, Version 2.0 (the "License");
6    *  you may not use this file except in compliance with the License.
7    *  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   *  Unless required by applicable law or agreed to in writing, software
12   *  distributed under the License is distributed on an "AS IS" BASIS,
13   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   *  See the License for the specific language governing permissions and
15   *  limitations under the License.
16   */
17  
18  //
19  // This source code implements specifications defined by the Java
20  // Community Process. In order to remain compliant with the specification
21  // DO NOT add / change / or delete method signatures!
22  //
23  
24  package javax.servlet.http;
25  
26  import java.util.Enumeration;
27  import javax.servlet.ServletRequest;
28  
29  /**
30   * Extends the {@link javax.servlet.ServletRequest} interface
31   * to provide request information for HTTP servlets.
32   *
33   * <p>The servlet container creates an <code>HttpServletRequest</code>
34   * object and passes it as an argument to the servlet's service
35   * methods (<code>doGet</code>, <code>doPost</code>, etc).
36   *
37   * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $
38   */
39  public interface HttpServletRequest extends ServletRequest {
40  
41      /**
42       * String identifier for Basic authentication. Value "BASIC"
43       */
44      public static final String BASIC_AUTH = "BASIC";
45  
46      /**
47       * String identifier for Form authentication. Value "FORM"
48       */
49      public static final String FORM_AUTH = "FORM";
50  
51      /**
52       * String identifier for Client Certificate authentication. Value "CLIENT_CERT"
53       */
54      public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
55  
56      /**
57       * String identifier for Digest authentication. Value "DIGEST"
58       */
59      public static final String DIGEST_AUTH = "DIGEST";
60  
61      /**
62       * Returns the name of the authentication scheme used to protect
63       * the servlet. All servlet containers support basic, form and client
64       * certificate authentication, and may additionally support digest
65       * authentication.
66       * If the servlet is not authenticated <code>null</code> is returned.
67       *
68       * <p>Same as the value of the CGI variable AUTH_TYPE.
69       *
70       * @return one of the static members BASIC_AUTH, FORM_AUTH, CLIENT_CERT_AUTH,
71       * DIGEST_AUTH (suitable for == comparison) or the container-specific string
72       * indicating the authentication scheme, or <code>null</code> if the request
73       * was not authenticated.
74       */
75      public String getAuthType();
76  
77      /**
78       * Returns an array containing all of the <code>Cookie</code>
79       * objects the client sent with this request.
80       * This method returns <code>null</code> if no cookies were sent.
81       *
82       * @return an array of all the <code>Cookies</code>
83       * included with this request, or <code>null</code>
84       * if the request has no cookies
85       */
86      public Cookie[] getCookies();
87  
88      /**
89       * Returns the value of the specified request header
90       * as a <code>long</code> value that represents a
91       * <code>Date</code> object. Use this method with
92       * headers that contain dates, such as
93       * <code>If-Modified-Since</code>.
94       *
95       * <p>The date is returned as
96       * the number of milliseconds since January 1, 1970 GMT.
97       * The header name is case insensitive.
98       *
99       * <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 }