javax.servlet
Interface ServletRequest

All Known Subinterfaces:

HttpServletRequest

public abstract interface ServletRequest

Defines a servlet engine generated object that enables a servlet to get information about a client request.

Some of the data provided by the ServletRequest object includes parameter names and values, attributes, and an input stream. Subclasses of ServletRequest can provide additional protocol-specific data. For example, HTTP data is provided by the interface HttpServletRequest, which extends ServletRequest. This framework provides the servlet's only access to this data.

MIME bodies are either text or binary data. Use getReader to handle text, including the character encodings. The getInputStream call should be used to handle binary data. Multipart MIME bodies are treated as binary data, since the headers are US-ASCII data.

See Also:

HttpServletRequest

Method Summary

java.lang.Object	getAttribute(java.lang.String name) Returns the value of the named attribute of this request.
java.util.Enumeration	getAttributeNames() Returns an enumeration of attribute names contained in this request.
java.lang.String	getCharacterEncoding() Returns the character set encoding for the input of this request.
int	getContentLength() Returns the size of the request entity data, or -1 if not known.
java.lang.String	getContentType() Returns the Internet Media (MIME) Type of the request entity data, or null if not known.
ServletInputStream	getInputStream() Returns an input stream for reading binary data in the request body.
java.lang.String	getParameter(java.lang.String name) Returns a string containing the lone value of the specified parameter, or null if the parameter does not exist.
java.util.Enumeration	getParameterNames() Returns the parameter names for this request as an enumeration of strings, or an empty enumeration if there are no parameters or the input stream is empty.
java.lang.String[]	getParameterValues(java.lang.String name) Returns the values of the specified parameter for the request as an array of strings, or null if the named parameter does not exist.
java.lang.String	getProtocol() Returns the protocol and version of the request as a string of the form <protocol>/<major version>.<minor version>.
java.io.BufferedReader	getReader() Returns a buffered reader for reading text in the request body.
java.lang.String	getRealPath(java.lang.String path) Deprecated. This method has been deprecated in preference to the same method found in the ServletContext interface.
java.lang.String	getRemoteAddr() Returns the IP address of the agent that sent the request.
java.lang.String	getRemoteHost() Returns the fully qualified host name of the agent that sent the request.
java.lang.String	getScheme() Returns the scheme of the URL used in 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) This method stores an attribute in the request context; these attributes will be reset between requests.

Method Detail

getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Returns the value of the named attribute of this request. This method may return null if the attribute does not exist. This method allows access to request information not already provided by other methods in this interface or data that was placed in the request object by other server components. Attribute names should follow the same convention as package names. Names matching java.*, javax.*, and sun.* are reserved for definition by this specification or by the reference implementation.

Parameters:

name - the name of the attribute whose value is required

getAttributeNames

public java.util.Enumeration getAttributeNames()

Returns an enumeration of attribute names contained in this request.

getCharacterEncoding

public java.lang.String getCharacterEncoding()

Returns the character set encoding for the input of this request. This method may return null if no character encoding is defined for this request body.

getContentLength

public int getContentLength()

Returns the size of the request entity data, or -1 if not known. Same as the CGI variable CONTENT_LENGTH.

getContentType

public java.lang.String getContentType()

Returns the Internet Media (MIME) Type of the request entity data, or null if not known. Same as the CGI variable CONTENT_TYPE.

getInputStream

public ServletInputStream getInputStream()
                                  throws java.io.IOException

Returns an input stream for reading binary data in the request body.

Throws:

IllegalStateException - if getReader has been called on this same request.

java.io.IOException - on other I/O related errors.

See Also:

getReader

getParameter

public java.lang.String getParameter(java.lang.String name)

Returns a string containing the lone value of the specified parameter, or null if the parameter does not exist. For example, in an HTTP servlet this method would return the value of the specified query string parameter. Servlet writers should use this method only when they are sure that there is only one value for the parameter. If the parameter has (or could have) multiple values, servlet writers should use getParameterValues. If a multiple valued parameter name is passed as an argument, the return value is implementation dependent.

Parameters:

name - the name of the parameter whose value is required.

See Also:

getParameterValues(java.lang.String)

getParameterNames

public java.util.Enumeration getParameterNames()

Returns the parameter names for this request as an enumeration of strings, or an empty enumeration if there are no parameters or the input stream is empty. The input stream would be empty if all the data had been read from the stream returned by the method getInputStream.

getParameterValues

public java.lang.String[] getParameterValues(java.lang.String name)

Returns the values of the specified parameter for the request as an array of strings, or null if the named parameter does not exist. For example, in an HTTP servlet this method would return the values of the specified query string or posted form as an array of strings.

Parameters:

name - the name of the parameter whose value is required.

See Also:

getParameter(java.lang.String)

getProtocol

public java.lang.String getProtocol()

Returns the protocol and version of the request as a string of the form <protocol>/<major version>.<minor version>. Same as the CGI variable SERVER_PROTOCOL.

getScheme

public java.lang.String getScheme()

Returns the scheme of the URL used in this request, for example "http", "https", or "ftp". Different schemes have different rules for constructing URLs, as noted in RFC 1738. The URL used to create a request may be reconstructed using this scheme, the server name and port, and additional information such as URIs.

getServerName

public java.lang.String getServerName()

Returns the host name of the server that received the request. Same as the CGI variable SERVER_NAME.

getServerPort

public int getServerPort()

Returns the port number on which this request was received. Same as the CGI variable SERVER_PORT.

getReader

public java.io.BufferedReader getReader()
                                 throws java.io.IOException

Returns a buffered reader for reading text in the request body. This translates character set encodings as appropriate.

Throws:

java.io.UnsupportedEncodingException - if the character set encoding is unsupported, so the text can't be correctly decoded.

IllegalStateException - if getInputStream has been called on this same request.

java.io.IOException - on other I/O related errors.

See Also:

getInputStream

getRemoteAddr

public java.lang.String getRemoteAddr()

Returns the IP address of the agent that sent the request. Same as the CGI variable REMOTE_ADDR.

getRemoteHost

public java.lang.String getRemoteHost()

Returns the fully qualified host name of the agent that sent the request. Same as the CGI variable REMOTE_HOST.

setAttribute

public void setAttribute(java.lang.String key,
                         java.lang.Object o)

This method stores an attribute in the request context; these attributes will be reset between requests. Attribute names should follow the same convention as package names.

The package (and hence attribute) names beginning with java.*, and javax.* are reserved for use by Javasoft. Similarly, com.sun.* is reserved for use by Sun Microsystems.

Parameters:

key - a String specifying the name of the attribute

o - a context object stored with the key.

Throws:

IllegalStateException - if the named attribute already has a value.

getRealPath

public java.lang.String getRealPath(java.lang.String path)

Deprecated. This method has been deprecated in preference to the same method found in the ServletContext interface.

Applies alias rules to the specified virtual path and returns the corresponding real path, or null if the translation can not be performed for any reason. For example, an HTTP servlet would resolve the path using the virtual docroot, if virtual hosting is enabled, and with the default docroot otherwise. Calling this method with the string "/" as an argument returns the document root.

Parameters:

path - the virtual path to be translated to a real path