lib/servlet-api/javax/servlet/http/HttpServletRequest.java

   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 java.io.IOException;
  21 import java.util.Collection;
  22 import java.util.Enumeration;
  23
  24 import javax.servlet.ServletException;
  25 import javax.servlet.ServletRequest;
  26
  27 /**
  28  * Extends the {@link javax.servlet.ServletRequest} interface to provide request
  29  * information for HTTP servlets.
  30  * <p>
  31  * The servlet container creates an <code>HttpServletRequest</code> object and
  32  * passes it as an argument to the servlet's service methods
  33  * (<code>doGet</code>, <code>doPost</code>, etc).
  34  */
  35 public interface HttpServletRequest extends ServletRequest {
  36
  37     /**
  38      * String identifier for Basic authentication. Value "BASIC"
  39      */
  40     public static final String BASIC_AUTH = "BASIC";
  41     /**
  42      * String identifier for Form authentication. Value "FORM"
  43      */
  44     public static final String FORM_AUTH = "FORM";
  45     /**
  46      * String identifier for Client Certificate authentication. Value
  47      * "CLIENT_CERT"
  48      */
  49     public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
  50     /**
  51      * String identifier for Digest authentication. Value "DIGEST"
  52      */
  53     public static final String DIGEST_AUTH = "DIGEST";
  54
  55     /**
  56      * Returns the name of the authentication scheme used to protect the
  57      * servlet. All servlet containers support basic, form and client
  58      * certificate authentication, and may additionally support digest
  59      * authentication. If the servlet is not authenticated <code>null</code> is
  60      * returned.
  61      * <p>
  62      * Same as the value of the CGI variable AUTH_TYPE.
  63      *
  64      * @return one of the static members BASIC_AUTH, FORM_AUTH, CLIENT_CERT_AUTH,
  65      *         DIGEST_AUTH (suitable for == comparison) or the
  66      *         container-specific string indicating the authentication scheme,
  67      *         or <code>null</code> if the request was not authenticated.
  68      */
  69     public String getAuthType();
  70
  71     /**
  72      * Returns an array containing all of the <code>Cookie</code> objects the
  73      * client sent with this request. This method returns <code>null</code> if
  74      * no cookies were sent.
  75      *
  76      * @return an array of all the <code>Cookies</code> included with this
  77      *         request, or <code>null</code> if the request has no cookies
  78      */
  79     public Cookie[] getCookies();
  80
  81     /**
  82      * Returns the value of the specified request header as a <code>long</code>
  83      * value that represents a <code>Date</code> object. Use this method with
  84      * headers that contain dates, such as <code>If-Modified-Since</code>.
  85      * <p>
  86      * The date is returned as the number of milliseconds since January 1, 1970
  87      * GMT. The header name is case insensitive.
  88      * <p>
  89      * If the request did not have a header of the specified name, this method
  90      * returns -1. If the header can't be converted to a date, the method throws
  91      * an <code>IllegalArgumentException</code>.
  92      *
  93      * @param name
  94      *            a <code>String</code> specifying the name of the header
  95      * @return a <code>long</code> value representing the date specified in the
  96      *         header expressed as the number of milliseconds since January 1,
  97      *         1970 GMT, or -1 if the named header was not included with the
  98      *         request
  99      * @exception IllegalArgumentException
 100      *                If the header value can't be converted to a date
 101      */
 102     public long getDateHeader(String name);
 103
 104     /**
 105      * Returns the value of the specified request header as a
 106      * <code>String</code>. If the request did not include a header of the
 107      * specified name, this method returns <code>null</code>. If there are
 108      * multiple headers with the same name, this method returns the first head
 109      * in the request. The header name is case insensitive. You can use this
 110      * method with any request header.
 111      *
 112      * @param name
 113      *            a <code>String</code> specifying the header name
 114      * @return a <code>String</code> containing the value of the requested
 115      *         header, or <code>null</code> if the request does not have a
 116      *         header of that name
 117      */
 118     public String getHeader(String name);
 119
 120     /**
 121      * Returns all the values of the specified request header as an
 122      * <code>Enumeration</code> of <code>String</code> objects.
 123      * <p>
 124      * Some headers, such as <code>Accept-Language</code> can be sent by clients
 125      * as several headers each with a different value rather than sending the
 126      * header as a comma separated list.
 127      * <p>
 128      * If the request did not include any headers of the specified name, this
 129      * method returns an empty <code>Enumeration</code>. The header name is case
 130      * insensitive. You can use this method with any request header.
 131      *
 132      * @param name
 133      *            a <code>String</code> specifying the header name
 134      * @return an <code>Enumeration</code> containing the values of the requested
 135      *         header. If the request does not have any headers of that name
 136      *         return an empty enumeration. If the container does not allow
 137      *         access to header information, return null
 138      */
 139     public Enumeration<String> getHeaders(String name);
 140
 141     /**
 142      * Returns an enumeration of all the header names this request contains. If
 143      * the request has no headers, this method returns an empty enumeration.
 144      * <p>
 145      * Some servlet containers do not allow servlets to access headers using
 146      * this method, in which case this method returns <code>null</code>
 147      *
 148      * @return an enumeration of all the header names sent with this request; if
 149      *         the request has no headers, an empty enumeration; if the servlet
 150      *         container does not allow servlets to use this method,
 151      *         <code>null</code>
 152      */
 153     public Enumeration<String> getHeaderNames();
 154
 155     /**
 156      * Returns the value of the specified request header as an <code>int</code>.
 157      * If the request does not have a header of the specified name, this method
 158      * returns -1. If the header cannot be converted to an integer, this method
 159      * throws a <code>NumberFormatException</code>.
 160      * <p>
 161      * The header name is case insensitive.
 162      *
 163      * @param name
 164      *            a <code>String</code> specifying the name of a request header
 165      * @return an integer expressing the value of the request header or -1 if the
 166      *         request doesn't have a header of this name
 167      * @exception NumberFormatException
 168      *                If the header value can't be converted to an
 169      *                <code>int</code>
 170      */
 171     public int getIntHeader(String name);
 172
 173     /**
 174      * Returns the name of the HTTP method with which this request was made, for
 175      * example, GET, POST, or PUT. Same as the value of the CGI variable
 176      * REQUEST_METHOD.
 177      *
 178      * @return a <code>String</code> specifying the name of the method with
 179      *         which this request was made
 180      */
 181     public String getMethod();
 182
 183     /**
 184      * Returns any extra path information associated with the URL the client
 185      * sent when it made this request. The extra path information follows the
 186      * servlet path but precedes the query string and will start with a "/"
 187      * character.
 188      * <p>
 189      * This method returns <code>null</code> if there was no extra path
 190      * information.
 191      * <p>
 192      * Same as the value of the CGI variable PATH_INFO.
 193      *
 194      * @return a <code>String</code>, decoded by the web container, specifying
 195      *         extra path information that comes after the servlet path but
 196      *         before the query string in the request URL; or <code>null</code>
 197      *         if the URL does not have any extra path information
 198      */
 199     public String getPathInfo();
 200
 201     /**
 202      * Returns any extra path information after the servlet name but before the
 203      * query string, and translates it to a real path. Same as the value of the
 204      * CGI variable PATH_TRANSLATED.
 205      * <p>
 206      * If the URL does not have any extra path information, this method returns
 207      * <code>null</code> or the servlet container cannot translate the virtual
 208      * path to a real path for any reason (such as when the web application is
 209      * executed from an archive). The web container does not decode this string.
 210      *
 211      * @return a <code>String</code> specifying the real path, or
 212      *         <code>null</code> if the URL does not have any extra path
 213      *         information
 214      */
 215     public String getPathTranslated();
 216
 217     /**
 218      * Returns the portion of the request URI that indicates the context of the
 219      * request. The context path always comes first in a request URI. The path
 220      * starts with a "/" character but does not end with a "/" character. For
 221      * servlets in the default (root) context, this method returns "". The
 222      * container does not decode this string.
 223      *
 224      * @return a <code>String</code> specifying the portion of the request URI
 225      *         that indicates the context of the request
 226      */
 227     public String getContextPath();
 228
 229     /**
 230      * Returns the query string that is contained in the request URL after the
 231      * path. This method returns <code>null</code> if the URL does not have a
 232      * query string. Same as the value of the CGI variable QUERY_STRING.
 233      *
 234      * @return a <code>String</code> containing the query string or
 235      *         <code>null</code> if the URL contains no query string. The value
 236      *         is not decoded by the container.
 237      */
 238     public String getQueryString();
 239
 240     /**
 241      * Returns the login of the user making this request, if the user has been
 242      * authenticated, or <code>null</code> if the user has not been
 243      * authenticated. Whether the user name is sent with each subsequent request
 244      * depends on the browser and type of authentication. Same as the value of
 245      * the CGI variable REMOTE_USER.
 246      *
 247      * @return a <code>String</code> specifying the login of the user making
 248      *         this request, or <code>null</code> if the user login is not known
 249      */
 250     public String getRemoteUser();
 251
 252     /**
 253      * Returns a boolean indicating whether the authenticated user is included
 254      * in the specified logical "role". Roles and role membership can be defined
 255      * using deployment descriptors. If the user has not been authenticated, the
 256      * method returns <code>false</code>.
 257      *
 258      * @param role
 259      *            a <code>String</code> specifying the name of the role
 260      * @return a <code>boolean</code> indicating whether the user making this
 261      *         request belongs to a given role; <code>false</code> if the user
 262      *         has not been authenticated
 263      */
 264     public boolean isUserInRole(String role);
 265
 266     /**
 267      * Returns a <code>java.security.Principal</code> object containing the name
 268      * of the current authenticated user. If the user has not been
 269      * authenticated, the method returns <code>null</code>.
 270      *
 271      * @return a <code>java.security.Principal</code> containing the name of the
 272      *         user making this request; <code>null</code> if the user has not
 273      *         been authenticated
 274      */
 275     public java.security.Principal getUserPrincipal();
 276
 277     /**
 278      * Returns the session ID specified by the client. This may not be the same
 279      * as the ID of the current valid session for this request. If the client
 280      * did not specify a session ID, this method returns <code>null</code>.
 281      *
 282      * @return a <code>String</code> specifying the session ID, or
 283      *         <code>null</code> if the request did not specify a session ID
 284      * @see #isRequestedSessionIdValid
 285      */
 286     public String getRequestedSessionId();
 287
 288     /**
 289      * Returns the part of this request's URL from the protocol name up to the
 290      * query string in the first line of the HTTP request. The web container
 291      * does not decode this String. For example:
 292      * <table summary="Examples of Returned Values">
 293      * <tr align=left>
 294      * <th>First line of HTTP request</th>
 295      * <th>Returned Value</th>
 296      * <tr>
 297      * <td>POST /some/path.html HTTP/1.1
 298      * <td>
 299      * <td>/some/path.html
 300      * <tr>
 301      * <td>GET http://foo.bar/a.html HTTP/1.0
 302      * <td>
 303      * <td>/a.html
 304      * <tr>
 305      * <td>HEAD /xyz?a=b HTTP/1.1
 306      * <td>
 307      * <td>/xyz
 308      * </table>
 309      * <p>
 310      * To reconstruct an URL with a scheme and host, use
 311      * {@link #getRequestURL}.
 312      *
 313      * @return a <code>String</code> containing the part of the URL from the
 314      *         protocol name up to the query string
 315      * @see #getRequestURL
 316      */
 317     public String getRequestURI();
 318
 319     /**
 320      * Reconstructs the URL the client used to make the request. The returned
 321      * URL contains a protocol, server name, port number, and server path, but
 322      * it does not include query string parameters.
 323      * <p>
 324      * Because this method returns a <code>StringBuffer</code>, not a string,
 325      * you can modify the URL easily, for example, to append query parameters.
 326      * <p>
 327      * This method is useful for creating redirect messages and for reporting
 328      * errors.
 329      *
 330      * @return a <code>StringBuffer</code> object containing the reconstructed
 331      *         URL
 332      */
 333     public StringBuffer getRequestURL();
 334
 335     /**
 336      * Returns the part of this request's URL that calls the servlet. This path
 337      * starts with a "/" character and includes either the servlet name or a
 338      * path to the servlet, but does not include any extra path information or a
 339      * query string. Same as the value of the CGI variable SCRIPT_NAME.
 340      * <p>
 341      * This method will return an empty string ("") if the servlet used to
 342      * process this request was matched using the "/*" pattern.
 343      *
 344      * @return a <code>String</code> containing the name or path of the servlet
 345      *         being called, as specified in the request URL, decoded, or an
 346      *         empty string if the servlet used to process the request is
 347      *         matched using the "/*" pattern.
 348      */
 349     public String getServletPath();
 350
 351     /**
 352      * Returns the current <code>HttpSession</code> associated with this request
 353      * or, if there is no current session and <code>create</code> is true,
 354      * returns a new session.
 355      * <p>
 356      * If <code>create</code> is <code>false</code> and the request has no valid
 357      * <code>HttpSession</code>, this method returns <code>null</code>.
 358      * <p>
 359      * To make sure the session is properly maintained, you must call this
 360      * method before the response is committed. If the container is using
 361      * cookies to maintain session integrity and is asked to create a new
 362      * session when the response is committed, an IllegalStateException is
 363      * thrown.
 364      *
 365      * @param create
 366      *            <code>true</code> to create a new session for this request if
 367      *            necessary; <code>false</code> to return <code>null</code> if
 368      *            there's no current session
 369      * @return the <code>HttpSession</code> associated with this request or
 370      *         <code>null</code> if <code>create</code> is <code>false</code>
 371      *         and the request has no valid session
 372      * @see #getSession()
 373      */
 374     public HttpSession getSession(boolean create);
 375
 376     /**
 377      * Returns the current session associated with this request, or if the
 378      * request does not have a session, creates one.
 379      *
 380      * @return the <code>HttpSession</code> associated with this request
 381      * @see #getSession(boolean)
 382      */
 383     public HttpSession getSession();
 384
 385     /**
 386      * Changes the session ID of the session associated with this request. This
 387      * method does not create a new session object it only changes the ID of the
 388      * current session.
 389      *
 390      * @return the new session ID allocated to the session
 391      * @see HttpSessionIdListener
 392      * @since Servlet 3.1
 393      */
 394     public String changeSessionId();
 395
 396     /**
 397      * Checks whether the requested session ID is still valid.
 398      *
 399      * @return <code>true</code> if this request has an id for a valid session
 400      *         in the current session context; <code>false</code> otherwise
 401      * @see #getRequestedSessionId
 402      * @see #getSession
 403      */
 404     public boolean isRequestedSessionIdValid();
 405
 406     /**
 407      * Checks whether the requested session ID came in as a cookie.
 408      *
 409      * @return <code>true</code> if the session ID came in as a cookie;
 410      *         otherwise, <code>false</code>
 411      * @see #getSession
 412      */
 413     public boolean isRequestedSessionIdFromCookie();
 414
 415     /**
 416      * Checks whether the requested session ID came in as part of the request
 417      * URL.
 418      *
 419      * @return <code>true</code> if the session ID came in as part of a URL;
 420      *         otherwise, <code>false</code>
 421      * @see #getSession
 422      */
 423     public boolean isRequestedSessionIdFromURL();
 424
 425     /**
 426      * @deprecated As of Version 2.1 of the Java Servlet API, use
 427      *             {@link #isRequestedSessionIdFromURL} instead.
 428      */
 429     @SuppressWarnings("dep-ann")
 430     // Spec API does not use @Deprecated
 431     public boolean isRequestedSessionIdFromUrl();
 432
 433     /**
 434      * Triggers the same authentication process as would be triggered if the
 435      * request is for a resource that is protected by a security constraint.
 436      *
 437      * @param response  The response to use to return any authentication
 438      *                  challenge
 439      * @return <code>true</code> if the user is successfully authenticated and
 440      *         <code>false</code> if not
 441      *
 442      * @since Servlet 3.0
 443      */
 444     public boolean authenticate(HttpServletResponse response)
 445             throws IOException, ServletException;
 446
 447     /**
 448      * Authenticate the provided user name and password and then associated the
 449      * authenticated user with the request.
 450      *
 451      * @param username  The user name to authenticate
 452      * @param password  The password to use to authenticate the user
 453      *
 454      * @throws ServletException
 455      *             If any of {@link #getRemoteUser()},
 456      *             {@link #getUserPrincipal()} or {@link #getAuthType()} are
 457      *             non-null, if the configured authenticator does not support
 458      *             user name and password authentication or if the
 459      *             authentication fails
 460      * @since Servlet 3.0
 461      */
 462     public void login(String username, String password) throws ServletException;
 463
 464     /**
 465      * Removes any authenticated user from the request.
 466      *
 467      * @throws ServletException
 468      *             If the logout fails
 469      * @since Servlet 3.0
 470      */
 471     public void logout() throws ServletException;
 472
 473     /**
 474      * Return a collection of all uploaded Parts.
 475      *
 476      * @return A collection of all uploaded Parts.
 477      * @throws IOException
 478      *             if an I/O error occurs
 479      * @throws IllegalStateException
 480      *             if size limits are exceeded or no multipart configuration is
 481      *             provided
 482      * @throws ServletException
 483      *             if the request is not multipart/form-data
 484      * @since Servlet 3.0
 485      */
 486     public Collection<Part> getParts() throws IOException,
 487             ServletException;
 488
 489     /**
 490      * Gets the named Part or null if the Part does not exist. Triggers upload
 491      * of all Parts.
 492      *
 493      * @param name
 494      * @return The named Part or null if the Part does not exist
 495      * @throws IOException
 496      *             if an I/O error occurs
 497      * @throws IllegalStateException
 498      *             if size limits are exceeded
 499      * @throws ServletException
 500      *             if the request is not multipart/form-data
 501      * @since Servlet 3.0
 502      */
 503     public Part getPart(String name) throws IOException,
 504             ServletException;
 505
 506     /**
 507      * Start the HTTP upgrade process and pass the connection to the provided
 508      * protocol handler once the current request/response pair has completed
 509      * processing. Calling this method sets the response status to {@link
 510      * HttpServletResponse#SC_SWITCHING_PROTOCOLS} and flushes the response.
 511      * Protocol specific headers must have already been set before this method
 512      * is called.
 513      *
 514      * @throws IOException
 515      *             if an I/O error occurred during the upgrade
 516      * @throws ServletException
 517      *             if the given httpUpgradeHandlerClass fails to be instantiated
 518      * @since Servlet 3.1
 519      */
 520     public <T extends HttpUpgradeHandler> T upgrade(
 521             Class<T> httpUpgradeHandlerClass) throws java.io.IOException, ServletException;
 522 }