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