Synopsis
Interface Name: javax.servlet.ServletRequest
Superinterface: None
Immediate Subinterfaces: javax.servlet.http.HttpServletRequest
Implemented By: None
Availability: Servlet API 1.0 and later
Description
A ServletRequest object encapsulates information about a single client request, including request parameters, request attributes, client locales, and an input stream for reading binary data from the request body. ServletRequest can be subclassed to provide additional protocol-specific information. HttpServletRequest, for instance, includes methods to manipulate HTTP headers.
Interface Declaration
public interface ServletRequest { // Methods public abstract Object getAttribute(String name); public abstract Enumeration getAttributeNames(); // New in 2.1 public abstract String getCharacterEncoding(); // New in 2.0 public abstract int getContentLength(); public abstract String getContentType(); public abstract ServletInputStream getInputStream() throws IOException; public abstract Locale getLocale(); // New in 2.2 public abstract Enumeration getLocales(); // New in 2.2 public abstract String getParameter(String name); public abstract Enumeration getParameterNames(); public abstract String[] getParameterValues(String name); public abstract String getProtocol(); public abstract BufferedReader getReader() throws IOException;// New in 2.0 public abstract String getRealPath(String path); // Deprecated public abstract String getRemoteAddr(); public abstract String getRemoteHost(); public abstract RequestDispatcher getRequestDispatcher(String path); // New public abstract String getScheme(); public abstract String getServerName(); public abstract int getServerPort(); public abstract boolean isSecure(); // New in 2.2 public abstract void removeAttribute(String name); // New in 2.2 public abstract void setAttribute(String name, Object o); // New in 2.1 } Methods
getAttribute()
public abstract Object getAttribute(String name)
- Description
-
Returns the value of the named request attribute as an Object or null if the attribute does not exist. Server-specific request attributes may be autoset by the servlet container to provide servlets with information above and beyond that provided for by the base Servlet API. Attributes can also be set programmatically by servlets as a way of passing information from one servlet to another when using a RequestDispatcher. Attribute names should follow the same convention as package names. The package names java.* and javax.* are reserved for use by the Java Software division of Sun Microsystems (formerly known as JavaSoft), and com.sun.* is reserved for use by Sun Microsystems. See your server's documentation for a list of its built-in attributes. Remember that servlets relying on server-specific attributes are not portable.
getAttributeNames()
public abstract Enumeration getAttributeNames()
- Description
-
Returns the names of all the current request attributes as an Enumeration of String objects. It returns an empty Enumeration if the request has no attributes. This method was introduced in Servlet API 2.1.
getCharacterEncoding()
public abstract String getCharacterEncoding()
- Description
-
Returns the charset encoding for the servlet's input stream or null if not known. This method was introduced in Servlet API 2.0.
getContentLength()
public abstract int getContentLength()
- Description
-
Returns the length, in bytes, of the content being sent via the input stream or -1 if the length is not known (such as when there is no data). Equivalent to the CGI variable CONTENT_LENGTH.
getContentType()
public abstract String getContentType()
- Description
-
Returns the media type of the content being sent via the input stream or null if the type is not known or there is no data. The same as the CGI variable CONTENT_TYPE.
getInputStream()
public abstract ServletInputStream getInputStream() throws IOException, IllegalStateException
- Description
-
Retrieves the input stream as a ServletInputStream object. ServletInputStream is a direct subclass of InputStream and can be treated identically to a normal InputStream, with the added ability to efficiently read input a line at a time into an array of bytes. This method should be used for reading binary input. It throws an IllegalStateException if getReader( ) has been called before on the request. The IllegalStateException does not need to be explicitly caught.
getLocale()
public abstract Locale getLocale()
- Description
-
Returns the client's preferred Locale, as extracted from the client's Accept-Language request header. If the client request does not provide an Accept-Language header, this method returns the default locale for the server. Use the com.oreilly.servlet.LocaleNegotiator class for more robust locale detection. This method was introduced in Servlet API 2.2.
getLocales()
public abstract Enumeration getLocales()
- Description
-
Returns an Enumeration of Locale objects indicating the locales that are acceptable to the client based on the Accept-Language header, from most preferred to least preferred. 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. Use the com.oreilly.servlet.LocaleNegotiator class for more robust locale detection. This method was introduced in Servlet API 2.2.
getParameter()
public abstract String getParameter(String name)
- Description
-
Returns the value of the named parameter as a String. Returns null if the parameter does not exist or an empty string if the parameter exists but has no value. The value is guaranteed to be in its normal, decoded form. If the parameter has multiple values, use the getParameterValues( ) method to retrieve an array of values. If this method is called on a parameter with multiple values, the value returned is the same as the first element in the array returned by getParameterValues( ). If the parameter information came in as encoded POST data, it may not be available if the POST data has already been manually read using the getReader( ) or getInputStream( ) methods. This method was deprecated momentarily in favor of getParameterValues( ), but thanks to an overwhelming flood of support from the developer community, it was restored in Servlet API 2.0.
getParameterNames()
public abstract Enumeration getParameterNames()
- Description
-
Returns all the parameter names as an Enumeration of String objects. It returns an empty Enumeration if the servlet has no parameters.
getParameterValues()
public abstract String[] getParameterValues(String name)
- Description
-
Returns all the values of the named parameter as an array of String objects or null if the parameter does not exist. A single value is returned in an array of length 1.
getProtocol()
public abstract String getProtocol()
- Description
-
Returns the name and version of the protocol used by the request as a String in the form protocol/major-version.minor-version. Equivalent to the CGI variable SERVER_PROTOCOL.
getReader()
public abstract BufferedReader getReader() throws IOException, IllegalStateException
- Description
-
This method retrieves the input stream as a BufferedReader object, which should be used for reading character-based input, since the reader translates charsets as appropriate. This method throws an IllegalStateException if getInputStream( ) has been called before on this same request. It throws an UnsupportedEncodingException if the character encoding of the input is unsupported or unknown. This method was introduced in Servlet API 2.0.
getRealPath()
public abstract String getRealPath(String path)
- Description
-
Returns the real filesystem path of any given "virtual path" or null if the translation cannot be performed. If the given path is / it returns the document root for the server. If the given path is the same as the one returned by getPathInfo( ), it returns the same real path as would be returned by getPathTranslated( ). There is no CGI counterpart. This method has been deprecated as of Servlet API 2.1 in favor of the getRealPath( ) method in ServletContext.
getRemoteAddr()
public abstract String getRemoteAddr()
- Description
-
Returns the IP address of the client machine as a String. This information comes from the socket connecting the server to the client, so the remote address may be that of a proxy server. It is the same as the CGI variable REMOTE_ADDR.
getRemoteHost()
public abstract String getRemoteHost()
- Description
-
Returns the name of the client host. This comes from the socket connecting the server to the client and may be the name of a proxy server. It is the same as the CGI variable REMOTE_HOST.
getRequestDispatcher()
public abstract RequestDispatcher getRequestDispatcher(String path)
- Description
-
Returns a RequestDispatcher capable of dispatching the request to the given path. A RequestDispatcher can be used to forward a request to the resource or to include the content of that resource into the current 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 for any reason. The difference between this method and the getRequestDispatcher( ) method in ServletContext is that this method can take a relative path. This method was introduced in Servlet API 2.2.
getScheme()
public abstract String getScheme()
- Description
-
This method returns the scheme used to make this request. Examples include http, https, and ftp, as well as the newer Java-specific schemes jdbc and rmi.
getServerName()
public abstract String getServerName()
- Description
-
Returns the name of the server that received the request. It is an attribute of the ServletRequest because it can change for different requests depending on how the client refers to the server. Similar to the CGI variable SERVER_NAME.
getServerPort()
public abstract int getServerPort()
- Description
-
Returns the port number on which this request was received. The same as the CGI variable SERVER_PORT.
isSecure()
public abstract boolean isSecure()
- Description
-
Returns whether this request was made using a secure channel, such as HTTPS. This method was introduced in Servlet API 2.2.
removeAttribute()
public abstract void removeAttribute(String name)
- Description
-
Removes the attribute with the given name from the request. Server-specific attributes generally cannot be removed. This method was introduced in Servlet API 2.2.
setAttribute()
public abstract void setAttribute(String name, Object o)
- Description
-
Binds an object under a given name in this request. Any existing binding with the same name is replaced. Request attributes most often are set as a way of passing information from one servlet to another when using a RequestDispatcher. Attribute names should follow the same convention as package names. The package names java.* and javax.* are reserved for use by the Java Software division of Sun Microsystems (formerly known as JavaSoft), and com.sun.* is reserved for use by Sun Microsystems. This method was introduced in Servlet API 2.1.
