| /* |
| * 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(); |
| } |
