image.png
/*
* 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();
}
image.png
/*
* 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.http;
import java.io.IOException;
import java.util.Collection;
import java.util.Enumeration;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
/**
* Extends the {@link javax.servlet.ServletRequest} interface to provide request
* information for HTTP servlets.
* <p>
* The servlet container creates an <code>HttpServletRequest</code> object and
* passes it as an argument to the servlet's service methods
* (<code>doGet</code>, <code>doPost</code>, etc).
*/
public interface HttpServletRequest extends ServletRequest {
/**
* String identifier for Basic authentication. Value "BASIC"
*/
public static final String BASIC_AUTH = "BASIC";
/**
* String identifier for Form authentication. Value "FORM"
*/
public static final String FORM_AUTH = "FORM";
/**
* String identifier for Client Certificate authentication. Value
* "CLIENT_CERT"
*/
public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
/**
* String identifier for Digest authentication. Value "DIGEST"
*/
public static final String DIGEST_AUTH = "DIGEST";
/**
* Returns the name of the authentication scheme used to protect the
* servlet. All servlet containers support basic, form and client
* certificate authentication, and may additionally support digest
* authentication. If the servlet is not authenticated <code>null</code> is
* returned.
* <p>
* Same as the value of the CGI variable AUTH_TYPE.
*
* @return one of the static members BASIC_AUTH, FORM_AUTH, CLIENT_CERT_AUTH,
* DIGEST_AUTH (suitable for == comparison) or the
* container-specific string indicating the authentication scheme,
* or <code>null</code> if the request was not authenticated.
*/
public String getAuthType();
/**
* Returns an array containing all of the <code>Cookie</code> objects the
* client sent with this request. This method returns <code>null</code> if
* no cookies were sent.
*
* @return an array of all the <code>Cookies</code> included with this
* request, or <code>null</code> if the request has no cookies
*/
public Cookie[] getCookies();
/**
* Returns the value of the specified request header as a <code>long</code>
* value that represents a <code>Date</code> object. Use this method with
* headers that contain dates, such as <code>If-Modified-Since</code>.
* <p>
* The date is returned as the number of milliseconds since January 1, 1970
* GMT. The header name is case insensitive.
* <p>
* 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 <code>IllegalArgumentException</code>.
*
* @param name
* a <code>String</code> specifying the name of the header
* @return a <code>long</code> value representing the date specified in the
* header expressed as the number of milliseconds since January 1,
* 1970 GMT, or -1 if the named header was not included with the
* request
* @exception IllegalArgumentException
* If the header value can't be converted to a date
*/
public long getDateHeader(String name);
/**
* Returns the value of the specified request header as a
* <code>String</code>. If the request did not include a header of the
* specified name, this method returns <code>null</code>. If there are
* multiple headers with the same name, this method returns the first head
* in the request. The header name is case insensitive. You can use this
* method with any request header.
*
* @param name
* a <code>String</code> specifying the header name
* @return a <code>String</code> containing the value of the requested
* header, or <code>null</code> if the request does not have a
* header of that name
*/
public String getHeader(String name);
/**
* Returns all the values of the specified request header as an
* <code>Enumeration</code> of <code>String</code> objects.
* <p>
* Some headers, such as <code>Accept-Language</code> can be sent by clients
* as several headers each with a different value rather than sending the
* header as a comma separated list.
* <p>
* If the request did not include any headers of the specified name, this
* method returns an empty <code>Enumeration</code>. The header name is case
* insensitive. You can use this method with any request header.
*
* @param name
* a <code>String</code> specifying the header name
* @return an <code>Enumeration</code> containing the values of the requested
* header. If the request does not have any headers of that name
* return an empty enumeration. If the container does not allow
* access to header information, return null
*/
public Enumeration<String> getHeaders(String name);
/**
* Returns an enumeration of all the header names this request contains. If
* the request has no headers, this method returns an empty enumeration.
* <p>
* Some servlet containers do not allow servlets to access headers using
* this method, in which case this method returns <code>null</code>
*
* @return an enumeration of all the header names sent with this request; if
* the request has no headers, an empty enumeration; if the servlet
* container does not allow servlets to use this method,
* <code>null</code>
*/
public Enumeration<String> getHeaderNames();
/**
* Returns the value of the specified request header as an <code>int</code>.
* 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 <code>NumberFormatException</code>.
* <p>
* The header name is case insensitive.
*
* @param name
* a <code>String</code> specifying the name of a request header
* @return an integer expressing the value of the request header or -1 if the
* request doesn't have a header of this name
* @exception NumberFormatException
* If the header value can't be converted to an
* <code>int</code>
*/
public int getIntHeader(String name);
/**
* Returns the name of the HTTP method with which this request was made, for
* example, GET, POST, or PUT. Same as the value of the CGI variable
* REQUEST_METHOD.
*
* @return a <code>String</code> specifying the name of the method with
* which this request was made
*/
public String getMethod();
/**
* 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.
* <p>
* This method returns <code>null</code> if there was no extra path
* information.
* <p>
* Same as the value of the CGI variable PATH_INFO.
*
* @return a <code>String</code>, decoded by the web container, specifying
* extra path information that comes after the servlet path but
* before the query string in the request URL; or <code>null</code>
* if the URL does not have any extra path information
*/
public String getPathInfo();
/**
* Returns any extra path information after the servlet name but before the
* query string, and translates it to a real path. Same as the value of the
* CGI variable PATH_TRANSLATED.
* <p>
* If the URL does not have any extra path information, this method returns
* <code>null</code> or the servlet container cannot translate the virtual
* path to a real path for any reason (such as when the web application is
* executed from an archive). The web container does not decode this string.
*
* @return a <code>String</code> specifying the real path, or
* <code>null</code> if the URL does not have any extra path
* information
*/
public String getPathTranslated();
/**
* Returns the portion of the request URI that indicates the context of the
* request. The context path always comes first in a request URI. The path
* starts with a "/" character but does not end with a "/" character. For
* servlets in the default (root) context, this method returns "". The
* container does not decode this string.
*
* @return a <code>String</code> specifying the portion of the request URI
* that indicates the context of the request
*/
public String getContextPath();
/**
* Returns the query string that is contained in the request URL after the
* path. This method returns <code>null</code> if the URL does not have a
* query string. Same as the value of the CGI variable QUERY_STRING.
*
* @return a <code>String</code> containing the query string or
* <code>null</code> if the URL contains no query string. The value
* is not decoded by the container.
*/
public String getQueryString();
/**
* Returns the login of the user making this request, if the user has been
* authenticated, or <code>null</code> if the user has not been
* authenticated. Whether the user name is sent with each subsequent request
* depends on the browser and type of authentication. Same as the value of
* the CGI variable REMOTE_USER.
*
* @return a <code>String</code> specifying the login of the user making
* this request, or <code>null</code> if the user login is not known
*/
public String getRemoteUser();
/**
* Returns a boolean indicating whether the authenticated user is included
* in the specified logical "role". Roles and role membership can be defined
* using deployment descriptors. If the user has not been authenticated, the
* method returns <code>false</code>.
*
* @param role
* a <code>String</code> specifying the name of the role
* @return a <code>boolean</code> indicating whether the user making this
* request belongs to a given role; <code>false</code> if the user
* has not been authenticated
*/
public boolean isUserInRole(String role);
/**
* Returns a <code>java.security.Principal</code> object containing the name
* of the current authenticated user. If the user has not been
* authenticated, the method returns <code>null</code>.
*
* @return a <code>java.security.Principal</code> containing the name of the
* user making this request; <code>null</code> if the user has not
* been authenticated
*/
public java.security.Principal getUserPrincipal();
/**
* Returns the session ID specified by the client. This may not be the same
* as the ID of the current valid session for this request. If the client
* did not specify a session ID, this method returns <code>null</code>.
*
* @return a <code>String</code> specifying the session ID, or
* <code>null</code> if the request did not specify a session ID
* @see #isRequestedSessionIdValid
*/
public String getRequestedSessionId();
/**
* 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:
* <table summary="Examples of Returned Values">
* <tr align=left>
* <th>First line of HTTP request</th>
* <th>Returned Value</th>
* <tr>
* <td>POST /some/path.html HTTP/1.1
* <td>
* <td>/some/path.html
* <tr>
* <td>GET http://foo.bar/a.html HTTP/1.0
* <td>
* <td>/a.html
* <tr>
* <td>HEAD /xyz?a=b HTTP/1.1
* <td>
* <td>/xyz
* </table>
* <p>
* To reconstruct an URL with a scheme and host, use
* {@link #getRequestURL}.
*
* @return a <code>String</code> containing the part of the URL from the
* protocol name up to the query string
* @see #getRequestURL
*/
public String getRequestURI();
/**
* 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.
* <p>
* Because this method returns a <code>StringBuffer</code>, not a string,
* you can modify the URL easily, for example, to append query parameters.
* <p>
* This method is useful for creating redirect messages and for reporting
* errors.
*
* @return a <code>StringBuffer</code> object containing the reconstructed
* URL
*/
public StringBuffer getRequestURL();
/**
* Returns the part of this request's URL that calls the servlet. 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. Same as the value of the CGI variable SCRIPT_NAME.
* <p>
* This method will return an empty string ("") if the servlet used to
* process this request was matched using the "/*" pattern.
*
* @return a <code>String</code> containing the name or path of the servlet
* being called, as specified in the request URL, decoded, or an
* empty string if the servlet used to process the request is
* matched using the "/*" pattern.
*/
public String getServletPath();
/**
* Returns the current <code>HttpSession</code> associated with this request
* or, if there is no current session and <code>create</code> is true,
* returns a new session.
* <p>
* If <code>create</code> is <code>false</code> and the request has no valid
* <code>HttpSession</code>, this method returns <code>null</code>.
* <p>
* To make sure the session is properly maintained, you must call this
* method before the response is committed. If the container is using
* cookies to maintain session integrity and is asked to create a new
* session when the response is committed, an IllegalStateException is
* thrown.
*
* @param create
* <code>true</code> to create a new session for this request if
* necessary; <code>false</code> to return <code>null</code> if
* there's no current session
* @return the <code>HttpSession</code> associated with this request or
* <code>null</code> if <code>create</code> is <code>false</code>
* and the request has no valid session
* @see #getSession()
*/
public HttpSession getSession(boolean create);
/**
* Returns the current session associated with this request, or if the
* request does not have a session, creates one.
*
* @return the <code>HttpSession</code> associated with this request
* @see #getSession(boolean)
*/
public HttpSession getSession();
/**
* Changes the session ID of the session associated with this request. This
* method does not create a new session object it only changes the ID of the
* current session.
*
* @return the new session ID allocated to the session
* @see HttpSessionIdListener
* @since Servlet 3.1
*/
public String changeSessionId();
/**
* Checks whether the requested session ID is still valid.
*
* @return <code>true</code> if this request has an id for a valid session
* in the current session context; <code>false</code> otherwise
* @see #getRequestedSessionId
* @see #getSession
*/
public boolean isRequestedSessionIdValid();
/**
* Checks whether the requested session ID came in as a cookie.
*
* @return <code>true</code> if the session ID came in as a cookie;
* otherwise, <code>false</code>
* @see #getSession
*/
public boolean isRequestedSessionIdFromCookie();
/**
* Checks whether the requested session ID came in as part of the request
* URL.
*
* @return <code>true</code> if the session ID came in as part of a URL;
* otherwise, <code>false</code>
* @see #getSession
*/
public boolean isRequestedSessionIdFromURL();
/**
* @return {@link #isRequestedSessionIdFromURL()}
* @deprecated As of Version 2.1 of the Java Servlet API, use
* {@link #isRequestedSessionIdFromURL} instead.
*/
@SuppressWarnings("dep-ann")
// Spec API does not use @Deprecated
public boolean isRequestedSessionIdFromUrl();
/**
* Triggers the same authentication process as would be triggered if the
* request is for a resource that is protected by a security constraint.
*
* @param response The response to use to return any authentication
* challenge
* @return <code>true</code> if the user is successfully authenticated and
* <code>false</code> if not
*
* @throws IOException if the authentication process attempted to read from
* the request or write to the response and an I/O error occurred
* @throws IllegalStateException if the authentication process attempted to
* write to the response after it had been committed
* @throws ServletException if the authentication failed and the caller is
* expected to handle the failure
* @since Servlet 3.0
*/
public boolean authenticate(HttpServletResponse response)
throws IOException, ServletException;
/**
* Authenticate the provided user name and password and then associated the
* authenticated user with the request.
*
* @param username The user name to authenticate
* @param password The password to use to authenticate the user
*
* @throws ServletException
* If any of {@link #getRemoteUser()},
* {@link #getUserPrincipal()} or {@link #getAuthType()} are
* non-null, if the configured authenticator does not support
* user name and password authentication or if the
* authentication fails
* @since Servlet 3.0
*/
public void login(String username, String password) throws ServletException;
/**
* Removes any authenticated user from the request.
*
* @throws ServletException
* If the logout fails
* @since Servlet 3.0
*/
public void logout() throws ServletException;
/**
* Return a collection of all uploaded Parts.
*
* @return A collection of all uploaded Parts.
* @throws IOException
* if an I/O error occurs
* @throws IllegalStateException
* if size limits are exceeded or no multipart configuration is
* provided
* @throws ServletException
* if the request is not multipart/form-data
* @since Servlet 3.0
*/
public Collection<Part> getParts() throws IOException,
ServletException;
/**
* Gets the named Part or null if the Part does not exist. Triggers upload
* of all Parts.
*
* @param name The name of the Part to obtain
*
* @return The named Part or null if the Part does not exist
* @throws IOException
* if an I/O error occurs
* @throws IllegalStateException
* if size limits are exceeded
* @throws ServletException
* if the request is not multipart/form-data
* @since Servlet 3.0
*/
public Part getPart(String name) throws IOException,
ServletException;
/**
* Start the HTTP upgrade process and pass the connection to the provided
* protocol handler once the current request/response pair has completed
* processing. Calling this method sets the response status to {@link
* HttpServletResponse#SC_SWITCHING_PROTOCOLS} and flushes the response.
* Protocol specific headers must have already been set before this method
* is called.
*
* @param <T> The type of the upgrade handler
* @param httpUpgradeHandlerClass The class that implements the upgrade
* handler
*
* @return A newly created instance of the specified upgrade handler type
*
* @throws IOException
* if an I/O error occurred during the upgrade
* @throws ServletException
* if the given httpUpgradeHandlerClass fails to be instantiated
* @since Servlet 3.1
*/
public <T extends HttpUpgradeHandler> T upgrade(
Class<T> httpUpgradeHandlerClass) throws java.io.IOException, ServletException;
}
image.png
/*
* 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.IOException;
import java.io.PrintWriter;
import java.util.Locale;
/**
* Defines an object to assist a servlet in sending a response to the client.
* The servlet container creates a <code>ServletResponse</code> object and
* passes it as an argument to the servlet's <code>service</code> method.
* <p>
* To send binary data in a MIME body response, use the
* {@link ServletOutputStream} returned by {@link #getOutputStream}. To send
* character data, use the <code>PrintWriter</code> object returned by
* {@link #getWriter}. To mix binary and text data, for example, to create a
* multipart response, use a <code>ServletOutputStream</code> and manage the
* character sections manually.
* <p>
* The charset for the MIME body response can be specified explicitly using the
* {@link #setCharacterEncoding} and {@link #setContentType} methods, or
* implicitly using the {@link #setLocale} method. Explicit specifications take
* precedence over implicit specifications. If no charset is specified,
* ISO-8859-1 will be used. The <code>setCharacterEncoding</code>,
* <code>setContentType</code>, or <code>setLocale</code> method must be called
* before <code>getWriter</code> and before committing the response for the
* character encoding to be used.
* <p>
* See the Internet RFCs such as <a href="http://www.ietf.org/rfc/rfc2045.txt">
* RFC 2045</a> for more information on MIME. Protocols such as SMTP and HTTP
* define profiles of MIME, and those standards are still evolving.
*
* @see ServletOutputStream
*/
public interface ServletResponse {
/**
* Returns the name of the character encoding (MIME charset) used for the
* body sent in this response. The character encoding may have been
* specified explicitly using the {@link #setCharacterEncoding} or
* {@link #setContentType} methods, or implicitly using the
* {@link #setLocale} method. Explicit specifications take precedence over
* implicit specifications. Calls made to these methods after
* <code>getWriter</code> has been called or after the response has been
* committed have no effect on the character encoding. If no character
* encoding has been specified, <code>ISO-8859-1</code> is returned.
* <p>
* See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) for more information
* about character encoding and MIME.
*
* @return a <code>String</code> specifying the name of the character
* encoding, for example, <code>UTF-8</code>
*/
public String getCharacterEncoding();
/**
* Returns the content type used for the MIME body sent in this response.
* The content type proper must have been specified using
* {@link #setContentType} before the response is committed. If no content
* type has been specified, this method returns null. If a content type has
* been specified and a character encoding has been explicitly or implicitly
* specified as described in {@link #getCharacterEncoding}, the charset
* parameter is included in the string returned. If no character encoding
* has been specified, the charset parameter is omitted.
*
* @return a <code>String</code> specifying the content type, for example,
* <code>text/html; charset=UTF-8</code>, or null
* @since 2.4
*/
public String getContentType();
/**
* Returns a {@link ServletOutputStream} suitable for writing binary data in
* the response. The servlet container does not encode the binary data.
* <p>
* Calling flush() on the ServletOutputStream commits the response. Either
* this method or {@link #getWriter} may be called to write the body, not
* both.
*
* @return a {@link ServletOutputStream} for writing binary data
* @exception IllegalStateException
* if the <code>getWriter</code> method has been called on
* this response
* @exception IOException
* if an input or output exception occurred
* @see #getWriter
*/
public ServletOutputStream getOutputStream() throws IOException;
/**
* Returns a <code>PrintWriter</code> object that can send character text to
* the client. The <code>PrintWriter</code> uses the character encoding
* returned by {@link #getCharacterEncoding}. If the response's character
* encoding has not been specified as described in
* <code>getCharacterEncoding</code> (i.e., the method just returns the
* default value <code>ISO-8859-1</code>), <code>getWriter</code> updates it
* to <code>ISO-8859-1</code>.
* <p>
* Calling flush() on the <code>PrintWriter</code> commits the response.
* <p>
* Either this method or {@link #getOutputStream} may be called to write the
* body, not both.
*
* @return a <code>PrintWriter</code> object that can return character data
* to the client
* @exception java.io.UnsupportedEncodingException
* if the character encoding returned by
* <code>getCharacterEncoding</code> cannot be used
* @exception IllegalStateException
* if the <code>getOutputStream</code> method has already
* been called for this response object
* @exception IOException
* if an input or output exception occurred
* @see #getOutputStream
* @see #setCharacterEncoding
*/
public PrintWriter getWriter() throws IOException;
/**
* Sets the character encoding (MIME charset) of the response being sent to
* the client, for example, to UTF-8. If the character encoding has already
* been set by {@link #setContentType} or {@link #setLocale}, this method
* overrides it. Calling {@link #setContentType} with the
* <code>String</code> of <code>text/html</code> and calling this method
* with the <code>String</code> of <code>UTF-8</code> is equivalent with
* calling <code>setContentType</code> with the <code>String</code> of
* <code>text/html; charset=UTF-8</code>.
* <p>
* This method can be called repeatedly to change the character encoding.
* This method has no effect if it is called after <code>getWriter</code>
* has been called or after the response has been committed.
* <p>
* Containers must communicate the character encoding used for the servlet
* response's writer to the client if the protocol provides a way for doing
* so. In the case of HTTP, the character encoding is communicated as part
* of the <code>Content-Type</code> header for text media types. Note that
* the character encoding cannot be communicated via HTTP headers if the
* servlet does not specify a content type; however, it is still used to
* encode text written via the servlet response's writer.
*
* @param charset
* a String specifying only the character set defined by IANA
* Character Sets
* (http://www.iana.org/assignments/character-sets)
* @see #setContentType #setLocale
* @since 2.4
*/
public void setCharacterEncoding(String charset);
/**
* Sets the length of the content body in the response In HTTP servlets,
* this method sets the HTTP Content-Length header.
*
* @param len
* an integer specifying the length of the content being returned
* to the client; sets the Content-Length header
*/
public void setContentLength(int len);
/**
* Sets the length of the content body in the response In HTTP servlets,
* this method sets the HTTP Content-Length header.
*
* @param length
* an integer specifying the length of the content being returned
* to the client; sets the Content-Length header
*
* @since Servlet 3.1
*/
public void setContentLengthLong(long length);
/**
* Sets the content type of the response being sent to the client, if the
* response has not been committed yet. The given content type may include a
* character encoding specification, for example,
* <code>text/html;charset=UTF-8</code>. The response's character encoding
* is only set from the given content type if this method is called before
* <code>getWriter</code> is called.
* <p>
* This method may be called repeatedly to change content type and character
* encoding. This method has no effect if called after the response has been
* committed. It does not set the response's character encoding if it is
* called after <code>getWriter</code> has been called or after the response
* has been committed.
* <p>
* Containers must communicate the content type and the character encoding
* used for the servlet response's writer to the client if the protocol
* provides a way for doing so. In the case of HTTP, the
* <code>Content-Type</code> header is used.
*
* @param type
* a <code>String</code> specifying the MIME type of the content
* @see #setLocale
* @see #setCharacterEncoding
* @see #getOutputStream
* @see #getWriter
*/
public void setContentType(String type);
/**
* Sets the preferred buffer size for the body of the response. The servlet
* container will use a buffer at least as large as the size requested. The
* actual buffer size used can be found using <code>getBufferSize</code>.
* <p>
* A larger buffer allows more content to be written before anything is
* actually sent, thus providing the servlet with more time to set
* appropriate status codes and headers. A smaller buffer decreases server
* memory load and allows the client to start receiving data more quickly.
* <p>
* This method must be called before any response body content is written;
* if content has been written or the response object has been committed,
* this method throws an <code>IllegalStateException</code>.
*
* @param size
* the preferred buffer size
* @exception IllegalStateException
* if this method is called after content has been written
* @see #getBufferSize
* @see #flushBuffer
* @see #isCommitted
* @see #reset
*/
public void setBufferSize(int size);
/**
* Returns the actual buffer size used for the response. If no buffering is
* used, this method returns 0.
*
* @return the actual buffer size used
* @see #setBufferSize
* @see #flushBuffer
* @see #isCommitted
* @see #reset
*/
public int getBufferSize();
/**
* Forces any content in the buffer to be written to the client. A call to
* this method automatically commits the response, meaning the status code
* and headers will be written.
*
* @throws IOException if an I/O occurs during the flushing of the response
*
* @see #setBufferSize
* @see #getBufferSize
* @see #isCommitted
* @see #reset
*/
public void flushBuffer() throws IOException;
/**
* Clears the content of the underlying buffer in the response without
* clearing headers or status code. If the response has been committed, this
* method throws an <code>IllegalStateException</code>.
*
* @see #setBufferSize
* @see #getBufferSize
* @see #isCommitted
* @see #reset
* @since 2.3
*/
public void resetBuffer();
/**
* Returns a boolean indicating if the response has been committed. A
* committed response has already had its status code and headers written.
*
* @return a boolean indicating if the response has been committed
* @see #setBufferSize
* @see #getBufferSize
* @see #flushBuffer
* @see #reset
*/
public boolean isCommitted();
/**
* Clears any data that exists in the buffer as well as the status code and
* headers. If the response has been committed, this method throws an
* <code>IllegalStateException</code>.
*
* @exception IllegalStateException
* if the response has already been committed
* @see #setBufferSize
* @see #getBufferSize
* @see #flushBuffer
* @see #isCommitted
*/
public void reset();
/**
* Sets the locale of the response, if the response has not been committed
* yet. It also sets the response's character encoding appropriately for the
* locale, if the character encoding has not been explicitly set using
* {@link #setContentType} or {@link #setCharacterEncoding},
* <code>getWriter</code> hasn't been called yet, and the response hasn't
* been committed yet. If the deployment descriptor contains a
* <code>locale-encoding-mapping-list</code> element, and that element
* provides a mapping for the given locale, that mapping is used. Otherwise,
* the mapping from locale to character encoding is container dependent.
* <p>
* This method may be called repeatedly to change locale and character
* encoding. The method has no effect if called after the response has been
* committed. It does not set the response's character encoding if it is
* called after {@link #setContentType} has been called with a charset
* specification, after {@link #setCharacterEncoding} has been called, after
* <code>getWriter</code> has been called, or after the response has been
* committed.
* <p>
* Containers must communicate the locale and the character encoding used
* for the servlet response's writer to the client if the protocol provides
* a way for doing so. In the case of HTTP, the locale is communicated via
* the <code>Content-Language</code> header, the character encoding as part
* of the <code>Content-Type</code> header for text media types. Note that
* the character encoding cannot be communicated via HTTP headers if the
* servlet does not specify a content type; however, it is still used to
* encode text written via the servlet response's writer.
*
* @param loc
* the locale of the response
* @see #getLocale
* @see #setContentType
* @see #setCharacterEncoding
*/
public void setLocale(Locale loc);
/**
* Returns the locale specified for this response using the
* {@link #setLocale} method. Calls made to <code>setLocale</code> after the
* response is committed have no effect.
*
* @return The locale specified for this response using the
* {@link #setLocale} method. If no locale has been specified, the
* container's default locale is returned.
*
* @see #setLocale
*/
public Locale getLocale();
}
image.png
/*
* 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.http;
import java.io.IOException;
import java.util.Collection;
import javax.servlet.ServletResponse;
/**
* Extends the {@link ServletResponse} interface to provide HTTP-specific
* functionality in sending a response. For example, it has methods to access
* HTTP headers and cookies.
* <p>
* The servlet container creates an <code>HttpServletResponse</code> object and
* passes it as an argument to the servlet's service methods (<code>doGet</code>, <code>doPost</code>, etc).
*
* @see javax.servlet.ServletResponse
*/
public interface HttpServletResponse extends ServletResponse {
/**
* Adds the specified cookie to the response. This method can be called
* multiple times to set more than one cookie.
*
* @param cookie
* the Cookie to return to the client
*/
public void addCookie(Cookie cookie);
/**
* Returns a boolean indicating whether the named response header has
* already been set.
*
* @param name
* the header name
* @return <code>true</code> if the named response header has already been
* set; <code>false</code> otherwise
*/
public boolean containsHeader(String name);
/**
* Encodes the specified URL by including the session ID in it, or, if
* encoding is not needed, returns the URL unchanged. The implementation of
* this method includes the logic to determine whether the session ID needs
* to be encoded in the URL. For example, if the browser supports cookies,
* or session tracking is turned off, URL encoding is unnecessary.
* <p>
* For robust session tracking, all URLs emitted by a servlet should be run
* through this method. Otherwise, URL rewriting cannot be used with
* browsers which do not support cookies.
*
* @param url
* the url to be encoded.
* @return the encoded URL if encoding is needed; the unchanged URL
* otherwise.
*/
public String encodeURL(String url);
/**
* Encodes the specified URL for use in the <code>sendRedirect</code> method
* or, if encoding is not needed, returns the URL unchanged. The
* implementation of this method includes the logic to determine whether the
* session ID needs to be encoded in the URL. Because the rules for making
* this determination can differ from those used to decide whether to encode
* a normal link, this method is separated from the <code>encodeURL</code>
* method.
* <p>
* All URLs sent to the <code>HttpServletResponse.sendRedirect</code> method
* should be run through this method. Otherwise, URL rewriting cannot be
* used with browsers which do not support cookies.
*
* @param url
* the url to be encoded.
* @return the encoded URL if encoding is needed; the unchanged URL
* otherwise.
* @see #sendRedirect
* @see #encodeUrl
*/
public String encodeRedirectURL(String url);
/**
* @param url
* the url to be encoded.
* @return the encoded URL if encoding is needed; the unchanged URL
* otherwise.
* @deprecated As of version 2.1, use encodeURL(String url) instead
*/
@SuppressWarnings("dep-ann")
// Spec API does not use @Deprecated
public String encodeUrl(String url);
/**
* @param url
* the url to be encoded.
* @return the encoded URL if encoding is needed; the unchanged URL
* otherwise.
* @deprecated As of version 2.1, use encodeRedirectURL(String url) instead
*/
@SuppressWarnings("dep-ann")
// Spec API does not use @Deprecated
public String encodeRedirectUrl(String url);
/**
* Sends an error response to the client using the specified status code and
* clears the output buffer. The server defaults to creating the response to
* look like an HTML-formatted server error page containing the specified
* message, setting the content type to "text/html", leaving cookies and
* other headers unmodified. If an error-page declaration has been made for
* the web application corresponding to the status code passed in, it will
* be served back in preference to the suggested msg parameter.
* <p>
* If the response has already been committed, this method throws an
* IllegalStateException. After using this method, the response should be
* considered to be committed and should not be written to.
*
* @param sc
* the error status code
* @param msg
* the descriptive message
* @exception IOException
* If an input or output exception occurs
* @exception IllegalStateException
* If the response was committed
*/
public void sendError(int sc, String msg) throws IOException;
/**
* Sends an error response to the client using the specified status code and
* clears the buffer. This is equivalent to calling {@link #sendError(int,
* String)} with the same status code and <code>null</code> for the message.
*
* @param sc
* the error status code
* @exception IOException
* If an input or output exception occurs
* @exception IllegalStateException
* If the response was committed before this method call
*/
public void sendError(int sc) throws IOException;
/**
* Sends a temporary redirect response to the client using the specified
* redirect location URL. This method can accept relative URLs; the servlet
* container must convert the relative URL to an absolute URL before sending
* the response to the client. If the location is relative without a leading
* '/' the container interprets it as relative to the current request URI.
* If the location is relative with a leading '/' the container interprets
* it as relative to the servlet container root.
* <p>
* If the response has already been committed, this method throws an
* IllegalStateException. After using this method, the response should be
* considered to be committed and should not be written to.
*
* @param location
* the redirect location URL
* @exception IOException
* If an input or output exception occurs
* @exception IllegalStateException
* If the response was committed or if a partial URL is given
* and cannot be converted into a valid URL
*/
public void sendRedirect(String location) throws IOException;
/**
* Sets a response header with the given name and date-value. The date is
* specified in terms of milliseconds since the epoch. If the header had
* already been set, the new value overwrites the previous one. The
* <code>containsHeader</code> method can be used to test for the presence
* of a header before setting its value.
*
* @param name
* the name of the header to set
* @param date
* the assigned date value
* @see #containsHeader
* @see #addDateHeader
*/
public void setDateHeader(String name, long date);
/**
* Adds a response header with the given name and date-value. The date is
* specified in terms of milliseconds since the epoch. This method allows
* response headers to have multiple values.
*
* @param name
* the name of the header to set
* @param date
* the additional date value
* @see #setDateHeader
*/
public void addDateHeader(String name, long date);
/**
* Sets a response header with the given name and value. If the header had
* already been set, the new value overwrites the previous one. The
* <code>containsHeader</code> method can be used to test for the presence
* of a header before setting its value.
*
* @param name
* the name of the header
* @param value
* the header value If it contains octet string, it should be
* encoded according to RFC 2047
* (http://www.ietf.org/rfc/rfc2047.txt)
* @see #containsHeader
* @see #addHeader
*/
public void setHeader(String name, String value);
/**
* Adds a response header with the given name and value. This method allows
* response headers to have multiple values.
*
* @param name
* the name of the header
* @param value
* the additional header value If it contains octet string, it
* should be encoded according to RFC 2047
* (http://www.ietf.org/rfc/rfc2047.txt)
* @see #setHeader
*/
public void addHeader(String name, String value);
/**
* Sets a response header with the given name and integer value. If the
* header had already been set, the new value overwrites the previous one.
* The <code>containsHeader</code> method can be used to test for the
* presence of a header before setting its value.
*
* @param name
* the name of the header
* @param value
* the assigned integer value
* @see #containsHeader
* @see #addIntHeader
*/
public void setIntHeader(String name, int value);
/**
* Adds a response header with the given name and integer value. This method
* allows response headers to have multiple values.
*
* @param name
* the name of the header
* @param value
* the assigned integer value
* @see #setIntHeader
*/
public void addIntHeader(String name, int value);
/**
* Sets the status code for this response. This method is used to set the
* return status code when there is no error (for example, for the status
* codes SC_OK or SC_MOVED_TEMPORARILY). If there is an error, and the
* caller wishes to invoke an error-page defined in the web application, the
* <code>sendError</code> method should be used instead.
* <p>
* The container clears the buffer and sets the Location header, preserving
* cookies and other headers.
*
* @param sc
* the status code
* @see #sendError
*/
public void setStatus(int sc);
/**
* Sets the status code and message for this response.
*
* @param sc
* the status code
* @param sm
* the status message
* @deprecated As of version 2.1, due to ambiguous meaning of the message
* parameter. To set a status code use
* <code>setStatus(int)</code>, to send an error with a
* description use <code>sendError(int, String)</code>.
*/
@SuppressWarnings("dep-ann")
// Spec API does not use @Deprecated
public void setStatus(int sc, String sm);
/**
* Get the HTTP status code for this Response.
*
* @return The HTTP status code for this Response
*
* @since Servlet 3.0
*/
public int getStatus();
/**
* Return the value for the specified header, or <code>null</code> if this
* header has not been set. If more than one value was added for this
* name, only the first is returned; use {@link #getHeaders(String)} to
* retrieve all of them.
*
* @param name Header name to look up
*
* @return The first value for the specified header. This is the raw value
* so if multiple values are specified in the first header then they
* will be returned as a single header value .
*
* @since Servlet 3.0
*/
public String getHeader(String name);
/**
* Return a Collection of all the header values associated with the
* specified header name.
*
* @param name Header name to look up
*
* @return The values for the specified header. These are the raw values so
* if multiple values are specified in a single header that will be
* returned as a single header value.
*
* @since Servlet 3.0
*/
public Collection<String> getHeaders(String name);
/**
* Get the header names set for this HTTP response.
*
* @return The header names set for this HTTP response.
*
* @since Servlet 3.0
*/
public Collection<String> getHeaderNames();
/*
* Server status codes; see RFC 2068.
*/
/**
* Status code (100) indicating the client can continue.
*/
public static final int SC_CONTINUE = 100;
/**
* Status code (101) indicating the server is switching protocols according
* to Upgrade header.
*/
public static final int SC_SWITCHING_PROTOCOLS = 101;
/**
* Status code (200) indicating the request succeeded normally.
*/
public static final int SC_OK = 200;
/**
* Status code (201) indicating the request succeeded and created a new
* resource on the server.
*/
public static final int SC_CREATED = 201;
/**
* Status code (202) indicating that a request was accepted for processing,
* but was not completed.
*/
public static final int SC_ACCEPTED = 202;
/**
* Status code (203) indicating that the meta information presented by the
* client did not originate from the server.
*/
public static final int SC_NON_AUTHORITATIVE_INFORMATION = 203;
/**
* Status code (204) indicating that the request succeeded but that there
* was no new information to return.
*/
public static final int SC_NO_CONTENT = 204;
/**
* Status code (205) indicating that the agent <em>SHOULD</em> reset the
* document view which caused the request to be sent.
*/
public static final int SC_RESET_CONTENT = 205;
/**
* Status code (206) indicating that the server has fulfilled the partial
* GET request for the resource.
*/
public static final int SC_PARTIAL_CONTENT = 206;
/**
* Status code (300) indicating that the requested resource corresponds to
* any one of a set of representations, each with its own specific location.
*/
public static final int SC_MULTIPLE_CHOICES = 300;
/**
* Status code (301) indicating that the resource has permanently moved to a
* new location, and that future references should use a new URI with their
* requests.
*/
public static final int SC_MOVED_PERMANENTLY = 301;
/**
* Status code (302) indicating that the resource has temporarily moved to
* another location, but that future references should still use the
* original URI to access the resource. This definition is being retained
* for backwards compatibility. SC_FOUND is now the preferred definition.
*/
public static final int SC_MOVED_TEMPORARILY = 302;
/**
* Status code (302) indicating that the resource reside temporarily under a
* different URI. Since the redirection might be altered on occasion, the
* client should continue to use the Request-URI for future
* requests.(HTTP/1.1) To represent the status code (302), it is recommended
* to use this variable.
*/
public static final int SC_FOUND = 302;
/**
* Status code (303) indicating that the response to the request can be
* found under a different URI.
*/
public static final int SC_SEE_OTHER = 303;
/**
* Status code (304) indicating that a conditional GET operation found that
* the resource was available and not modified.
*/
public static final int SC_NOT_MODIFIED = 304;
/**
* Status code (305) indicating that the requested resource <em>MUST</em> be
* accessed through the proxy given by the <code><em>Location</em></code>
* field.
*/
public static final int SC_USE_PROXY = 305;
/**
* Status code (307) indicating that the requested resource resides
* temporarily under a different URI. The temporary URI <em>SHOULD</em> be
* given by the <code><em>Location</em></code> field in the response.
*/
public static final int SC_TEMPORARY_REDIRECT = 307;
/**
* Status code (400) indicating the request sent by the client was
* syntactically incorrect.
*/
public static final int SC_BAD_REQUEST = 400;
/**
* Status code (401) indicating that the request requires HTTP
* authentication.
*/
public static final int SC_UNAUTHORIZED = 401;
/**
* Status code (402) reserved for future use.
*/
public static final int SC_PAYMENT_REQUIRED = 402;
/**
* Status code (403) indicating the server understood the request but
* refused to fulfill it.
*/
public static final int SC_FORBIDDEN = 403;
/**
* Status code (404) indicating that the requested resource is not
* available.
*/
public static final int SC_NOT_FOUND = 404;
/**
* Status code (405) indicating that the method specified in the
* <code><em>Request-Line</em></code> is not allowed for the resource
* identified by the <code><em>Request-URI</em></code>.
*/
public static final int SC_METHOD_NOT_ALLOWED = 405;
/**
* Status code (406) indicating that the resource identified by the request
* is only capable of generating response entities which have content
* characteristics not acceptable according to the accept headers sent in
* the request.
*/
public static final int SC_NOT_ACCEPTABLE = 406;
/**
* Status code (407) indicating that the client <em>MUST</em> first
* authenticate itself with the proxy.
*/
public static final int SC_PROXY_AUTHENTICATION_REQUIRED = 407;
/**
* Status code (408) indicating that the client did not produce a request
* within the time that the server was prepared to wait.
*/
public static final int SC_REQUEST_TIMEOUT = 408;
/**
* Status code (409) indicating that the request could not be completed due
* to a conflict with the current state of the resource.
*/
public static final int SC_CONFLICT = 409;
/**
* Status code (410) indicating that the resource is no longer available at
* the server and no forwarding address is known. This condition
* <em>SHOULD</em> be considered permanent.
*/
public static final int SC_GONE = 410;
/**
* Status code (411) indicating that the request cannot be handled without a
* defined <code><em>Content-Length</em></code>.
*/
public static final int SC_LENGTH_REQUIRED = 411;
/**
* Status code (412) indicating that the precondition given in one or more
* of the request-header fields evaluated to false when it was tested on the
* server.
*/
public static final int SC_PRECONDITION_FAILED = 412;
/**
* Status code (413) indicating that the server is refusing to process the
* request because the request entity is larger than the server is willing
* or able to process.
*/
public static final int SC_REQUEST_ENTITY_TOO_LARGE = 413;
/**
* Status code (414) indicating that the server is refusing to service the
* request because the <code><em>Request-URI</em></code> is longer than the
* server is willing to interpret.
*/
public static final int SC_REQUEST_URI_TOO_LONG = 414;
/**
* Status code (415) indicating that the server is refusing to service the
* request because the entity of the request is in a format not supported by
* the requested resource for the requested method.
*/
public static final int SC_UNSUPPORTED_MEDIA_TYPE = 415;
/**
* Status code (416) indicating that the server cannot serve the requested
* byte range.
*/
public static final int SC_REQUESTED_RANGE_NOT_SATISFIABLE = 416;
/**
* Status code (417) indicating that the server could not meet the
* expectation given in the Expect request header.
*/
public static final int SC_EXPECTATION_FAILED = 417;
/**
* Status code (500) indicating an error inside the HTTP server which
* prevented it from fulfilling the request.
*/
public static final int SC_INTERNAL_SERVER_ERROR = 500;
/**
* Status code (501) indicating the HTTP server does not support the
* functionality needed to fulfill the request.
*/
public static final int SC_NOT_IMPLEMENTED = 501;
/**
* Status code (502) indicating that the HTTP server received an invalid
* response from a server it consulted when acting as a proxy or gateway.
*/
public static final int SC_BAD_GATEWAY = 502;
/**
* Status code (503) indicating that the HTTP server is temporarily
* overloaded, and unable to handle the request.
*/
public static final int SC_SERVICE_UNAVAILABLE = 503;
/**
* Status code (504) indicating that the server did not receive a timely
* response from the upstream server while acting as a gateway or proxy.
*/
public static final int SC_GATEWAY_TIMEOUT = 504;
/**
* Status code (505) indicating that the server does not support or refuses
* to support the HTTP protocol version that was used in the request
* message.
*/
public static final int SC_HTTP_VERSION_NOT_SUPPORTED = 505;
}
ublic abstract class Action_Js extends Action{
protected static final Logger log = LoggerFactory.getLogger(Action_Js.class);
public static void setNoCache(HttpServletResponse res) {
//添加下面三行代码是为了避免客户端下载一些动态信息的时候,返回的是本地的缓存,比如编辑报表时
res.setHeader("Pragma", "No-cache");
res.setHeader("Cache-Control", "No-cache");
res.setDateHeader("Expires", 0);
}
/**
* key是字符串,value是Method
* 此map保存了当前类的所有名称以action_开头的方法对象
*/
private Map subActions = new HashMap();
public Action_Js() {
super();
Method[] methods = this.getClass().getDeclaredMethods();
for (int i = 0; i < methods.length; i++) {
Method method = methods[i];
String name = method.getName();
if (name.startsWith("action_")){
subActions.put(name.substring(7).toLowerCase(), method);
method.setAccessible(true);
}
}
}
public String execute(HttpServletRequest req, HttpServletResponse res) throws Exception{
ClientResult result = ClientResult.getInstance(req, res);
try {
res.setContentType("text/plain; charset=UTF-8");
setNoCache(res);
result.setResultOk(null);
return jsexecute(req, res, result);
}
catch (Throwable e) {
/*
* 2010-10-9 将对异常的处理合并到processException方法中
*/
if(e.getClass().getName().endsWith("BithrowException")){
result.setResultException(e);
result.setPrintStackTrace(false);
}else{
/*
* 2010-10-9 将对异常的处理合并到processException方法中
*/
processException(e, req, result);
}
}
finally {
try {
processResult(req, res, result);
}
finally {
result.releaseInstance();
}
}
return null;
}