javax.servlet
Interface ServletRequest

All Known Subinterfaces:
HttpServletRequest

public abstract interface ServletRequest

Defines an object that a servlet engine uses to give a servlet information about a client request.

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 HttpServletRequest. This interface and the interfaces that descend from it provide the servlet's only access to this data.

A servlet request is a Multipurpose Internet Mail Extension (MIME) body request, and the response is a MIME body response. MIME bodies are either text or binary data. When they are text,including character encodings, use the getReader method. When they are binary data, use getInputStream. Multipart MIME bodies are treated as binary data.

Version:
$Version$
Author:
Various
See Also:
HttpServletRequest

Method Summary
 java.lang.Object getAttribute(java.lang.String name)
          Returns the value of the named attribute as an Object.
 java.util.Enumeration getAttributeNames()
          Returns an Enumeration containing the names of the attributes available to this request.
 java.lang.String getCharacterEncoding()
          Returns the name of the character encoding style used in this request.
 int getContentLength()
          Returns the length, in bytes, of the content contained in the request and sent by way of the input stream or -1 if the length is not known.
 java.lang.String getContentType()
          Returns the MIME type of the content of the request, or null if the type is not known.
 ServletInputStream getInputStream()
          Retrieves binary data from the body of the request as a ServletInputStream, which gives you the ability to read one line at a time.
 java.lang.String getParameter(java.lang.String name)
          Returns the value of a request parameter as a String, or null if the parameter does not exist.
 java.util.Enumeration getParameterNames()
          Returns an Enumeration of String objects containing the names of the parameters contained in this request.
 java.lang.String[] getParameterValues(java.lang.String name)
          Returns an array of String objects containing all of the values the given request parameter has, or null if the parameter does not exist.
 java.lang.String getProtocol()
          Returns the name and version of the protocol the request uses in the form protocol/majorVersion.minorVersion, for example, HTTP/1.1.
 java.io.BufferedReader getReader()
          Returns the body of the request as a BufferedReader that translates character set encodings.
 java.lang.String getRealPath(java.lang.String path)
          Deprecated. As of Version 2.1 of the Java Servlet API, use ServletContext.getRealPath(java.lang.String) instead.
 java.lang.String getRemoteAddr()
          Returns the Internet Protocol (IP) address of the client that sent the request.
 java.lang.String getRemoteHost()
          Returns the fully qualified name of the client that sent the request.
 java.lang.String getScheme()
          Returns the name of the scheme used to make this request, for example, http, https, or ftp.
 java.lang.String getServerName()
          Returns the host name of the server that received the request.
 int getServerPort()
          Returns the port number on which this request was received.
 void setAttribute(java.lang.String key, java.lang.Object o)
          Stores an attribute in the context of this request.
 

Method Detail

getAttribute

public java.lang.Object getAttribute(java.lang.String name)
Returns the value of the named attribute as an Object. This method allows the servlet engine to give the servlet custom information about a request. This method returns null if no attribute of the given name exists.

Attribute names should follow the same conventions as package names. This specification reserves names matching java.*, javax.*, and sun.*.

Parameters:
name - a String specifying the name of the attribute
Returns:
an Object containing the value of the attribute, or null if the attribute does not exist

getAttributeNames

public java.util.Enumeration getAttributeNames()
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.
Returns:
an Enumeration of strings containing the names of the request's attributes

getCharacterEncoding

public java.lang.String getCharacterEncoding()
Returns the name of the character encoding style used in this request. This method returns null if the request does not use character encoding.
Returns:
a String containing the name of the chararacter encoding style, or null if the request does not use character encoding

getContentLength

public int getContentLength()
Returns the length, in bytes, of the content contained in the request and sent by way of the input stream or -1 if the length is not known. Same as the value of the CGI variable CONTENT_LENGTH.
Returns:
an integer containing the length of the content in the request or -1 if the length is not known

getContentType

public java.lang.String getContentType()
Returns the MIME type of the content of the request, or null if the type is not known. Same as the value of the CGI variable CONTENT_TYPE.
Returns:
a String containing the name of the MIME type of the request, or -1 if the type is not known

