/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package jakarta.servlet;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.nio.charset.Charset;
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
* <code>ServletRequest</code> object and passes it as an argument to the servlet's <code>service</code> method.
* <p>
* A <code>ServletRequest</code> object provides data including parameter name and values, attributes, and an input
* stream. Interfaces that extend <code>ServletRequest</code> can provide additional protocol-specific data (for
* example, HTTP data is provided by {@link jakarta.servlet.http.HttpServletRequest}).
*
* @see jakarta.servlet.http.HttpServletRequest
*/
public interface ServletRequest {
/**
* Returns the value of the named attribute as an <code>Object</code>, or <code>null</code> if no attribute of the
* given name exists.
* <p>
* 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
* <code>jakarta.servlet.request.X509Certificate</code> can be used to retrieve information on the certificate of
* the client. Attributes can also be set programmatically using {@link ServletRequest#setAttribute}. This allows
* information to be embedded into a request before a {@link RequestDispatcher} call.
* <p>
* Attribute names should follow the same conventions as package names. Names beginning with <code>jakarta.*</code>
* are reserved for use by the Jakarta EE platform.
*
* @param name a <code>String</code> specifying the name of the attribute
*
* @return an <code>Object</code> containing the value of the attribute, or <code>null</code> if the attribute does
* not exist
*/
Object getAttribute(String name);
/**
* Returns an <code>Enumeration</code> containing the names of the attributes available to this request. This method
* returns an empty <code>Enumeration</code> if the request has no attributes available to it.
*
* @return an <code>Enumeration</code> of strings containing the names of the request's attributes
*/
Enumeration<String> getAttributeNames();
/**
* Returns the name of the character encoding used in the body of this request. This method returns
* <code>null</code> if the no character encoding has been specified. The following priority order is used to
* determine the specified encoding:
* <ol>
* <li>per request</li>
* <li>web application default via the deployment descriptor or
* {@link ServletContext#setRequestCharacterEncoding(String)}</li>
* <li>container default via container specific configuration</li>
* </ol>
*
* @return a <code>String</code> containing the name of the character encoding, or <code>null</code> if the request
* does not specify a character encoding
*/
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().
*
* @param encoding a {@code String} containing the name of the character encoding
*
* @throws UnsupportedEncodingException if this is not a valid encoding
*/
void setCharacterEncoding(String encoding) throws UnsupportedEncodingException;
/**
* Overrides 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.
* <p>
* Implementations are strongly encouraged to override this default method and provide a more efficient
* implementation.
*
* @param encoding {@code Charset} representing the character encoding.
*
* @since Servlet 6.1
*/
default void setCharacterEncoding(Charset encoding) {
try {
setCharacterEncoding(encoding.name());
} catch (UnsupportedEncodingException ignore) {
// Unreachable code
}
}
/**
* 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 or is greater than
* {@link Integer#MAX_VALUE}
*/
int getContentLength();
/**
* 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 a long integer containing the length of the request body or -1 if the length is not known
*
* @since Servlet 3.1
*/
long getContentLengthLong();
/**
* Returns the MIME type of the body of the request, or <code>null</code> if the type is not known. For HTTP
* servlets, same as the value of the CGI variable CONTENT_TYPE.
*
* @return a <code>String</code> containing the name of the MIME type of the request, or null if the type is not
* known
*/
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
*/
ServletInputStream getInputStream() throws IOException;
/**
* Returns the value of a request parameter as a <code>String</code>, or <code>null</code> 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.
* <p>
* 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}.
* <p>
* If you use this method with a multivalued parameter, the value returned is equal to the first value in the array
* returned by <code>getParameterValues</code>.
* <p>
* 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.
* <p>
* If not already parsed, calling this method will trigger the parsing of the query string, POSTed form data where
* the request body has content type is <code>application/x-www-form-urlencoded</code> and POSTed form data where
* the request body has content-type <code>multipart/form-data</code> and the Servlet is configured with a
* {@link jakarta.servlet.annotation.MultipartConfig} annotation or a <code>multipart-config</code> element in the
* deployment descriptor.
*
* @param name a <code>String</code> specifying the name of the parameter
*
* @return a <code>String</code> representing the single value of the parameter
*
* @throws IllegalStateException if parameter parsing is triggered and a problem is encountered parsing the
* parameters including, but not limited to: invalid percent (%nn) encoding;
* invalid byte sequence for the specified character set; I/O errors reading the
* request body; and triggering a container defined limit related to parameter
* parsing. Containers may provide container specific options to handle some or
* all of these errors in an alternative manner that may include not throwing an
* exception.
*
* @see #getParameterValues
*/
String getParameter(String name);
/**
* Returns an <code>Enumeration</code> of <code>String</code> objects containing the names of the parameters
* contained in this request. If the request has no parameters, the method returns an empty
* <code>Enumeration</code>.
* <p>
* If not already parsed, calling this method will trigger the parsing of the query string, POSTed form data where
* the request body has content type is <code>application/x-www-form-urlencoded</code> and POSTed form data where
* the request body has content-type <code>multipart/form-data</code> and the Servlet is configured with a
* {@link jakarta.servlet.annotation.MultipartConfig} annotation or a <code>multipart-config</code> element in the
* deployment descriptor.
*
* @return an <code>Enumeration</code> of <code>String</code> objects, each <code>String</code> containing the name
* of a request parameter; or an empty <code>Enumeration</code> if the request has no parameters
*
* @throws IllegalStateException if parameter parsing is triggered and a problem is encountered parsing the
* parameters including, but not limited to: invalid percent (%nn) encoding;
* invalid byte sequence for the specified character set; I/O errors reading the
* request body; and triggering a container defined limit related to parameter
* parsing. Containers may provide container specific options to handle some or
* all of these errors in an alternative manner that may include not throwing an
* exception.
*/
Enumeration<String> getParameterNames();
/**
* Returns an array of <code>String</code> objects containing all of the values the given request parameter has, or
* <code>null</code> if the parameter does not exist.
* <p>
* If the parameter has a single value, the array has a length of 1.
* <p>
* If not already parsed, calling this method will trigger the parsing of the query string, POSTed form data where
* the request body has content type is <code>application/x-www-form-urlencoded</code> and POSTed form data where
* the request body has content-type <code>multipart/form-data</code> and the Servlet is configured with a
* {@link jakarta.servlet.annotation.MultipartConfig} annotation or a <code>multipart-config</code> element in the
* deployment descriptor.
*
* @param name a <code>String</code> containing the name of the parameter whose value is requested
*
* @return an array of <code>String</code> objects containing the parameter's values
*
* @throws IllegalStateException if parameter parsing is triggered and a problem is encountered parsing the
* parameters including, but not limited to: invalid percent (%nn) encoding;
* invalid byte sequence for the specified character set; I/O errors reading the
* request body; and triggering a container defined limit related to parameter
* parsing. Containers may provide container specific options to handle some or
* all of these errors in an alternative manner that may include not throwing an
* exception.
*
* @see #getParameter
*/
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.
* <p>
* If not already parsed, calling this method will trigger the parsing of the query string, POSTed form data where
* the request body has content type is <code>application/x-www-form-urlencoded</code> and POSTed form data where
* the request body has content-type <code>multipart/form-data</code> and the Servlet is configured with a
* {@link jakarta.servlet.annotation.MultipartConfig} annotation or a <code>multipart-config</code> element in the
* deployment descriptor.
*
* @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.
*
* @throws IllegalStateException if parameter parsing is triggered and a problem is encountered parsing the
* parameters including, but not limited to: invalid percent (%nn) encoding;
* invalid byte sequence for the specified character set; I/O errors reading the
* request body; and triggering a container defined limit related to parameter
* parsing. Containers may provide container specific options to handle some or
* all of these errors in an alternative manner that may include not throwing an
* exception.
*/
Map<String,String[]> getParameterMap();
/**
* Returns the name and version of the protocol the request uses in the form
* <i>protocol/majorVersion.minorVersion</i>, for example, HTTP/1.1. For HTTP servlets, the value returned is the
* same as the value of the CGI variable <code>SERVER_PROTOCOL</code>.
*
* @return a <code>String</code> containing the protocol name and version number
*/
String getProtocol();
/**
* Returns the name of the scheme used to make this request, for example, <code>http</code>, <code>https</code>, or
* <code>ftp</code>. Different schemes have different rules for constructing URLs, as noted in RFC 1738.
*
* @return a <code>String</code> containing the name of the scheme used to make this request
*/
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
* <code>Host</code> header value, if any, or the resolved server name, or the server IP address.
*
* @return a <code>String</code> containing the name of the server
*/
String getServerName();
/**
* Returns the port number to which the request was sent. It is the value of the part after ":" in the
* <code>Host</code> header value, if any, or the server port where the client connection was accepted on.
*
* @return an integer specifying the port number
*/
int getServerPort();
/**
* Retrieves the body of the request as character data using a <code>BufferedReader</code>. 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 <code>BufferedReader</code> containing the body of the request
*
* @exception java.io.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
*/
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 <code>REMOTE_ADDR</code>.
*
* @return a <code>String</code> containing the IP address of the client that sent the request
*/
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 <code>REMOTE_HOST</code>.
*
* @return a <code>String</code> containing the fully qualified name of the client
*/
String getRemoteHost();
/**
* Stores an attribute in this request. Attributes are reset between requests. This method is most often used in
* conjunction with {@link RequestDispatcher}.
* <p>
* Attribute names should follow the same conventions as package names. Names beginning with <code>jakarta.*</code>
* are reserved for use by the Jakarta EE platform.
* <p>
* If the object passed in is null, the effect is the same as calling {@link #removeAttribute}. <br>
* It is warned that when the request is dispatched from the servlet resides in a different web application by
* <code>RequestDispatcher</code>, the object set by this method may not be correctly retrieved in the caller
* servlet.
*
* @param name a <code>String</code> specifying the name of the attribute
* @param o the <code>Object</code> to be stored
*/
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.
* <p>
* Attribute names should follow the same conventions as package names. Names beginning with <code>jakarta.*</code>
* are reserved for use by the Jakarta EE platform.
*
* @param name a <code>String</code> specifying the name of the attribute to remove
*/
void removeAttribute(String name);
/**
* Returns the preferred <code>Locale</code> 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 <code>Locale</code> for the client
*/
Locale getLocale();
/**
* Returns an <code>Enumeration</code> of <code>Locale</code> 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 <code>Enumeration</code>
* containing one <code>Locale</code>, the default locale for the server.
*
* @return an <code>Enumeration</code> of preferred <code>Locale</code> objects for the client
*/
Enumeration<Locale> 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
*/
boolean isSecure();
/**
* Returns a {@link RequestDispatcher} object that acts as a wrapper for the resource located at the given path. A
* <code>RequestDispatcher</code> 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.
* <p>
* 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
* <code>null</code> if the servlet container cannot return a <code>RequestDispatcher</code>.
* <p>
* The difference between this method and {@link ServletContext#getRequestDispatcher} is that this method can take a
* relative path.
*
* @param path a <code>String</code> specifying the pathname to the resource. If it is relative, it must be relative
* against the current servlet.
*
* @return a <code>RequestDispatcher</code> object that acts as a wrapper for the resource at the specified path, or
* <code>null</code> if the servlet container cannot return a <code>RequestDispatcher</code>
*
* @see RequestDispatcher
* @see ServletContext#getRequestDispatcher
*/
RequestDispatcher getRequestDispatcher(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 Servlet 2.4
*/
int getRemotePort();
/**
* Returns the host name of the Internet Protocol (IP) interface on which the request was received.
*
* @return a <code>String</code> containing the host name of the IP on which the request was received.
*
* @since Servlet 2.4
*/
String getLocalName();
/**
* Returns the Internet Protocol (IP) address of the interface on which the request was received.
*
* @return a <code>String</code> containing the IP address on which the request was received.
*
* @since Servlet 2.4
*/
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 Servlet 2.4
*/
int getLocalPort();
/**
* @return TODO
*
* @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
ServletContext getServletContext();
/**
* @return TODO
*
* @throws IllegalStateException If async is not supported for this request
*
* @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
AsyncContext startAsync() throws IllegalStateException;
/**
* @param servletRequest The ServletRequest with which to initialise the asynchronous context
* @param servletResponse The ServletResponse with which to initialise the asynchronous context
*
* @return TODO
*
* @throws IllegalStateException If async is not supported for this request
*
* @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
AsyncContext startAsync(ServletRequest servletRequest, ServletResponse servletResponse)
throws IllegalStateException;
/**
* @return TODO
*
* @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
boolean isAsyncStarted();
/**
* @return TODO
*
* @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
boolean isAsyncSupported();
/**
* Get the current AsyncContext.
*
* @return The current AsyncContext
*
* @throws IllegalStateException if the request is not in asynchronous mode (i.e. @link #isAsyncStarted() is
* {@code false})
*
* @since Servlet 3.0
*/
AsyncContext getAsyncContext();
/**
* @return TODO
*
* @since Servlet 3.0 TODO SERVLET3 - Add comments
*/
DispatcherType getDispatcherType();
/**
* Obtain a unique (within the lifetime of the Servlet container) identifier string for this request.
* <p>
* There is no defined format for this string. The format is implementation dependent.
*
* @return A unique identifier for the request
*
* @since Servlet 6.0
*/
String getRequestId();
/**
* Obtain the request identifier for this request as defined by the protocol in use. Note that some protocols do not
* define such an identifier.
* <p>
* Examples of protocol provided request identifiers include:
* <dl>
* <dt>HTTP 1.x</dt>
* <dd>None, so the empty string should be returned</dd>
* <dt>HTTP 2</dt>
* <dd>The stream identifier</dd>
* <dt>HTTP 3</dt>
* <dd>The stream identifier</dd>
* <dt>AJP</dt>
* <dd>None, so the empty string should be returned</dd>
* </dl>
*
* @return The request identifier if one is defined, otherwise an empty string
*
* @since Servlet 6.0
*/
String getProtocolRequestId();
/**
* Obtain details of the network connection to the Servlet container that is being used by this request. The
* information presented may differ from information presented elsewhere in the Servlet API as raw information is
* presented without adjustments for, example, use of reverse proxies that may be applied elsewhere in the Servlet
* API.
*
* @return The network connection details.
*
* @since Servlet 6.0
*/
ServletConnection getServletConnection();
}