HttpServletRequest Class

Used to read raw bytes sent from the client to the server. Assumes the data is a valid HTTP/1.1 request. Supports both http and https (ssl/tls). This class implements the javax.servlet.http.HttpServletRequest interface defined in Version 2.5 of the Java Servlet API.

Constructors

public HttpServletRequest( javax.servlet.http.HttpServletRequest request, javaxt.http.servlet.HttpServlet servlet )

Methods

authenticate( ) returns void
Used to authenticate a client request. Authentication is performed by an Authenticator. If no Authenticator is defined or if the Authenticator fails to authenticate the client, this method throws a ServletException.
getAsyncContext( ) returns javax.servlet.AsyncContext
getAttribute( String name ) returns Object
Returns the value of a given attribute. Returns null if no attribute of the given name exists.

Attributes contain custom information about a request. Attributes are set programatically using the setAttribute() method and are typically used in conjunction with a RequestDispatcher. Attribute names should follow the same conventions as package names. The servlet specification reserves names matching "java.*", "javax.*", and "sun.*".

getAttributeNames( ) returns java.util.Enumeration
Returns an Enumeration containing the names of the attributes associated with this request. Returns an empty Enumeration if the request has no attributes associated with it. See getAttribute() and setAttribute() for more information.
getAuthType( ) returns String
Returns the authentication scheme used to authenticate clients (e.g. "BASIC", "DIGEST", "CLIENT_CERT", etc). This value is retrieved from an Authenticator and does not necessarily correspond to the "Authorization" request header. If an Authenticator is not used to secure the servlet, a null is returned.
getBody( ) returns byte[]
Returns the body of the http request as a byte array. Reads all remaining bytes from the socket. Therefore, you should only call this method once. Subsequent calls will return an empty array.
getCharacterEncoding( ) returns String
Returns the name of the character encoding used in the body of this request as specified in the "Content-Type" in the request header (e.g. "UTF-8"). Returns a null if the request does not specify a character encoding.
getContentLength( ) returns int
Returns the "Content-Length" specified in the http request header.
getContentType( ) returns String
Returns the "Content-Type" defined in the request header. Returns null if the "Content-Type" is not defined.
getContextPath( ) returns String
Returns a string in the requested URL that represents the servlet context. This is typically defined in the META-INF/context.xml file in Java EE web applications. For example, if a web application is called "WebApplication", the context path might be "/WebApplication". In this case, a requested URL will include the context path like this:
http://localhost:8080/WebApplication/MyServlet/?abc=123

The context path always comes first in a request URL. The path starts with a "/" character but does not end with a "/" character. For servlets in the default (root) context, this method returns "".

Note that this server does not currently support the container concept where multiple servlets are managed by a servlet container. Instead, we have a single servlet that processes all web requests and can dispatch the requests to other servlets. Therefore, to retrieve a "context path" developers must explicitely set the "context path" in the servlet and implement logic to generate/process the URLs accordingly.

getCookies( ) returns javaxt.http.servlet.Cookie[]
Returns an array containing all of the Cookie objects the client sent with this request. This method returns null if no cookies were sent.
getCredentials( ) returns String[]
Returns an array representing the client credentials associated with this request. The first element in the array represents the username and the second element represents the password.

Credentials are retrieved from an Authenticator. If no Authenticator is defined or if the Authenticator fails to parse the credentials, this method returns a null.

getDateHeader( String name ) returns long
Returns the value of the specified request header as a long representing the number of milliseconds since January 1, 1970 GMT. If the request did not have a header of the specified name, this method returns -1. If the header can't be converted to a date, the method throws an IllegalArgumentException.
nameA String specifying the header name (e.g. "If-Modified-Since"). The header name is case insensitive.
getDispatcherType( ) returns javax.servlet.DispatcherType
getFormInputs( ) returns javaxt.http.servlet.HttpServletRequest.FormIterator
Returns form elements in the body of the http request as an iterator. Reads data from the client on-demand, meaning form data will only be retrieved from the client when calling Iterator.next(). This is potentially more memory efficient than calling getBody() and parsing the entire byte array. This is especially true when processing "multipart/form-data" with large amounts of binary data (e.g. uploaded files). Please see the FormInput.getInputStream() or FormInput.toFile() methods for more information on handling large binary streams.

Here's a simple example of how to iterate through form data using the getFormInputs() method. Note how easy it is to identify an uploaded file and save it to disk.

        java.util.Iterator<FormInput> it = request.getFormInputs();
        while (it.hasNext()){
            FormInput input = it.next();
            String name = input.getName();
            FormValue value = input.getValue();

            if (input.isFile()){
                value.toFile(new java.io.File("/temp/" + input.getFileName()));
                System.out.println(name + ": <FILE>");
            }
            else{
                System.out.println(name + ": " + value);
            }
        }
   