getInputStream

public ServletInputStream getInputStream()
                                  throws java.io.IOException
Retrieves binary data from the body of the request as a ServletInputStream, which gives you the ability to read one line at a time.
Returns:
a ServletInputStream object containing the body of the request
Throws:
IllegalStateException - if the getReader() method has already been called for this request
java.io.IOException - if an input or output exception occurred

getParameter

public java.lang.String getParameter(java.lang.String name)
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.

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 getParameterValues(java.lang.String).

If you use this method with a multivalued parameter, the servlet engine determines the return value.

Parameters:
name - a String specifying the name of the parameter
Returns:
a String representing the single value of the parameter
See Also:
getParameterValues(java.lang.String)

getParameterNames

public java.util.Enumeration getParameterNames()
Returns an Enumeration of String objects containing the names of the parameters contained in this request. If the request has no parameters or if the input stream is empty, returns an empty Enumeration. The input stream is empty when all the data returned by getInputStream() has been read.
Returns:
an Enumeration of String objects, each String containing the name of a request parameter; or an empty Enumeration if the request has no parameters

getParameterValues

public java.lang.String[] getParameterValues(java.lang.String name)
Returns an array of String objects containing all of the values the given request parameter has, or null if the parameter does not exist. For example, in an HTTP servlet, this method returns an array of String objects containing the values of a query string or posted form.

If the parameter has a single value, the array has a length of 1.

Parameters:
name - a String containing the name of the parameter whose value is requested
Returns:
an array of String objects containing the parameter's values
See Also:
getParameter(java.lang.String)

getProtocol

public java.lang.String getProtocol()
Returns the name and version of the protocol the request uses in the form protocol/majorVersion.minorVersion, for example, HTTP/1.1. The value returned is the same as the value of the CGI variable SERVER_PROTOCOL.
Returns:
a String containing the protocol name and version number

getScheme

public java.lang.String getScheme()
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.

You can reconstruct the URL used to make this request by using this scheme, the server name and port, the pathname to the Web page on the server (also known as the Universal Resource Identifier), and the query string..

Returns:
a String containing the name of the scheme used to make this request

getServerName

public java.lang.String getServerName()
Returns the host name of the server that received the request. Same as the value of the CGI variable SERVER_NAME.
Returns:
a String containing the name of the server to which the request was sent

getServerPort

public int getServerPort()
Returns the port number on which this request was received. Same as the value of the CGI variable SERVER_PORT.
Returns:
an integer specifying the port number

getReader

public java.io.BufferedReader getReader()
                                 throws java.io.IOException
Returns the body of the request as a BufferedReader that translates character set encodings.
Returns:
a BufferedReader containing the body of the request
Throws:
java.io.UnsupportedEncodingException - if the character set encoding used is not supported and the text cannot be decoded
IllegalStateException - if getInputStream() method has been called on this request
java.io.IOException - if an input or output exception occurred
See Also:
getInputStream()

getRemoteAddr

public java.lang.String getRemoteAddr()
Returns the Internet Protocol (IP) address of the client that sent the request. Same as the value of the CGI variable REMOTE_ADDR.
Returns:
a String containing the IP address of the client that sent the request

getRemoteHost

public java.lang.String getRemoteHost()
Returns the fully qualified name of the client that sent the request. Same as the value of the CGI variable REMOTE_HOST.
Returns:
a String containing the fully qualified name of the client

setAttribute

public void setAttribute(java.lang.String key,
                         java.lang.Object o)
Stores an attribute in the context of this request. Attributes are reset between requests.

Attribute names should follow the same conventions as package names. Names beginning with java.*, javax.*, and com.sun.*, are reserved for use by Sun Microsystems.

Parameters:
key - a String specifying the name of the attribute
o - an Object containing the context of the request
Throws:
IllegalStateException - if the specified attribute already has a value

getRealPath

public java.lang.String getRealPath(java.lang.String path)
Deprecated. As of Version 2.1 of the Java Servlet API, use ServletContext.getRealPath(java.lang.String) instead.