javax.servlet.ServletRequest Maven / Gradle / Ivy
/*
* JBoss, Home of Professional Open Source.
* Copyright 2007, Red Hat Middleware LLC, and individual contributors
* as indicated by the @author tags. See the copyright.txt file in the
* distribution for a full listing of individual contributors.
*
* This is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of
* the License, or (at your option) any later version.
*
* This software is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this software; if not, write to the Free
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
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}.
*
* @author Various
* @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 programatically 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. This
* specification reserves names matching java.*,
* javax.*, and sun.*.
*
* @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(). Otherwise, it has no effect.
*
* @param env
* String containing the name of the character
* encoding.
* @throws java.io.UnsupportedEncodingException
* if this ServletRequest is still in a state where a character
* encoding may be set, but the specified encoding is invalid
*/
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
*/
public int getContentLength();
/**
* 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 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.*, javax.*, and
* com.sun.*, are reserved for use by Sun Microsystems.
* 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.*, javax.*, and
* com.sun.*, are reserved for use by Sun Microsystems.
*
* @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);
/**
* @deprecated As of Version 2.1 of the Java Servlet API, use
* {@link ServletContext#getRealPath} instead.
*/
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 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 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 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 2.4
*/
public int getLocalPort();
}