/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package javax.servlet; import java.io.BufferedReader; import java.io.IOException; import java.util.Enumeration; import java.util.Locale; import java.util.Map; /** * Defines an object to provide client request information to a servlet. The * servlet container creates a ServletRequest object and passes it * as an argument to the servlet's service method. *

* A ServletRequest object provides data including parameter name * and values, attributes, and an input stream. Interfaces that extend * ServletRequest can provide additional protocol-specific data * (for example, HTTP data is provided by * {@link javax.servlet.http.HttpServletRequest}. * * @see javax.servlet.http.HttpServletRequest */ public interface ServletRequest { /** * Returns the value of the named attribute as an Object, or * null if no attribute of the given name exists. *

* Attributes can be set two ways. The servlet container may set attributes * to make available custom information about a request. For example, for * requests made using HTTPS, the attribute * javax.servlet.request.X509Certificate can be used to * retrieve information on the certificate of the client. Attributes can * also be set programmatically using {@link ServletRequest#setAttribute}. * This allows information to be embedded into a request before a * {@link RequestDispatcher} call. *

* Attribute names should follow the same conventions as package names. * Names beginning with java.* and javax.* are * reserved for use by the Servlet specification. Names beginning with * sun.*, com.sun.*, oracle.* and * com.oracle.*) are reserved for use by Oracle Corporation. * * @param name * a String specifying the name of the attribute * @return an Object containing the value of the attribute, or * null if the attribute does not exist */ public Object getAttribute(String name); /** * Returns an Enumeration containing the names of the * attributes available to this request. This method returns an empty * Enumeration if the request has no attributes available to * it. * * @return an Enumeration of strings containing the names of the * request's attributes */ public Enumeration getAttributeNames(); /** * Returns the name of the character encoding used in the body of this * request. This method returns null if the request does not * specify a character encoding * * @return a String containing the name of the character * encoding, or null if the request does not specify a * character encoding */ public String getCharacterEncoding(); /** * Overrides the name of the character encoding used in the body of this * request. This method must be called prior to reading request parameters * or reading input using getReader(). * * @param env * a String containing the name of the character * encoding. * @throws java.io.UnsupportedEncodingException * if this is not a valid encoding */ public void setCharacterEncoding(String env) throws java.io.UnsupportedEncodingException; /** * Returns the length, in bytes, of the request body and made available by * the input stream, or -1 if the length is not known. For HTTP servlets, * same as the value of the CGI variable CONTENT_LENGTH. * * @return an integer containing the length of the request body or -1 if the * length is not known or is greater than {@link Integer#MAX_VALUE} */ public int getContentLength(); /** * Returns the length, in bytes, of the request body and made available by * the input stream, or -1 if the length is not known. For HTTP servlets, * same as the value of the CGI variable CONTENT_LENGTH. * * @return a long integer containing the length of the request body or -1 if * the length is not known * @since Servlet 3.1 */ public long getContentLengthLong(); /** * Returns the MIME type of the body of the request, or null if * the type is not known. For HTTP servlets, same as the value of the CGI * variable CONTENT_TYPE. * * @return a String containing the name of the MIME type of the * request, or null if the type is not known */ public String getContentType(); /** * Retrieves the body of the request as binary data using a * {@link ServletInputStream}. Either this method or {@link #getReader} may * be called to read the body, not both. * * @return a {@link ServletInputStream} object containing the body of the * request * @exception IllegalStateException * if the {@link #getReader} method has already been called * for this request * @exception IOException * if an input or output exception occurred */ public ServletInputStream getInputStream() throws IOException; /** * Returns the value of a request parameter as a String, or * null if the parameter does not exist. Request parameters are * extra information sent with the request. For HTTP servlets, parameters * are contained in the query string or posted form data. *

* You should only use this method when you are sure the parameter has only * one value. If the parameter might have more than one value, use * {@link #getParameterValues}. *

* If you use this method with a multivalued parameter, the value returned * is equal to the first value in the array returned by * getParameterValues. *

* If the parameter data was sent in the request body, such as occurs with * an HTTP POST request, then reading the body directly via * {@link #getInputStream} or {@link #getReader} can interfere with the * execution of this method. * * @param name * a String specifying the name of the parameter * @return a String representing the single value of the * parameter * @see #getParameterValues */ public String getParameter(String name); /** * Returns an Enumeration of String objects * containing the names of the parameters contained in this request. If the * request has no parameters, the method returns an empty * Enumeration. * * @return an Enumeration of String objects, each * String containing the name of a request parameter; * or an empty Enumeration if the request has no * parameters */ public Enumeration getParameterNames(); /** * Returns an array of String objects containing all of the * values the given request parameter has, or null if the * parameter does not exist. *

* If the parameter has a single value, the array has a length of 1. * * @param name * a String containing the name of the parameter * whose value is requested * @return an array of String objects containing the parameter's * values * @see #getParameter */ public String[] getParameterValues(String name); /** * Returns a java.util.Map of the parameters of this request. Request * parameters are extra information sent with the request. For HTTP * servlets, parameters are contained in the query string or posted form * data. * * @return an immutable java.util.Map containing parameter names as keys and * parameter values as map values. The keys in the parameter map are * of type String. The values in the parameter map are of type * String array. */ public Map getParameterMap(); /** * Returns the name and version of the protocol the request uses in the form * protocol/majorVersion.minorVersion, for example, HTTP/1.1. For * HTTP servlets, the value returned is the same as the value of the CGI * variable SERVER_PROTOCOL. * * @return a String containing the protocol name and version * number */ public String getProtocol(); /** * Returns the name of the scheme used to make this request, for example, * http, https, or ftp. Different * schemes have different rules for constructing URLs, as noted in RFC 1738. * * @return a String containing the name of the scheme used to * make this request */ public String getScheme(); /** * Returns the host name of the server to which the request was sent. It is * the value of the part before ":" in the Host header value, * if any, or the resolved server name, or the server IP address. * * @return a String containing the name of the server */ public String getServerName(); /** * Returns the port number to which the request was sent. It is the value of * the part after ":" in the Host header value, if any, or the * server port where the client connection was accepted on. * * @return an integer specifying the port number */ public int getServerPort(); /** * Retrieves the body of the request as character data using a * BufferedReader. The reader translates the character data * according to the character encoding used on the body. Either this method * or {@link #getInputStream} may be called to read the body, not both. * * @return a BufferedReader containing the body of the request * @exception java.io.UnsupportedEncodingException * if the character set encoding used is not supported and * the text cannot be decoded * @exception IllegalStateException * if {@link #getInputStream} method has been called on this * request * @exception IOException * if an input or output exception occurred * @see #getInputStream */ public BufferedReader getReader() throws IOException; /** * Returns the Internet Protocol (IP) address of the client or last proxy * that sent the request. For HTTP servlets, same as the value of the CGI * variable REMOTE_ADDR. * * @return a String containing the IP address of the client * that sent the request */ public String getRemoteAddr(); /** * Returns the fully qualified name of the client or the last proxy that * sent the request. If the engine cannot or chooses not to resolve the * hostname (to improve performance), this method returns the dotted-string * form of the IP address. For HTTP servlets, same as the value of the CGI * variable REMOTE_HOST. * * @return a String containing the fully qualified name of the * client */ public String getRemoteHost(); /** * Stores an attribute in this request. Attributes are reset between * requests. This method is most often used in conjunction with * {@link RequestDispatcher}. *

* Attribute names should follow the same conventions as package names. * Names beginning with java.* and javax.* are * reserved for use by the Servlet specification. Names beginning with * sun.*, com.sun.*, oracle.* and * com.oracle.*) are reserved for use by Oracle Corporation. *
* If the object passed in is null, the effect is the same as calling * {@link #removeAttribute}.
* It is warned that when the request is dispatched from the servlet resides * in a different web application by RequestDispatcher, the * object set by this method may not be correctly retrieved in the caller * servlet. * * @param name * a String specifying the name of the attribute * @param o * the Object to be stored */ public void setAttribute(String name, Object o); /** * Removes an attribute from this request. This method is not generally * needed as attributes only persist as long as the request is being * handled. *

* Attribute names should follow the same conventions as package names. * Names beginning with java.* and javax.* are * reserved for use by the Servlet specification. Names beginning with * sun.*, com.sun.*, oracle.* and * com.oracle.*) are reserved for use by Oracle Corporation. * * @param name * a String specifying the name of the attribute to * remove */ public void removeAttribute(String name); /** * Returns the preferred Locale that the client will accept * content in, based on the Accept-Language header. If the client request * doesn't provide an Accept-Language header, this method returns the * default locale for the server. * * @return the preferred Locale for the client */ public Locale getLocale(); /** * Returns an Enumeration of Locale objects * indicating, in decreasing order starting with the preferred locale, the * locales that are acceptable to the client based on the Accept-Language * header. If the client request doesn't provide an Accept-Language header, * this method returns an Enumeration containing one * Locale, the default locale for the server. * * @return an Enumeration of preferred Locale * objects for the client */ public Enumeration getLocales(); /** * Returns a boolean indicating whether this request was made using a secure * channel, such as HTTPS. * * @return a boolean indicating if the request was made using a secure * channel */ public boolean isSecure(); /** * Returns a {@link RequestDispatcher} object that acts as a wrapper for the * resource located at the given path. A RequestDispatcher * object can be used to forward a request to the resource or to include the * resource in a response. The resource can be dynamic or static. *

* The pathname specified may be relative, although it cannot extend outside * the current servlet context. If the path begins with a "/" it is * interpreted as relative to the current context root. This method returns * null if the servlet container cannot return a * RequestDispatcher. *

* The difference between this method and * {@link ServletContext#getRequestDispatcher} is that this method can take * a relative path. * * @param path * a String specifying the pathname to the resource. * If it is relative, it must be relative against the current * servlet. * @return a RequestDispatcher object that acts as a wrapper for * the resource at the specified path, or null if the * servlet container cannot return a RequestDispatcher * @see RequestDispatcher * @see ServletContext#getRequestDispatcher */ public RequestDispatcher getRequestDispatcher(String path); /** * @param path The virtual path to be converted to a real path * @return {@link ServletContext#getRealPath(String)} * @deprecated As of Version 2.1 of the Java Servlet API, use * {@link ServletContext#getRealPath} instead. */ @SuppressWarnings("dep-ann") // Spec API does not use @Deprecated public String getRealPath(String path); /** * Returns the Internet Protocol (IP) source port of the client or last * proxy that sent the request. * * @return an integer specifying the port number * @since Servlet 2.4 */ public int getRemotePort(); /** * Returns the host name of the Internet Protocol (IP) interface on which * the request was received. * * @return a String containing the host name of the IP on which * the request was received. * @since Servlet 2.4 */ public String getLocalName(); /** * Returns the Internet Protocol (IP) address of the interface on which the * request was received. * * @return a String containing the IP address on which the * request was received. * @since Servlet 2.4 */ public String getLocalAddr(); /** * Returns the Internet Protocol (IP) port number of the interface on which * the request was received. * * @return an integer specifying the port number * @since Servlet 2.4 */ public int getLocalPort(); /** * @return TODO * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public ServletContext getServletContext(); /** * @return TODO * @throws IllegalStateException If async is not supported for this request * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public AsyncContext startAsync() throws IllegalStateException; /** * @param servletRequest The ServletRequest with which to initialise the * asynchronous context * @param servletResponse The ServletResponse with which to initialise the * asynchronous context * @return TODO * @throws IllegalStateException If async is not supported for this request * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public AsyncContext startAsync(ServletRequest servletRequest, ServletResponse servletResponse) throws IllegalStateException; /** * @return TODO * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public boolean isAsyncStarted(); /** * @return TODO * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public boolean isAsyncSupported(); /** * Get the current AsyncContext. * * @return The current AsyncContext * * @throws IllegalStateException if the request is not in asynchronous mode * (i.e. @link #isAsyncStarted() is {@code false}) * * @since Servlet 3.0 */ public AsyncContext getAsyncContext(); /** * @return TODO * @since Servlet 3.0 TODO SERVLET3 - Add comments */ public DispatcherType getDispatcherType(); }