Note that the form iterator reads data directly from the socket connection. Therefore, you should only call this method once.

More information on HTML form data can be found here:
http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4

getHeader( String name ) returns String
Returns the value of the specified request header as a String. If the request did not include a header of the specified name, this method returns null. If there are multiple headers with the same name, this method returns the first head in the request. The header name is case insensitive.
nameA String specifying the header name (e.g. "Content-Encoding") The header name is case insensitive.
getHeaderNames( ) returns java.util.Enumeration
Returns an enumeration of all the header names this request contains. If the request has no headers, this method returns an empty enumeration.
getHeaders( String name ) returns java.util.Enumeration
Returns all the values of the specified request header as an Enumeration. If the request did not include any headers of the specified name, this method returns an empty Enumeration.
nameA String specifying the header name (e.g. "Accept-Language"). The header name is case insensitive.
getHost( ) returns String
getHttpVersion( ) returns String
Returns the HTTP version number passed in as part of the request (e.g. "1.0", "1.1", etc).
getInputStream( ) returns javaxt.http.servlet.ServletInputStream
Returns the body of the http request as an input stream. Automatically decrypts the body if the data is SSL/TLS encrypted. Example:
        java.io.InputStream inputStream = request.getInputStream();
        byte[] b = new byte[1024];
        int x=0;
        while ( (x = inputStream.read(b)) != -1) {
            //Do something! Example: outputStream.write(b,0,x);
        }
        inputStream.close();
   
getIntHeader( String name ) returns int
Returns the value of the specified request header as an int. If the request does not have a header of the specified name, this method returns -1. If the header cannot be converted to an integer, this method throws a NumberFormatException.
nameA String specifying the header name (e.g. "Content-Length"). The header name is case insensitive.
getLocalAddr( ) returns String
Returns the Internet Protocol (IP) address of the interface on which the request was received.
getLocale( ) returns java.util.Locale
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.
getLocales( ) returns java.util.Enumeration
Returns an Enumeration of Locale objects indicating the locales that are acceptable to the client based on the Accept-Language header. The list of Locales is ordered, starting with the preferred locale. 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.
getLocalName( ) returns String
Returns the host name of the Internet Protocol (IP) interface on which the request was received.
getLocalPort( ) returns int
Returns the Internet Protocol (IP) port number of the interface on which the request was received.
getMethod( ) returns String
Returns the method specified in the first line of the request (e.g. GET, POST, PUT, HEAD, etc). Note that the method is always returned in uppercase.
getParameter( String key ) returns String
Used to retrieve the value of a specific variable supplied in the query string. Does NOT retrieve or parse posted data from form data. Use the getForm() method instead.
keyParameter name. Performs a case insensitive search for the keyword.
getParameterMap( ) returns java.util.Map
Returns an immutable java.util.Map containing parameters found in the query string. The keys in the parameter map are of type String. The values in the parameter map are of type String array.

Note that this method does NOT retrieve or parse posted data from form data. Use the getForm() method instead.

getParameterNames( ) returns java.util.Enumeration
Returns an Enumeration of String objects containing the names of the parameters contained in the query string. If the request has no parameters, the method returns an empty Enumeration.

Note that this method does NOT retrieve or parse posted data from form data. Use the getForm() method instead.

getParameterValues( String name ) returns String[]
Returns an array containing all of the values for a given query string parameter or null if the parameter does not exist.

Note that this method does NOT retrieve or parse posted data from form data. Use the getForm() method instead.

getPath( ) returns String
Returns the requested path and querystring. This usually corresponds to the first line of the request header. Example:
GET /index.html?abc=123 HTTP/1.1
If the server is acting as a proxy, the first line may include a full url. In this case, use the getURL() method to retrieve the original path.
getPathInfo( ) returns String
Returns any extra path information associated with the URL the client sent when it made this request. The extra path information follows the servlet path but precedes the query string and will start with a "/" character. Consider this example:
http://localhost:8080/MyServlet/Extra/Path/?abc=123
In this example, "/MyServlet" is the servlet path and this method will return "/Extra/Path/" as the extra path. If no extra path is found, this method will return a null.
getPathTranslated( ) returns String
Returns any extra path information after the servlet name but before the query string, and translates it to a real path. If the URL does not have any extra path information, or if the servlet container cannot translate the virtual path to a real path for any reason, this method returns a null.
getPort( ) returns int
getProtocol( ) returns String
Returns the name and version of the protocol the request uses in the form protocol/majorVersion.minorVersion (e.g. "HTTP/1.1").
getQueryString( ) returns String
Returns the url query string. Returns null if one does not exist.
getReader( ) returns java.io.BufferedReader
Returns a BufferedReader used to process the body of the http request. Automatically decrypts the body if the data is SSL/TLS encrypted. Either this method or getInputStream() may be called to read the body, but not both.
getRemoteAddr( ) returns String
Returns the IP address of the client that sent the request.
getRemoteHost( ) returns String
Returns the hostname of the client that sent the request.
getRemotePort( ) returns int
Returns the port of the client that sent the request.
getRemoteUser( ) returns String
Returns the login of the user making this request, if the user has been authenticated, or null if the user has not been authenticated.
getRequestDispatcher( String path ) returns Object
This method is supposed to return a RequestDispatcher object that can be used to forward a request to the resource or to include the resource in a response. This server does not currently support RequestDispatcher so this method returns a null.
getRequestedSessionId( ) returns String
Returns the session ID specified by the client ("JSESSIONID" cookie). If the client did not specify a session ID, this method returns null. Use the isRequestedSessionIdValid() method to verify whether the session ID is valid.
getRequestURI( ) returns String
Returns the part of this request's URL from the protocol name up to the query string in the first line of the HTTP request. The web container does not decode this String For example:
First line of HTTP request Returned Value
POST /some/path.html HTTP/1.1/some/path.html
GET http://foo.bar/a.html HTTP/1.0 /a.html
HEAD /xyz?a=b HTTP/1.1/xyz

To reconstruct an URL with a scheme and host, use {@link HttpUtils#getRequestURL}.

getRequestURL( ) returns StringBuffer
Reconstructs the URL the client used to make the request. The returned URL contains a protocol, server name, port number, and server path, but it does not include query string parameters.
getScheme( ) returns String
Returns the name of the scheme used to make this request (e.g. "http").
getServerName( ) returns String
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, header value, if any, or the resolved server name, or the server IP address.
getServerPort( ) returns int
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.
getServletPath( ) returns String
Returns a string in the requested URL that represents the servlet path. This path starts with a "/" character and includes either the servlet name or a path to the servlet, but does not include any extra path information or a query string. For example, consider the following URL:
http://localhost:8080/WebApplication/MyServlet/?abc=123

In this example, the context path is "/WebApplication" and "/MyServlet" is the servlet path.

Note that this server does not require a URL "Pattern" to be defined for for individual servlets. Instead, we have a single servlet that processes all web requests and can dispatch the requests to other servlets. Therefore, to retrieve a "servlet path" developers must explicitely set the servlet path in the servlet and implement logic to process the URLs accordingly.

getSession( ) returns javaxt.http.servlet.HttpSession
Returns the current session associated with this request, or if the request does not have a session, creates one.
getSession( boolean create ) returns javaxt.http.servlet.HttpSession
Returns the current HttpSession associated with this request or, if there is no current session and create is true, returns a new session.
getURL( ) returns java.net.URL
Used to retrieve the requested url defined in the header.
getUserPrincipal( ) returns java.security.Principal
Returns a java.security.Principal object containing the name of the current authenticated user. User Principals are resolved by an Authenticator. If no Authenticator is defined, or if the user has not been authenticated, the method returns a null.
isAsyncStarted( ) returns boolean
isAsyncSupported( ) returns boolean
isKeepAlive( ) returns boolean
Used to determine whether the Connection attribute is set to Keep-Alive.
isRequestedSessionIdFromCookie( ) returns boolean
Checks whether the requested session ID came in as a cookie.
isRequestedSessionIdFromURL( ) returns boolean
Checks whether the requested session ID came in as part of the request URL.
isRequestedSessionIdValid( ) returns boolean
Checks whether the requested session ID is still valid. Returns true if this request has an id for a valid session in the current session context.
isSecure( ) returns boolean
Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS.
isUserInRole( String role ) returns boolean
Returns a boolean indicating whether the authenticated user is included in the specified "role". Roles and role membership are often managed by an Authenticator. If no Authenticator is defined, or if the user is not authenticated, or if no role is defined for the user, the method returns false.
removeAttribute( String name ) returns void
Removes an attribute associated with this request. See getAttribute() and setAttribute() for more information.
setAttribute( String name, Object o ) returns void
Used to add, update, or delete an attribute associated with this request. Attributes contain custom information about a request and are typically used in conjunction with a RequestDispatcher. If the object passed in is null, the effect is the same as calling removeAttribute().
setCharacterEncoding( String env ) returns void
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().
startAsync( ) returns javax.servlet.AsyncContext
startAsync( javax.servlet.ServletRequest sr, javax.servlet.ServletResponse sr1 ) returns javax.servlet.AsyncContext
toString( ) returns String
Returns the full HTTP Request Header.