HttpServletRequest


1   /*
2   * Licensed to the Apache Software Foundation (ASF) under one or more
3   * contributor license agreements.  See the NOTICE file distributed with
4   * this work for additional information regarding copyright ownership.
5   * The ASF licenses this file to You under the Apache License, Version 2.0
6   * (the "License"); you may not use this file except in compliance with
7   * the License.  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  package javax.servlet.http;
19  
20  import javax.servlet.ServletRequest  ;
21  import java.util.Enumeration  ;
22  
23  /**
24   *
25   * Extends the {@link javax.servlet.ServletRequest} interface
26   * to provide request information for HTTP servlets. 
27   *
28   * <p>The servlet container creates an <code>HttpServletRequest</code> 
29   * object and passes it as an argument to the servlet's service
30   * methods (<code>doGet</code>, <code>doPost</code>, etc).
31   *
32   *
33   * @author  Various
34   * @version $Version$
35   *
36   *
37   */
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      * String identifier for Form authentication. Value "FORM"
47      */
48      public static final String   FORM_AUTH = "FORM";
49      /**
50      * String identifier for Client Certificate authentication. Value "CLIENT_CERT"
51      */
52      public static final String   CLIENT_CERT_AUTH = "CLIENT_CERT";
53      /**
54      * String identifier for Digest authentication. Value "DIGEST"
55      */
56      public static final String   DIGEST_AUTH = "DIGEST";
57  
58      /**
59       * Returns the name of the authentication scheme used to protect
60       * the servlet. All servlet containers support basic, form and client 
61       * certificate authentication, and may additionally support digest 
62       * authentication.
63       * If the servlet is not authenticated <code>null</code> is returned. 
64       *
65       * <p>Same as the value of the CGI variable AUTH_TYPE.
66       *
67       *
68       * @return      one of the static members BASIC_AUTH, 
69       *          FORM_AUTH, CLIENT_CERT_AUTH, DIGEST_AUTH
70       *          (suitable for == comparison) or
71       *          the container-specific string indicating
72       *          the authentication scheme, or
73       *          <code>null</code> if the request was 
74       *          not authenticated.     
75       *
76       */
77     
78      public String   getAuthType();
79      
80     
81      
82  
83      /**
84       *
85       * Returns an array containing all of the <code>Cookie</code>
86       * objects the client sent with this request.
87       * This method returns <code>null</code> if no cookies were sent.
88       *
89       * @return      an array of all the <code>Cookies</code>
90       *          included with this request, or <code>null</code>
91       *          if the request has no cookies
92       *
93       *
94       */
95  
96      public Cookie  [] getCookies();
97      
98      
99      
100 
101     /**
102      *
103      * Returns the value of the specified request header
104      * as a <code>long</code> value that represents a 
105      * <code>Date</code> object. Use this method with
106      * headers that contain dates, such as
107      * <code>If-Modified-Since</code>. 
108      *
109      * <p>The date is returned as
110      * the number of milliseconds since January 1, 1970 GMT.
111      * The header name is case insensitive.
112      *
113      * <p>If the request did not have a header of the
114      * specified name, this method returns -1. If the header
115      * can't be converted to a date, the method throws
116      * an <code>IllegalArgumentException</code>.
117      *
118      * @param name      a <code>String</code> specifying the
119      *              name of the header
120      *
121      * @return          a <code>long</code> value
122      *              representing the date specified
123      *              in the header expressed as
124      *              the number of milliseconds
125      *              since January 1, 1970 GMT,
126      *              or -1 if the named header
127      *              was not included with the
128      *              request
129      *
130      * @exception   IllegalArgumentException    If the header value
131      *                          can't be converted
132      *                          to a date
133      *
134      */
135 
136     public long getDateHeader(String   name);
137     
138     
139     
140 
141     /**
142      *
143      * Returns the value of the specified request header
144      * as a <code>String</code>. If the request did not include a header
145      * of the specified name, this method returns <code>null</code>.
146      * If there are multiple headers with the same name, this method
147      * returns the first head in the request.
148      * The header name is case insensitive. You can use
149      * this method with any request header.
150      *
151      * @param name      a <code>String</code> specifying the
152      *              header name
153      *
154      * @return          a <code>String</code> containing the
155      *              value of the requested
156      *              header, or <code>null</code>
157      *              if the request does not
158      *              have a header of that name
159      *
160      */         
161 
162     public String   getHeader(String   name); 
163 
164 
165 
166 
167     /**
168      *
169      * Returns all the values of the specified request header
170      * as an <code>Enumeration</code> of <code>String</code> objects.
171      *
172      * <p>Some headers, such as <code>Accept-Language</code> can be sent
173      * by clients as several headers each with a different value rather than
174      * sending the header as a comma separated list.
175      *
176      * <p>If the request did not include any headers
177      * of the specified name, this method returns an empty
178      * <code>Enumeration</code>.
179      * The header name is case insensitive. You can use
180      * this method with any request header.
181      *
182      * @param name      a <code>String</code> specifying the
183      *              header name
184      *
185      * @return          an <code>Enumeration</code> containing
186      *                      the values of the requested header. If
187      *                      the request does not have any headers of
188      *                      that name return an empty
189      *                      enumeration. If 
190      *                      the container does not allow access to
191      *                      header information, return null
192      *
193      */         
194 
195     public Enumeration   getHeaders(String   name); 
196     
197     
198     
199     
200 
201     /**
202      *
203      * Returns an enumeration of all the header names
204      * this request contains. If the request has no
205      * headers, this method returns an empty enumeration.
206      *
207      * <p>Some servlet containers do not allow
208      * servlets to access headers using this method, in
209      * which case this method returns <code>null</code>
210      *
211      * @return          an enumeration of all the
212      *              header names sent with this
213      *              request; if the request has
214      *              no headers, an empty enumeration;
215      *              if the servlet container does not
216      *              allow servlets to use this method,
217      *              <code>null</code>
218      *              
219      *
220      */
221 
222     public Enumeration   getHeaderNames();
223     
224     
225     
226 
227     /**
228      *
229      * Returns the value of the specified request header
230      * as an <code>int</code>. If the request does not have a header
231      * of the specified name, this method returns -1. If the
232      * header cannot be converted to an integer, this method
233      * throws a <code>NumberFormatException</code>.
234      *
235      * <p>The header name is case insensitive.
236      *
237      * @param name      a <code>String</code> specifying the name
238      *              of a request header
239      *
240      * @return          an integer expressing the value 
241      *              of the request header or -1
242      *              if the request doesn't have a
243      *              header of this name
244      *
245      * @exception   NumberFormatException       If the header value
246      *                          can't be converted
247      *                          to an <code>int</code>
248      */
249 
250     public int getIntHeader(String   name);
251     
252     
253     
254 
255     /**
256      *
257      * Returns the name of the HTTP method with which this 
258      * request was made, for example, GET, POST, or PUT.
259      * Same as the value of the CGI variable REQUEST_METHOD.
260      *
261      * @return          a <code>String</code> 
262      *              specifying the name
263      *              of the method with which
264      *              this request was made
265      *
266      */
267  
268     public String   getMethod();
269     
270     
271     
272 
273     /**
274      *
275      * Returns any extra path information associated with
276      * the URL the client sent when it made this request.
277      * The extra path information follows the servlet path
278      * but precedes the query string and will start with
279      * a "/" character.
280      *
281      * <p>This method returns <code>null</code> if there
282      * was no extra path information.
283      *
284      * <p>Same as the value of the CGI variable PATH_INFO.
285      *
286      *
287      * @return      a <code>String</code>, decoded by the
288      *          web container, specifying 
289      *          extra path information that comes
290      *          after the servlet path but before
291      *          the query string in the request URL;
292      *          or <code>null</code> if the URL does not have
293      *          any extra path information
294      *
295      */
296      
297     public String   getPathInfo();
298     
299 
300  
301 
302     /**
303      *
304      * Returns any extra path information after the servlet name
305      * but before the query string, and translates it to a real
306      * path. Same as the value of the CGI variable PATH_TRANSLATED.
307      *
308      * <p>If the URL does not have any extra path information,
309      * this method returns <code>null</code> or the servlet container
310      * cannot translate the virtual path to a real path for any reason
311      * (such as when the web application is executed from an archive).
312      *
313      * The web container does not decode this string.
314      *
315      *
316      * @return      a <code>String</code> specifying the
317      *          real path, or <code>null</code> if
318      *          the URL does not have any extra path
319      *          information
320      *
321      *
322      */
323 
324     public String   getPathTranslated();
325     
326 
327  
328 
329     /**
330      *
331      * Returns the portion of the request URI that indicates the context
332      * of the request.  The context path always comes first in a request
333      * URI.  The path starts with a "/" character but does not end with a "/"
334      * character.  For servlets in the default (root) context, this method
335      * returns "". The container does not decode this string.
336      *
337      *
338      * @return      a <code>String</code> specifying the
339      *          portion of the request URI that indicates the context
340      *          of the request
341      *
342      *
343      */
344 
345     public String   getContextPath();
346     
347     
348     
349 
350     /**
351      *
352      * Returns the query string that is contained in the request
353      * URL after the path. This method returns <code>null</code>
354      * if the URL does not have a query string. Same as the value
355      * of the CGI variable QUERY_STRING. 
356      *
357      * @return      a <code>String</code> containing the query
358      *          string or <code>null</code> if the URL 
359      *          contains no query string. The value is not
360      *          decoded by the container.
361      *
362      */
363 
364     public String   getQueryString();
365     
366     
367     
368 
369     /**
370      *
371      * Returns the login of the user making this request, if the
372      * user has been authenticated, or <code>null</code> if the user 
373      * has not been authenticated.
374      * Whether the user name is sent with each subsequent request
375      * depends on the browser and type of authentication. Same as the 
376      * value of the CGI variable REMOTE_USER.
377      *
378      * @return      a <code>String</code> specifying the login
379      *          of the user making this request, or <code>null</code>
380      *          if the user login is not known
381      *
382      */
383 
384     public String   getRemoteUser();
385     
386     
387     
388 
389     /**
390      *
391      * Returns a boolean indicating whether the authenticated user is included
392      * in the specified logical "role".  Roles and role membership can be
393      * defined using deployment descriptors.  If the user has not been
394      * authenticated, the method returns <code>false</code>.
395      *
396      * @param role      a <code>String</code> specifying the name
397      *              of the role
398      *
399      * @return      a <code>boolean</code> indicating whether
400      *          the user making this request belongs to a given role;
401      *          <code>false</code> if the user has not been 
402      *          authenticated
403      *
404      */
405 
406     public boolean isUserInRole(String   role);
407     
408     
409     
410 
411     /**
412      *
413      * Returns a <code>java.security.Principal</code> object containing
414      * the name of the current authenticated user. If the user has not been
415      * authenticated, the method returns <code>null</code>.
416      *
417      * @return      a <code>java.security.Principal</code> containing
418      *          the name of the user making this request;
419      *          <code>null</code> if the user has not been 
420      *          authenticated
421      *
422      */
423 
424     public java.security.Principal   getUserPrincipal();
425     
426     
427     
428 
429     /**
430      *
431      * Returns the session ID specified by the client. This may
432      * not be the same as the ID of the current valid session
433      * for this request.
434      * If the client did not specify a session ID, this method returns
435      * <code>null</code>.
436      *
437      *
438      * @return      a <code>String</code> specifying the session
439      *          ID, or <code>null</code> if the request did
440      *          not specify a session ID
441      *
442      * @see     #isRequestedSessionIdValid
443      *
444      */
445 
446     public String   getRequestedSessionId();
447     
448     
449     
450     
451     /**
452      *
453      * Returns the part of this request's URL from the protocol
454      * name up to the query string in the first line of the HTTP request.
455      * The web container does not decode this String.
456      * For example:
457      *
458      * 
459 
460      * <table summary="Examples of Returned Values">
461      * <tr align=left><th>First line of HTTP request      </th>
462      * <th>     Returned Value</th>
463      * <tr><td>POST /some/path.html HTTP/1.1<td><td>/some/path.html
464      * <tr><td>GET http://foo.bar/a.html HTTP/1.0
465      * <td><td>/a.html
466      * <tr><td>HEAD /xyz?a=b HTTP/1.1<td><td>/xyz
467      * </table>
468      *
469      * <p>To reconstruct an URL with a scheme and host, use
470      * {@link HttpUtils#getRequestURL}.
471      *
472      * @return      a <code>String</code> containing
473      *          the part of the URL from the 
474      *          protocol name up to the query string
475      *
476      * @see     HttpUtils#getRequestURL
477      *
478      */
479 
480     public String   getRequestURI();
481     
482     /**
483      *
484      * Reconstructs the URL the client used to make the request.
485      * The returned URL contains a protocol, server name, port
486      * number, and server path, but it does not include query
487      * string parameters.
488      *
489      * <p>Because this method returns a <code>StringBuffer</code>,
490      * not a string, you can modify the URL easily, for example,
491      * to append query parameters.
492      *
493      * <p>This method is useful for creating redirect messages
494      * and for reporting errors.
495      *
496      * @return      a <code>StringBuffer</code> object containing
497      *          the reconstructed URL
498      *
499      */
500     public StringBuffer   getRequestURL();
501     
502 
503     /**
504      *
505      * Returns the part of this request's URL that calls
506      * the servlet. This path starts with a "/" character
507      * and includes either the servlet name or a path to
508      * the servlet, but does not include any extra path
509      * information or a query string. Same as the value of
510      * the CGI variable SCRIPT_NAME.
511      *
512      * <p>This method will return an empty string ("") if the
513      * servlet used to process this request was matched using
514      * the "/*" pattern.
515      *
516      * @return      a <code>String</code> containing
517      *          the name or path of the servlet being
518      *          called, as specified in the request URL,
519      *          decoded, or an empty string if the servlet
520      *          used to process the request is matched
521      *          using the "/*" pattern.
522      *
523      */
524 
525     public String   getServletPath();
526     
527     
528     
529 
530     /**
531      *
532      * Returns the current <code>HttpSession</code>
533      * associated with this request or, if there is no
534      * current session and <code>create</code> is true, returns 
535      * a new session.
536      *
537      * <p>If <code>create</code> is <code>false</code>
538      * and the request has no valid <code>HttpSession</code>,
539      * this method returns <code>null</code>.
540      *
541      * <p>To make sure the session is properly maintained,
542      * you must call this method before 
543      * the response is committed. If the container is using cookies
544      * to maintain session integrity and is asked to create a new session
545      * when the response is committed, an IllegalStateException is thrown.
546      *
547      *
548      *
549      *
550      * @param create    <code>true</code> to create
551      *          a new session for this request if necessary; 
552      *          <code>false</code> to return <code>null</code>
553      *          if there's no current session
554      *          
555      *
556      * @return      the <code>HttpSession</code> associated 
557      *          with this request or <code>null</code> if
558      *          <code>create</code> is <code>false</code>
559      *          and the request has no valid session
560      *
561      * @see #getSession()
562      *
563      *
564      */
565 
566     public HttpSession   getSession(boolean create);
567     
568     
569     
570    
571 
572     /**
573      *
574      * Returns the current session associated with this request,
575      * or if the request does not have a session, creates one.
576      * 
577      * @return      the <code>HttpSession</code> associated
578      *          with this request
579      *
580      * @see #getSession(boolean)
581      *
582      */
583 
584     public HttpSession   getSession();
585     
586     
587     
588     
589     
590 
591     /**
592      *
593      * Checks whether the requested session ID is still valid.
594      *
595      * @return          <code>true</code> if this
596      *              request has an id for a valid session
597      *              in the current session context;
598      *              <code>false</code> otherwise
599      *
600      * @see         #getRequestedSessionId
601      * @see         #getSession
602      * @see         HttpSessionContext
603      *
604      */
605 
606     public boolean isRequestedSessionIdValid();
607     
608     
609     
610 
611     /**
612      *
613      * Checks whether the requested session ID came in as a cookie.
614      *
615      * @return          <code>true</code> if the session ID
616      *              came in as a
617      *              cookie; otherwise, <code>false</code>
618      *
619      *
620      * @see         #getSession
621      *
622      */ 
623 
624     public boolean isRequestedSessionIdFromCookie();
625     
626     
627     
628 
629     /**
630      *
631      * Checks whether the requested session ID came in as part of the 
632      * request URL.
633      *
634      * @return          <code>true</code> if the session ID
635      *              came in as part of a URL; otherwise,
636      *              <code>false</code>
637      *
638      *
639      * @see         #getSession
640      *
641      */
642     
643     public boolean isRequestedSessionIdFromURL();
644     
645     
646     
647     
648     
649     /**
650      *
651      * @deprecated      As of Version 2.1 of the Java Servlet
652      *              API, use {@link #isRequestedSessionIdFromURL}
653      *              instead.
654      *
655      */
656 
657     public boolean isRequestedSessionIdFromUrl();
658 
659 
660     
661 }
662
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags