View Javadoc

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