lib/servlet-api/javax/servlet/ServletRequest.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 package javax.servlet;
  18
  19 import java.io.BufferedReader;
  20 import java.io.IOException;
  21 import java.util.Enumeration;
  22 import java.util.Locale;
  23 import java.util.Map;
  24
  25 /**
  26  * Defines an object to provide client request information to a servlet. The
  27  * servlet container creates a <code>ServletRequest</code> object and passes it
  28  * as an argument to the servlet's <code>service</code> method.
  29  * <p>
  30  * A <code>ServletRequest</code> object provides data including parameter name
  31  * and values, attributes, and an input stream. Interfaces that extend
  32  * <code>ServletRequest</code> can provide additional protocol-specific data
  33  * (for example, HTTP data is provided by
  34  * {@link javax.servlet.http.HttpServletRequest}.
  35  *
  36  * @see javax.servlet.http.HttpServletRequest
  37  */
  38 public interface ServletRequest {
  39
  40     /**
  41      * Returns the value of the named attribute as an <code>Object</code>, or
  42      * <code>null</code> if no attribute of the given name exists.
  43      * <p>
  44      * Attributes can be set two ways. The servlet container may set attributes
  45      * to make available custom information about a request. For example, for
  46      * requests made using HTTPS, the attribute
  47      * <code>javax.servlet.request.X509Certificate</code> can be used to
  48      * retrieve information on the certificate of the client. Attributes can
  49      * also be set programatically using {@link ServletRequest#setAttribute}.
  50      * This allows information to be embedded into a request before a
  51      * {@link RequestDispatcher} call.
  52      * <p>
  53      * Attribute names should follow the same conventions as package names.
  54      * Names beginning with <code>java.*</code> and <code>javax.*</code> are
  55      * reserved for use by the Servlet specification. Names beginning with
  56      * <code>sun.*</code>, <code>com.sun.*</code>, <code>oracle.*</code> and
  57      * <code>com.oracle.*</code>) are reserved for use by Oracle Corporation.
  58      *
  59      * @param name
  60      *            a <code>String</code> specifying the name of the attribute
  61      * @return an <code>Object</code> containing the value of the attribute, or
  62      *         <code>null</code> if the attribute does not exist
  63      */
  64     public Object getAttribute(String name);
  65
  66     /**
  67      * Returns an <code>Enumeration</code> containing the names of the
  68      * attributes available to this request. This method returns an empty
  69      * <code>Enumeration</code> if the request has no attributes available to
  70      * it.
  71      *
  72      * @return an <code>Enumeration</code> of strings containing the names of the
  73      *         request's attributes
  74      */
  75     public Enumeration<String> getAttributeNames();
  76
  77     /**
  78      * Returns the name of the character encoding used in the body of this
  79      * request. This method returns <code>null</code> if the request does not
  80      * specify a character encoding
  81      *
  82      * @return a <code>String</code> containing the name of the character
  83      *         encoding, or <code>null</code> if the request does not specify a
  84      *         character encoding
  85      */
  86     public String getCharacterEncoding();
  87
  88     /**
  89      * Overrides the name of the character encoding used in the body of this
  90      * request. This method must be called prior to reading request parameters
  91      * or reading input using getReader().
  92      *
  93      * @param env
  94      *            a <code>String</code> containing the name of the character
  95      *            encoding.
  96      * @throws java.io.UnsupportedEncodingException
  97      *             if this is not a valid encoding
  98      */
  99     public void setCharacterEncoding(String env)
 100             throws java.io.UnsupportedEncodingException;
 101
 102     /**
 103      * Returns the length, in bytes, of the request body and made available by
 104      * the input stream, or -1 if the length is not known. For HTTP servlets,
 105      * same as the value of the CGI variable CONTENT_LENGTH.
 106      *
 107      * @return an integer containing the length of the request body or -1 if the
 108      *         length is not known or is greater than {@link Integer#MAX_VALUE}
 109      */
 110     public int getContentLength();
 111
 112     /**
 113      * Returns the length, in bytes, of the request body and made available by
 114      * the input stream, or -1 if the length is not known. For HTTP servlets,
 115      * same as the value of the CGI variable CONTENT_LENGTH.
 116      *
 117      * @return a long integer containing the length of the request body or -1 if
 118      *         the length is not known
 119      */
 120     public long getContentLengthLong();
 121
 122     /**
 123      * Returns the MIME type of the body of the request, or <code>null</code> if
 124      * the type is not known. For HTTP servlets, same as the value of the CGI
 125      * variable CONTENT_TYPE.
 126      *
 127      * @return a <code>String</code> containing the name of the MIME type of the
 128      *         request, or null if the type is not known
 129      */
 130     public String getContentType();
 131
 132     /**
 133      * Retrieves the body of the request as binary data using a
 134      * {@link ServletInputStream}. Either this method or {@link #getReader} may
 135      * be called to read the body, not both.
 136      *
 137      * @return a {@link ServletInputStream} object containing the body of the
 138      *         request
 139      * @exception IllegalStateException
 140      *                if the {@link #getReader} method has already been called
 141      *                for this request
 142      * @exception IOException
 143      *                if an input or output exception occurred
 144      */
 145     public ServletInputStream getInputStream() throws IOException;
 146
 147     /**
 148      * Returns the value of a request parameter as a <code>String</code>, or
 149      * <code>null</code> if the parameter does not exist. Request parameters are
 150      * extra information sent with the request. For HTTP servlets, parameters
 151      * are contained in the query string or posted form data.
 152      * <p>
 153      * You should only use this method when you are sure the parameter has only
 154      * one value. If the parameter might have more than one value, use
 155      * {@link #getParameterValues}.
 156      * <p>
 157      * If you use this method with a multivalued parameter, the value returned
 158      * is equal to the first value in the array returned by
 159      * <code>getParameterValues</code>.
 160      * <p>
 161      * If the parameter data was sent in the request body, such as occurs with
 162      * an HTTP POST request, then reading the body directly via
 163      * {@link #getInputStream} or {@link #getReader} can interfere with the
 164      * execution of this method.
 165      *
 166      * @param name
 167      *            a <code>String</code> specifying the name of the parameter
 168      * @return a <code>String</code> representing the single value of the
 169      *         parameter
 170      * @see #getParameterValues
 171      */
 172     public String getParameter(String name);
 173
 174     /**
 175      * Returns an <code>Enumeration</code> of <code>String</code> objects
 176      * containing the names of the parameters contained in this request. If the
 177      * request has no parameters, the method returns an empty
 178      * <code>Enumeration</code>.
 179      *
 180      * @return an <code>Enumeration</code> of <code>String</code> objects, each
 181      *         <code>String</code> containing the name of a request parameter;
 182      *         or an empty <code>Enumeration</code> if the request has no
 183      *         parameters
 184      */
 185     public Enumeration<String> getParameterNames();
 186
 187     /**
 188      * Returns an array of <code>String</code> objects containing all of the
 189      * values the given request parameter has, or <code>null</code> if the
 190      * parameter does not exist.
 191      * <p>
 192      * If the parameter has a single value, the array has a length of 1.
 193      *
 194      * @param name
 195      *            a <code>String</code> containing the name of the parameter
 196      *            whose value is requested
 197      * @return an array of <code>String</code> objects containing the parameter's
 198      *         values
 199      * @see #getParameter
 200      */
 201     public String[] getParameterValues(String name);
 202
 203     /**
 204      * Returns a java.util.Map of the parameters of this request. Request
 205      * parameters are extra information sent with the request. For HTTP
 206      * servlets, parameters are contained in the query string or posted form
 207      * data.
 208      *
 209      * @return an immutable java.util.Map containing parameter names as keys and
 210      *         parameter values as map values. The keys in the parameter map are
 211      *         of type String. The values in the parameter map are of type
 212      *         String array.
 213      */
 214     public Map<String, String[]> getParameterMap();
 215
 216     /**
 217      * Returns the name and version of the protocol the request uses in the form
 218      * <i>protocol/majorVersion.minorVersion</i>, for example, HTTP/1.1. For
 219      * HTTP servlets, the value returned is the same as the value of the CGI
 220      * variable <code>SERVER_PROTOCOL</code>.
 221      *
 222      * @return a <code>String</code> containing the protocol name and version
 223      *         number
 224      */
 225     public String getProtocol();
 226
 227     /**
 228      * Returns the name of the scheme used to make this request, for example,
 229      * <code>http</code>, <code>https</code>, or <code>ftp</code>. Different
 230      * schemes have different rules for constructing URLs, as noted in RFC 1738.
 231      *
 232      * @return a <code>String</code> containing the name of the scheme used to
 233      *         make this request
 234      */
 235     public String getScheme();
 236
 237     /**
 238      * Returns the host name of the server to which the request was sent. It is
 239      * the value of the part before ":" in the <code>Host</code> header value,
 240      * if any, or the resolved server name, or the server IP address.
 241      *
 242      * @return a <code>String</code> containing the name of the server
 243      */
 244     public String getServerName();
 245
 246     /**
 247      * Returns the port number to which the request was sent. It is the value of
 248      * the part after ":" in the <code>Host</code> header value, if any, or the
 249      * server port where the client connection was accepted on.
 250      *
 251      * @return an integer specifying the port number
 252      */
 253     public int getServerPort();
 254
 255     /**
 256      * Retrieves the body of the request as character data using a
 257      * <code>BufferedReader</code>. The reader translates the character data
 258      * according to the character encoding used on the body. Either this method
 259      * or {@link #getInputStream} may be called to read the body, not both.
 260      *
 261      * @return a <code>BufferedReader</code> containing the body of the request
 262      * @exception java.io.UnsupportedEncodingException
 263      *                if the character set encoding used is not supported and
 264      *                the text cannot be decoded
 265      * @exception IllegalStateException
 266      *                if {@link #getInputStream} method has been called on this
 267      *                request
 268      * @exception IOException
 269      *                if an input or output exception occurred
 270      * @see #getInputStream
 271      */
 272     public BufferedReader getReader() throws IOException;
 273
 274     /**
 275      * Returns the Internet Protocol (IP) address of the client or last proxy
 276      * that sent the request. For HTTP servlets, same as the value of the CGI
 277      * variable <code>REMOTE_ADDR</code>.
 278      *
 279      * @return a <code>String</code> containing the IP address of the client
 280      *         that sent the request
 281      */
 282     public String getRemoteAddr();
 283
 284     /**
 285      * Returns the fully qualified name of the client or the last proxy that
 286      * sent the request. If the engine cannot or chooses not to resolve the
 287      * hostname (to improve performance), this method returns the dotted-string
 288      * form of the IP address. For HTTP servlets, same as the value of the CGI
 289      * variable <code>REMOTE_HOST</code>.
 290      *
 291      * @return a <code>String</code> containing the fully qualified name of the
 292      *         client
 293      */
 294     public String getRemoteHost();
 295
 296     /**
 297      * Stores an attribute in this request. Attributes are reset between
 298      * requests. This method is most often used in conjunction with
 299      * {@link RequestDispatcher}.
 300      * <p>
 301      * Attribute names should follow the same conventions as package names.
 302      * Names beginning with <code>java.*</code> and <code>javax.*</code> are
 303      * reserved for use by the Servlet specification. Names beginning with
 304      * <code>sun.*</code>, <code>com.sun.*</code>, <code>oracle.*</code> and
 305      * <code>com.oracle.*</code>) are reserved for use by Oracle Corporation.
 306      * <br>
 307      * If the object passed in is null, the effect is the same as calling
 308      * {@link #removeAttribute}. <br>
 309      * It is warned that when the request is dispatched from the servlet resides
 310      * in a different web application by <code>RequestDispatcher</code>, the
 311      * object set by this method may not be correctly retrieved in the caller
 312      * servlet.
 313      *
 314      * @param name
 315      *            a <code>String</code> specifying the name of the attribute
 316      * @param o
 317      *            the <code>Object</code> to be stored
 318      */
 319     public void setAttribute(String name, Object o);
 320
 321     /**
 322      * Removes an attribute from this request. This method is not generally
 323      * needed as attributes only persist as long as the request is being
 324      * handled.
 325      * <p>
 326      * Attribute names should follow the same conventions as package names.
 327      * Names beginning with <code>java.*</code> and <code>javax.*</code> are
 328      * reserved for use by the Servlet specification. Names beginning with
 329      * <code>sun.*</code>, <code>com.sun.*</code>, <code>oracle.*</code> and
 330      * <code>com.oracle.*</code>) are reserved for use by Oracle Corporation.
 331      *
 332      * @param name
 333      *            a <code>String</code> specifying the name of the attribute to
 334      *            remove
 335      */
 336     public void removeAttribute(String name);
 337
 338     /**
 339      * Returns the preferred <code>Locale</code> that the client will accept
 340      * content in, based on the Accept-Language header. If the client request
 341      * doesn't provide an Accept-Language header, this method returns the
 342      * default locale for the server.
 343      *
 344      * @return the preferred <code>Locale</code> for the client
 345      */
 346     public Locale getLocale();
 347
 348     /**
 349      * Returns an <code>Enumeration</code> of <code>Locale</code> objects
 350      * indicating, in decreasing order starting with the preferred locale, the
 351      * locales that are acceptable to the client based on the Accept-Language
 352      * header. If the client request doesn't provide an Accept-Language header,
 353      * this method returns an <code>Enumeration</code> containing one
 354      * <code>Locale</code>, the default locale for the server.
 355      *
 356      * @return an <code>Enumeration</code> of preferred <code>Locale</code>
 357      *         objects for the client
 358      */
 359     public Enumeration<Locale> getLocales();
 360
 361     /**
 362      * Returns a boolean indicating whether this request was made using a secure
 363      * channel, such as HTTPS.
 364      *
 365      * @return a boolean indicating if the request was made using a secure
 366      *         channel
 367      */
 368     public boolean isSecure();
 369
 370     /**
 371      * Returns a {@link RequestDispatcher} object that acts as a wrapper for the
 372      * resource located at the given path. A <code>RequestDispatcher</code>
 373      * object can be used to forward a request to the resource or to include the
 374      * resource in a response. The resource can be dynamic or static.
 375      * <p>
 376      * The pathname specified may be relative, although it cannot extend outside
 377      * the current servlet context. If the path begins with a "/" it is
 378      * interpreted as relative to the current context root. This method returns
 379      * <code>null</code> if the servlet container cannot return a
 380      * <code>RequestDispatcher</code>.
 381      * <p>
 382      * The difference between this method and
 383      * {@link ServletContext#getRequestDispatcher} is that this method can take
 384      * a relative path.
 385      *
 386      * @param path
 387      *            a <code>String</code> specifying the pathname to the resource.
 388      *            If it is relative, it must be relative against the current
 389      *            servlet.
 390      * @return a <code>RequestDispatcher</code> object that acts as a wrapper for
 391      *         the resource at the specified path, or <code>null</code> if the
 392      *         servlet container cannot return a <code>RequestDispatcher</code>
 393      * @see RequestDispatcher
 394      * @see ServletContext#getRequestDispatcher
 395      */
 396     public RequestDispatcher getRequestDispatcher(String path);
 397
 398     /**
 399      * @deprecated As of Version 2.1 of the Java Servlet API, use
 400      *             {@link ServletContext#getRealPath} instead.
 401      */
 402     @SuppressWarnings("dep-ann")
 403     // Spec API does not use @Deprecated
 404     public String getRealPath(String path);
 405
 406     /**
 407      * Returns the Internet Protocol (IP) source port of the client or last
 408      * proxy that sent the request.
 409      *
 410      * @return an integer specifying the port number
 411      * @since 2.4
 412      */
 413     public int getRemotePort();
 414
 415     /**
 416      * Returns the host name of the Internet Protocol (IP) interface on which
 417      * the request was received.
 418      *
 419      * @return a <code>String</code> containing the host name of the IP on which
 420      *         the request was received.
 421      * @since 2.4
 422      */
 423     public String getLocalName();
 424
 425     /**
 426      * Returns the Internet Protocol (IP) address of the interface on which the
 427      * request was received.
 428      *
 429      * @return a <code>String</code> containing the IP address on which the
 430      *         request was received.
 431      * @since 2.4
 432      */
 433     public String getLocalAddr();
 434
 435     /**
 436      * Returns the Internet Protocol (IP) port number of the interface on which
 437      * the request was received.
 438      *
 439      * @return an integer specifying the port number
 440      * @since 2.4
 441      */
 442     public int getLocalPort();
 443
 444     /**
 445      * @return TODO
 446      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 447      */
 448     public ServletContext getServletContext();
 449
 450     /**
 451      * @return TODO
 452      * @throws java.lang.IllegalStateException
 453      *             If async is not supported for this request
 454      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 455      */
 456     public AsyncContext startAsync() throws IllegalStateException;
 457
 458     /**
 459      * @param servletRequest
 460      * @param servletResponse
 461      * @return TODO
 462      * @throws java.lang.IllegalStateException
 463      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 464      */
 465     public AsyncContext startAsync(ServletRequest servletRequest,
 466             ServletResponse servletResponse) throws IllegalStateException;
 467
 468     /**
 469      * @return TODO
 470      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 471      */
 472     public boolean isAsyncStarted();
 473
 474     /**
 475      * @return TODO
 476      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 477      */
 478     public boolean isAsyncSupported();
 479
 480     /**
 481      * @return TODO
 482      * @throws java.lang.IllegalStateException
 483      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 484      */
 485     public AsyncContext getAsyncContext();
 486
 487     /**
 488      * @return TODO
 489      * @since Servlet 3.0 TODO SERVLET3 - Add comments
 490      */
 491     public DispatcherType getDispatcherType();
 492 }