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
9 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 package javax.servlet;
19 import java.io.BufferedReader;
20 import java.io.IOException;
21 import java.util.Enumeration;
22 import java.util.Locale;
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.
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}.
36 * @see javax.servlet.http.HttpServletRequest
38 public interface ServletRequest {
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.
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.
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.
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
64 public Object getAttribute(String name);
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
72 * @return an <code>Enumeration</code> of strings containing the names of the
73 * request's attributes
75 public Enumeration<String> getAttributeNames();
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
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
86 public String getCharacterEncoding();
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().
94 * a <code>String</code> containing the name of the character
96 * @throws java.io.UnsupportedEncodingException
97 * if this is not a valid encoding
99 public void setCharacterEncoding(String env)
100 throws java.io.UnsupportedEncodingException;
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.
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}
110 public int getContentLength();
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.
117 * @return a long integer containing the length of the request body or -1 if
118 * the length is not known
120 public long getContentLengthLong();
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.
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
130 public String getContentType();
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.
137 * @return a {@link ServletInputStream} object containing the body of the
139 * @exception IllegalStateException
140 * if the {@link #getReader} method has already been called
142 * @exception IOException
143 * if an input or output exception occurred
145 public ServletInputStream getInputStream() throws IOException;
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.
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}.
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>.
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.
167 * a <code>String</code> specifying the name of the parameter
168 * @return a <code>String</code> representing the single value of the
170 * @see #getParameterValues
172 public String getParameter(String name);
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>.
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
185 public Enumeration<String> getParameterNames();
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.
192 * If the parameter has a single value, the array has a length of 1.
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
201 public String[] getParameterValues(String name);
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
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
214 public Map<String, String[]> getParameterMap();
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>.
222 * @return a <code>String</code> containing the protocol name and version
225 public String getProtocol();
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.
232 * @return a <code>String</code> containing the name of the scheme used to
235 public String getScheme();
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.
242 * @return a <code>String</code> containing the name of the server
244 public String getServerName();
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.
251 * @return an integer specifying the port number
253 public int getServerPort();
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.
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
268 * @exception IOException
269 * if an input or output exception occurred
270 * @see #getInputStream
272 public BufferedReader getReader() throws IOException;
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>.
279 * @return a <code>String</code> containing the IP address of the client
280 * that sent the request
282 public String getRemoteAddr();
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>.
291 * @return a <code>String</code> containing the fully qualified name of the
294 public String getRemoteHost();
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}.
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.
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
315 * a <code>String</code> specifying the name of the attribute
317 * the <code>Object</code> to be stored
319 public void setAttribute(String name, Object o);
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
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.
333 * a <code>String</code> specifying the name of the attribute to
336 public void removeAttribute(String name);
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.
344 * @return the preferred <code>Locale</code> for the client
346 public Locale getLocale();
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.
356 * @return an <code>Enumeration</code> of preferred <code>Locale</code>
357 * objects for the client
359 public Enumeration<Locale> getLocales();
362 * Returns a boolean indicating whether this request was made using a secure
363 * channel, such as HTTPS.
365 * @return a boolean indicating if the request was made using a secure
368 public boolean isSecure();
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.
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>.
382 * The difference between this method and
383 * {@link ServletContext#getRequestDispatcher} is that this method can take
387 * a <code>String</code> specifying the pathname to the resource.
388 * If it is relative, it must be relative against the current
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
396 public RequestDispatcher getRequestDispatcher(String path);
399 * @deprecated As of Version 2.1 of the Java Servlet API, use
400 * {@link ServletContext#getRealPath} instead.
402 @SuppressWarnings("dep-ann")
403 // Spec API does not use @Deprecated
404 public String getRealPath(String path);
407 * Returns the Internet Protocol (IP) source port of the client or last
408 * proxy that sent the request.
410 * @return an integer specifying the port number
413 public int getRemotePort();
416 * Returns the host name of the Internet Protocol (IP) interface on which
417 * the request was received.
419 * @return a <code>String</code> containing the host name of the IP on which
420 * the request was received.
423 public String getLocalName();
426 * Returns the Internet Protocol (IP) address of the interface on which the
427 * request was received.
429 * @return a <code>String</code> containing the IP address on which the
430 * request was received.
433 public String getLocalAddr();
436 * Returns the Internet Protocol (IP) port number of the interface on which
437 * the request was received.
439 * @return an integer specifying the port number
442 public int getLocalPort();
446 * @since Servlet 3.0 TODO SERVLET3 - Add comments
448 public ServletContext getServletContext();
452 * @throws java.lang.IllegalStateException
453 * If async is not supported for this request
454 * @since Servlet 3.0 TODO SERVLET3 - Add comments
456 public AsyncContext startAsync() throws IllegalStateException;
459 * @param servletRequest
460 * @param servletResponse
462 * @throws java.lang.IllegalStateException
463 * @since Servlet 3.0 TODO SERVLET3 - Add comments
465 public AsyncContext startAsync(ServletRequest servletRequest,
466 ServletResponse servletResponse) throws IllegalStateException;
470 * @since Servlet 3.0 TODO SERVLET3 - Add comments
472 public boolean isAsyncStarted();
476 * @since Servlet 3.0 TODO SERVLET3 - Add comments
478 public boolean isAsyncSupported();
482 * @throws java.lang.IllegalStateException
483 * @since Servlet 3.0 TODO SERVLET3 - Add comments
485 public AsyncContext getAsyncContext();
489 * @since Servlet 3.0 TODO SERVLET3 - Add comments
491 public DispatcherType getDispatcherType();