502 lines
20 KiB
Java
502 lines
20 KiB
Java
/*
|
|
* 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 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 <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 javax.servlet.http.HttpServletRequest}.
|
|
*
|
|
* @see javax.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>javax.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>java.*</code> and <code>javax.*</code> are
|
|
* reserved for use by the Servlet specification. Names beginning with
|
|
* <code>sun.*</code>, <code>com.sun.*</code>, <code>oracle.*</code> and
|
|
* <code>com.oracle.*</code>) are reserved for use by Oracle Corporation.
|
|
*
|
|
* @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
|
|
*/
|
|
public 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
|
|
*/
|
|
public 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 request does not
|
|
* specify a character encoding
|
|
*
|
|
* @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
|
|
*/
|
|
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().
|
|
*
|
|
* @param env
|
|
* a <code>String</code> containing the name of the character
|
|
* encoding.
|
|
* @throws java.io.UnsupportedEncodingException
|
|
* if this is not a valid encoding
|
|
*/
|
|
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 or is greater than {@link Integer#MAX_VALUE}
|
|
*/
|
|
public 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
|
|
*/
|
|
public 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
|
|
*/
|
|
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 <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.
|
|
*
|
|
* @param name
|
|
* a <code>String</code> specifying the name of the parameter
|
|
* @return a <code>String</code> representing the single value of the
|
|
* parameter
|
|
* @see #getParameterValues
|
|
*/
|
|
public 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>.
|
|
*
|
|
* @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
|
|
*/
|
|
public 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.
|
|
*
|
|
* @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
|
|
* @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<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
|
|
*/
|
|
public 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
|
|
*/
|
|
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 <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
|
|
*/
|
|
public 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
|
|
*/
|
|
public 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
|
|
*/
|
|
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 <code>REMOTE_ADDR</code>.
|
|
*
|
|
* @return a <code>String</code> 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 <code>REMOTE_HOST</code>.
|
|
*
|
|
* @return a <code>String</code> 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}.
|
|
* <p>
|
|
* Attribute names should follow the same conventions as package names.
|
|
* Names beginning with <code>java.*</code> and <code>javax.*</code> are
|
|
* reserved for use by the Servlet specification. Names beginning with
|
|
* <code>sun.*</code>, <code>com.sun.*</code>, <code>oracle.*</code> and
|
|
* <code>com.oracle.*</code>) are reserved for use by Oracle Corporation.
|
|
* <br>
|
|
* 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
|
|
*/
|
|
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.
|
|
* <p>
|
|
* Attribute names should follow the same conventions as package names.
|
|
* Names beginning with <code>java.*</code> and <code>javax.*</code> are
|
|
* reserved for use by the Servlet specification. Names beginning with
|
|
* <code>sun.*</code>, <code>com.sun.*</code>, <code>oracle.*</code> and
|
|
* <code>com.oracle.*</code>) are reserved for use by Oracle Corporation.
|
|
*
|
|
* @param name
|
|
* a <code>String</code> specifying the name of the attribute to
|
|
* remove
|
|
*/
|
|
public 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
|
|
*/
|
|
public 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
|
|
*/
|
|
public 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
|
|
*/
|
|
public 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
|
|
*/
|
|
public RequestDispatcher getRequestDispatcher(String path);
|
|
|
|
/**
|
|
* @param path The virtual path to be converted to a real path
|
|
* @return {@link ServletContext#getRealPath(String)}
|
|
* @deprecated As of Version 2.1 of the Java Servlet API, use
|
|
* {@link ServletContext#getRealPath} instead.
|
|
*/
|
|
@SuppressWarnings("dep-ann")
|
|
// Spec API does not use @Deprecated
|
|
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 Servlet 2.4
|
|
*/
|
|
public 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
|
|
*/
|
|
public 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
|
|
*/
|
|
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 Servlet 2.4
|
|
*/
|
|
public int getLocalPort();
|
|
|
|
/**
|
|
* @return TODO
|
|
* @since Servlet 3.0 TODO SERVLET3 - Add comments
|
|
*/
|
|
public ServletContext getServletContext();
|
|
|
|
/**
|
|
* @return TODO
|
|
* @throws IllegalStateException If async is not supported for this request
|
|
* @since Servlet 3.0 TODO SERVLET3 - Add comments
|
|
*/
|
|
public 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
|
|
*/
|
|
public AsyncContext startAsync(ServletRequest servletRequest,
|
|
ServletResponse servletResponse) throws IllegalStateException;
|
|
|
|
/**
|
|
* @return TODO
|
|
* @since Servlet 3.0 TODO SERVLET3 - Add comments
|
|
*/
|
|
public boolean isAsyncStarted();
|
|
|
|
/**
|
|
* @return TODO
|
|
* @since Servlet 3.0 TODO SERVLET3 - Add comments
|
|
*/
|
|
public 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
|
|
*/
|
|
public AsyncContext getAsyncContext();
|
|
|
|
/**
|
|
* @return TODO
|
|
* @since Servlet 3.0 TODO SERVLET3 - Add comments
|
|
*/
|
|
public DispatcherType getDispatcherType();
|
|
}
|