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 }