基于Servlet开发Web应用
一、简介Servlet 是Server与Applet的缩写，直译为服务端小程序，运行在 Web 服务器或应用服务器，用于接收来自Web客户端的请求并给出响应。二、关键类在基于Servlet开发过程中，有以下几个关键类。基于javax.servlet-api的4.0.1版本。2.1 ServletServlet约定了所有Servlet必须要实现的方法。接口定义如下。package javax.ser
·
一、简介
Servlet 是Server与Applet的缩写，直译为服务端小程序，运行在 Web 服务器或应用服务器，用于接收来自Web客户端的请求并给出响应。
二、关键类
在基于Servlet开发过程中，有以下几个关键类。基于javax.servlet-api的4.0.1版本。
2.1 Servlet
Servlet约定了所有Servlet必须要实现的方法。接口定义如下。
package javax.servlet;
import java.io.IOException;
/**
* Defines methods that all servlets must implement.
*
* <p>A servlet is a small Java program that runs within a Web server.
* Servlets receive and respond to requests from Web clients,
* usually across HTTP, the HyperText Transfer Protocol.
*
* <p>To implement this interface, you can write a generic servlet
* that extends
* <code>javax.servlet.GenericServlet</code> or an HTTP servlet that
* extends <code>javax.servlet.http.HttpServlet</code>.
*
* <p>This interface defines methods to initialize a servlet,
* to service requests, and to remove a servlet from the server.
* These are known as life-cycle methods and are called in the
* following sequence:
* <ol>
* <li>The servlet is constructed, then initialized with the <code>init</code> method.
* <li>Any calls from clients to the <code>service</code> method are handled.
* <li>The servlet is taken out of service, then destroyed with the
* <code>destroy</code> method, then garbage collected and finalized.
* </ol>
*/
public interface Servlet {
/**
* Servlet初始化方法，在Servlet实例化后被调用。
*
* @param config servlet的配置信息
*/
public void init(ServletConfig config) throws ServletException;
/**
* 获取Servlet的配置信息、初始化参数等。
*/
public ServletConfig getServletConfig();
/**
* Servlet请求处理方法。
*
* @param req 客户端请求
* @param res Servlet的响应
*/
public void service(ServletRequest req, ServletResponse res)
throws ServletException, IOException;
/**
* servlet描述信息。
*/
public String getServletInfo();
/**
* Servlet的销毁方法，在Servlet容器即将销毁Servlet时调用。
*/
public void destroy();
}
Servlet中定义了以下方法：
- 请求处理方法——service
- Servlet的生命周期方法，如
- init
- destroy
在接口JavaDoc中指出，如果要实现Servlet接口，可以考虑
- 如果要实现通用的Servlet，可以考虑继承GenericServlet
- 如果要实现HTTP的Servlet，可以考虑继承HttpServlet
在Servlet#init方法中接收入参为ServletConfig，通过该参数我们能获取Web应用中当前Servlet的配置信息。
在Servlet框架中，Servlet接口有两个抽象实现：GenericServlet与HttpServlet。
2.1.1 GenericServlet
GenericServlet抽象类实现了Servlet、ServletConfig接口，并通过属性保存了Servlet启动时传入的ServletConfig对象，但并未实现Servlet#service方法。
public abstract class GenericServlet
implements Servlet, ServletConfig, java.io.Serializable
{
private transient ServletConfig config;
/**
* 实现了Servlet#init方法，并对config进行了保存
*
* Called by the servlet container to indicate to a servlet that the
* servlet is being placed into service. See {@link Servlet#init}.
*
* <p>This implementation stores the {@link ServletConfig}
* object it receives from the servlet container for later use.
* When overriding this form of the method, call
* <code>super.init(config)</code>.
*
*/
public void init(ServletConfig config) throws ServletException {
this.config = config;
this.init();
}
/**
* 留给子类扩展的方法
*
* A convenience method which can be overridden so that there's no need
* to call <code>super.init(config)</code>.
*/
public void init() throws ServletException {
}
// 省略了很多方法
/**
* Called by the servlet container to allow the servlet to respond to
* a request. See {@link Servlet#service}.
*
* <p>This method is declared abstract so subclasses, such as
* <code>HttpServlet</code>, must override it.
*
* @param req the <code>ServletRequest</code> object
* that contains the client's request
*
* @param res the <code>ServletResponse</code> object
* that will contain the servlet's response
*
* @exception ServletException if an exception occurs that
* interferes with the servlet's
* normal operation occurred
*
* @exception IOException if an input or output
* exception occurs
*/
public abstract void service(ServletRequest req, ServletResponse res)
throws ServletException, IOException;
}
2.1.2 HttpServlet
对基于HTTP协议的Web客户端请求，HttpServlet扩展了GenericServlet。
2.1.2.1 HTTP支持的方法
| 方法 | 说明 |
|---|---|
| GET | GET方法请求一个指定资源的表示形式. 使用GET的请求应该只被用于获取数据. |
| HEAD | HEAD方法请求一个与GET请求的响应相同的响应，但没有响应体. |
| POST | POST方法用于将实体提交到指定的资源，通常导致在服务器上的状态变化或副作用. |
| PUT | PUT方法用请求有效载荷替换目标资源的所有当前表示。 |
| DELETE | DELETE方法删除指定的资源。 |
| CONNECT | CONNECT方法建立一个到由目标资源标识的服务器的隧道。保留方法。 |
| OPTIONS | OPTIONS方法用于描述目标资源的通信选项。 |
| TRACE | TRACE方法沿着到目标资源的路径执行一个消息环回测试。 |
参考：http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
2.1.2.2 HttpServlet类结构
HttpServlet结构如图。
HttpServlet继承了GenericServlet，实现了Servlet#service方法，并提供了基于HTTP协议的service方法。
/**
* 该方法依据http请求的method，分别将请求转发给具体doGet、doPost等具体实现方法。
**/
protected void service(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
对于需要自定义实现处理Http请求Servlet的场景，一般只需要实现对应的doGet、doPost等方法即可，通常没必要重写上述service方法。
2.1.2.3 HttpServlet具体实现
在HttpServlet实现中，doTrace、doOptions提供了基本实现，在扩展HttpServlet时通常没必要重写。但HttpServlet中doPost、doGet、doHead、doPut等方法默认实现为返回http status 400 或 405，在扩展HttpServlet要根据需要来重写。
源码实现如下。
package javax.servlet.http;
import java.io.IOException;
import java.io.PrintWriter;
import java.io.OutputStreamWriter;
import java.io.UnsupportedEncodingException;
import java.lang.reflect.Method;
import java.text.MessageFormat;
import java.util.Enumeration;
import java.util.ResourceBundle;
import javax.servlet.*;
/**
* 为基于HTTP协议的Servlet提供了抽象类。
*
* Provides an abstract class to be subclassed to create
* an HTTP servlet suitable for a Web site. A subclass of
* <code>HttpServlet</code> must override at least
* one method, usually one of these:
*
* 针对下述方法，HttpServlet的子类必须至少实现一个。
*
* <ul>
* <li> <code>doGet</code>, if the servlet supports HTTP GET requests
* <li> <code>doPost</code>, for HTTP POST requests
* <li> <code>doPut</code>, for HTTP PUT requests
* <li> <code>doDelete</code>, for HTTP DELETE requests
* <li> <code>init</code> and <code>destroy</code>,
* to manage resources that are held for the life of the servlet
* <li> <code>getServletInfo</code>, which the servlet uses to
* provide information about itself
* </ul>
*
* 通常没有必要重写service方法。
*
* <p>There's almost no reason to override the <code>service</code>
* method. <code>service</code> handles standard HTTP
* requests by dispatching them to the handler methods
* for each HTTP request type (the <code>do</code><i>XXX</i>
* methods listed above).
*
* 通常没必要重写doOptions、doTrace方法。
*
* <p>Likewise, there's almost no reason to override the
* <code>doOptions</code> and <code>doTrace</code> methods.
*
* 注意多线程环境中共享变量的线程安全。
*
* <p>Servlets typically run on multithreaded servers,
* so be aware that a servlet must handle concurrent
* requests and be careful to synchronize access to shared resources.
* Shared resources include in-memory data such as
* instance or class variables and external objects
* such as files, database connections, and network
* connections.
* See the
* <a href="https://docs.oracle.com/javase/tutorial/essential/concurrency/">
* Java Tutorial on Multithreaded Programming</a> for more
* information on handling multiple threads in a Java program.
*
* @author Various
*/
public abstract class HttpServlet extends GenericServlet
{
private static final String METHOD_DELETE = "DELETE";
private static final String METHOD_HEAD = "HEAD";
private static final String METHOD_GET = "GET";
private static final String METHOD_OPTIONS = "OPTIONS";
private static final String METHOD_POST = "POST";
private static final String METHOD_PUT = "PUT";
private static final String METHOD_TRACE = "TRACE";
// 省略部分属性、方法
/**
*
* 处理GET请求
*
* Called by the server (via the <code>service</code> method) to
* allow a servlet to handle a GET request.
*
* <p>Overriding this method to support a GET request also
* automatically supports an HTTP HEAD request. A HEAD
* request is a GET request that returns no body in the
* response, only the request header fields.
*
* <p>When overriding this method, read the request data,
* write the response headers, get the response's writer or
* output stream object, and finally, write the response data.
* It's best to include content type and encoding. When using
* a <code>PrintWriter</code> object to return the response,
* set the content type before accessing the
* <code>PrintWriter</code> object.
*
* <p>The servlet container must write the headers before
* committing the response, because in HTTP the headers must be sent
* before the response body.
*
* <p>Where possible, set the Content-Length header (with the
* {@link javax.servlet.ServletResponse#setContentLength} method),
* to allow the servlet container to use a persistent connection
* to return its response to the client, improving performance.
* The content length is automatically set if the entire response fits
* inside the response buffer.
*
* <p>When using HTTP 1.1 chunked encoding (which means that the response
* has a Transfer-Encoding header), do not set the Content-Length header.
*
* <p>The GET method should be safe, that is, without
* any side effects for which users are held responsible.
* For example, most form queries have no side effects.
* If a client request is intended to change stored data,
* the request should use some other HTTP method.
*
* <p>The GET method should also be idempotent, meaning
* that it can be safely repeated. Sometimes making a
* method safe also makes it idempotent. For example,
* repeating queries is both safe and idempotent, but
* buying a product online or modifying data is neither
* safe nor idempotent.
*
* <p>If the request is incorrectly formatted, <code>doGet</code>
* returns an HTTP "Bad Request" message.
*
*/
protected void doGet(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
String protocol = req.getProtocol();
String msg = lStrings.getString("http.method_get_not_supported");
if (protocol.endsWith("1.1")) {
resp.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg);
} else {
resp.sendError(HttpServletResponse.SC_BAD_REQUEST, msg);
}
}
/**
* 处理HEAD请求
*
* <p>Receives an HTTP HEAD request from the protected
* <code>service</code> method and handles the
* request.
* The client sends a HEAD request when it wants
* to see only the headers of a response, such as
* Content-Type or Content-Length. The HTTP HEAD
* method counts the output bytes in the response
* to set the Content-Length header accurately.
*
* <p>If you override this method, you can avoid computing
* the response body and just set the response headers
* directly to improve performance. Make sure that the
* <code>doHead</code> method you write is both safe
* and idempotent (that is, protects itself from being
* called multiple times for one HTTP HEAD request).
*
* <p>If the HTTP HEAD request is incorrectly formatted,
* <code>doHead</code> returns an HTTP "Bad Request"
* message.
*/
protected void doHead(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
NoBodyResponse response = new NoBodyResponse(resp);
doGet(req, response);
response.setContentLength();
}
/**
*
* 处理POST请求。
*
* Called by the server (via the <code>service</code> method)
* to allow a servlet to handle a POST request.
*
* The HTTP POST method allows the client to send
* data of unlimited length to the Web server a single time
* and is useful when posting information such as
* credit card numbers.
*
* <p>When overriding this method, read the request data,
* write the response headers, get the response's writer or output
* stream object, and finally, write the response data. It's best
* to include content type and encoding. When using a
* <code>PrintWriter</code> object to return the response, set the
* content type before accessing the <code>PrintWriter</code> object.
*
* <p>The servlet container must write the headers before committing the
* response, because in HTTP the headers must be sent before the
* response body.
*
* <p>Where possible, set the Content-Length header (with the
* {@link javax.servlet.ServletResponse#setContentLength} method),
* to allow the servlet container to use a persistent connection
* to return its response to the client, improving performance.
* The content length is automatically set if the entire response fits
* inside the response buffer.
*
* <p>When using HTTP 1.1 chunked encoding (which means that the response
* has a Transfer-Encoding header), do not set the Content-Length header.
*
* <p>This method does not need to be either safe or idempotent.
* Operations requested through POST can have side effects for
* which the user can be held accountable, for example,
* updating stored data or buying items online.
*
* <p>If the HTTP POST request is incorrectly formatted,
* <code>doPost</code> returns an HTTP "Bad Request" message.
*
*/
protected void doPost(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
String protocol = req.getProtocol();
String msg = lStrings.getString("http.method_post_not_supported");
if (protocol.endsWith("1.1")) {
resp.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg);
} else {
resp.sendError(HttpServletResponse.SC_BAD_REQUEST, msg);
}
}
/**
*
* 处理PUT请求
*
* Called by the server (via the <code>service</code> method)
* to allow a servlet to handle a PUT request.
*
* The PUT operation allows a client to
* place a file on the server and is similar to
* sending a file by FTP.
*
* <p>When overriding this method, leave intact
* any content headers sent with the request (including
* Content-Length, Content-Type, Content-Transfer-Encoding,
* Content-Encoding, Content-Base, Content-Language, Content-Location,
* Content-MD5, and Content-Range). If your method cannot
* handle a content header, it must issue an error message
* (HTTP 501 - Not Implemented) and discard the request.
* For more information on HTTP 1.1, see RFC 2616
* <a href="http://www.ietf.org/rfc/rfc2616.txt"></a>.
*
* <p>This method does not need to be either safe or idempotent.
* Operations that <code>doPut</code> performs can have side
* effects for which the user can be held accountable. When using
* this method, it may be useful to save a copy of the
* affected URL in temporary storage.
*
* <p>If the HTTP PUT request is incorrectly formatted,
* <code>doPut</code> returns an HTTP "Bad Request" message.
*/
protected void doPut(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
String protocol = req.getProtocol();
String msg = lStrings.getString("http.method_put_not_supported");
if (protocol.endsWith("1.1")) {
resp.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg);
} else {
resp.sendError(HttpServletResponse.SC_BAD_REQUEST, msg);
}
}
/**
*
* 处理DELETE请求。
*
* Called by the server (via the <code>service</code> method)
* to allow a servlet to handle a DELETE request.
*
* The DELETE operation allows a client to remove a document
* or Web page from the server.
*
* <p>This method does not need to be either safe
* or idempotent. Operations requested through
* DELETE can have side effects for which users
* can be held accountable. When using
* this method, it may be useful to save a copy of the
* affected URL in temporary storage.
*
* <p>If the HTTP DELETE request is incorrectly formatted,
* <code>doDelete</code> returns an HTTP "Bad Request"
* message.
*
*/
protected void doDelete(HttpServletRequest req,
HttpServletResponse resp)
throws ServletException, IOException
{
String protocol = req.getProtocol();
String msg = lStrings.getString("http.method_delete_not_supported");
if (protocol.endsWith("1.1")) {
resp.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg);
} else {
resp.sendError(HttpServletResponse.SC_BAD_REQUEST, msg);
}
}
/**
*
* 处理OPTIONS请求。
*
* Called by the server (via the <code>service</code> method)
* to allow a servlet to handle a request.
*
* The OPTIONS request determines which HTTP methods
* the server supports and
* returns an appropriate header. For example, if a servlet
* overrides <code>doGet</code>, this method returns the
* following header:
*
* <p><code>Allow: GET, HEAD, TRACE, OPTIONS</code>
*
* <p>There's no need to override this method unless the
* servlet implements new HTTP methods, beyond those
* implemented by HTTP 1.1.
*/
protected void doOptions(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
Method[] methods = getAllDeclaredMethods(this.getClass());
boolean ALLOW_GET = false;
boolean ALLOW_HEAD = false;
boolean ALLOW_POST = false;
boolean ALLOW_PUT = false;
boolean ALLOW_DELETE = false;
boolean ALLOW_TRACE = true;
boolean ALLOW_OPTIONS = true;
for (int i=0; i<methods.length; i++) {
String methodName = methods[i].getName();
if (methodName.equals("doGet")) {
ALLOW_GET = true;
ALLOW_HEAD = true;
} else if (methodName.equals("doPost")) {
ALLOW_POST = true;
} else if (methodName.equals("doPut")) {
ALLOW_PUT = true;
} else if (methodName.equals("doDelete")) {
ALLOW_DELETE = true;
}
}
// we know "allow" is not null as ALLOW_OPTIONS = true
// when this method is invoked
StringBuilder allow = new StringBuilder();
if (ALLOW_GET) {
allow.append(METHOD_GET);
}
if (ALLOW_HEAD) {
if (allow.length() > 0) {
allow.append(", ");
}
allow.append(METHOD_HEAD);
}
if (ALLOW_POST) {
if (allow.length() > 0) {
allow.append(", ");
}
allow.append(METHOD_POST);
}
if (ALLOW_PUT) {
if (allow.length() > 0) {
allow.append(", ");
}
allow.append(METHOD_PUT);
}
if (ALLOW_DELETE) {
if (allow.length() > 0) {
allow.append(", ");
}
allow.append(METHOD_DELETE);
}
if (ALLOW_TRACE) {
if (allow.length() > 0) {
allow.append(", ");
}
allow.append(METHOD_TRACE);
}
if (ALLOW_OPTIONS) {
if (allow.length() > 0) {
allow.append(", ");
}
allow.append(METHOD_OPTIONS);
}
resp.setHeader("Allow", allow.toString());
}
/**
*
* 处理TRACE请求。
*
* Called by the server (via the <code>service</code> method)
* to allow a servlet to handle a TRACE request.
*
* A TRACE returns the headers sent with the TRACE
* request to the client, so that they can be used in
* debugging. There's no need to override this method.
*
*/
protected void doTrace(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
int responseLength;
String CRLF = "\r\n";
StringBuilder buffer = new StringBuilder("TRACE ").append(req.getRequestURI())
.append(" ").append(req.getProtocol());
Enumeration<String> reqHeaderEnum = req.getHeaderNames();
while( reqHeaderEnum.hasMoreElements() ) {
String headerName = reqHeaderEnum.nextElement();
buffer.append(CRLF).append(headerName).append(": ")
.append(req.getHeader(headerName));
}
buffer.append(CRLF);
responseLength = buffer.length();
resp.setContentType("message/http");
resp.setContentLength(responseLength);
ServletOutputStream out = resp.getOutputStream();
out.print(buffer.toString());
}
/**
*
* 自定义service方法，处理基于HTTP的请求，相当于提供了HTTP协议版的service方法。
*
* Receives standard HTTP requests from the public
* <code>service</code> method and dispatches
* them to the <code>do</code><i>XXX</i> methods defined in
* this class. This method is an HTTP-specific version of the
* {@link javax.servlet.Servlet#service} method. There's no
* need to override this method.
*
* @see javax.servlet.Servlet#service
*/
protected void service(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
String method = req.getMethod();
if (method.equals(METHOD_GET)) {
long lastModified = getLastModified(req);
if (lastModified == -1) {
// servlet doesn't support if-modified-since, no reason
// to go through further expensive logic
doGet(req, resp);
} else {
long ifModifiedSince = req.getDateHeader(HEADER_IFMODSINCE);
if (ifModifiedSince < lastModified) {
// If the servlet mod time is later, call doGet()
// Round down to the nearest second for a proper compare
// A ifModifiedSince of -1 will always be less
maybeSetLastModified(resp, lastModified);
doGet(req, resp);
} else {
resp.setStatus(HttpServletResponse.SC_NOT_MODIFIED);
}
}
} else if (method.equals(METHOD_HEAD)) {
long lastModified = getLastModified(req);
maybeSetLastModified(resp, lastModified);
doHead(req, resp);
} else if (method.equals(METHOD_POST)) {
doPost(req, resp);
} else if (method.equals(METHOD_PUT)) {
doPut(req, resp);
} else if (method.equals(METHOD_DELETE)) {
doDelete(req, resp);
} else if (method.equals(METHOD_OPTIONS)) {
doOptions(req,resp);
} else if (method.equals(METHOD_TRACE)) {
doTrace(req,resp);
} else {
//
// Note that this means NO servlet supports whatever
// method was requested, anywhere on this server.
//
String errMsg = lStrings.getString("http.method_not_implemented");
Object[] errArgs = new Object[1];
errArgs[0] = method;
errMsg = MessageFormat.format(errMsg, errArgs);
resp.sendError(HttpServletResponse.SC_NOT_IMPLEMENTED, errMsg);
}
}
/**
*
* 实现了javax.servlet.Servlet#service方法。
*
* Dispatches client requests to the protected
* <code>service</code> method. There's no need to
* override this method.
*
* @param req the {@link HttpServletRequest} object that
* contains the request the client made of
* the servlet 实际是HttpServletRequest类
*
* @param res the {@link HttpServletResponse} object that
* contains the response the servlet returns
* to the client 实际是 HttpServletResponse类
*
* @see
*/
@Override
public void service(ServletRequest req, ServletResponse res)
throws ServletException, IOException
{
HttpServletRequest request;
HttpServletResponse response;
if (!(req instanceof HttpServletRequest &&
res instanceof HttpServletResponse)) {
throw new ServletException("non-HTTP request or response");
}
request = (HttpServletRequest) req;
response = (HttpServletResponse) res;
// 调用另一个service方法
service(request, response);
}
// 省略部分方法
}
// 省略内部类 NoBodyResponse、NoBodyOutputStream
2.2 ServletConfig
ServletConfig对象是在Servlet初始化过程中，由Servlet容器传递给Servlet的init方法的，包含当前Servlet的初始化信息及ServletContext信息。定义如下：
package javax.servlet;
import java.util.Enumeration;
/**
* 在Servlet初始化过程中，Servlet容器传递给Servlet的配置信息对象。
*/
public interface ServletConfig {
/**
* Returns the name of this servlet instance.
*/
public String getServletName();
/**
* 获取当前Servlet运行的ServletContext信息。
*/
public ServletContext getServletContext();
/**
* Gets the value of the initialization parameter with the given name.
*/
public String getInitParameter(String name);
/**
* Returns the names of the servlet's initialization parameters
*/
public Enumeration<String> getInitParameterNames();
}
2.3 ServletContext
ServletContext是Servlet上下文信息，定义了Servlet与Servlet容器交互的一系列方法。
在同一JVM中运行的每个Web应用都有一个ServletContext对象，被同一JVM同一Web应用中的所有Servlet共享。
package javax.servlet;
import java.io.InputStream;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.Enumeration;
import java.util.EnumSet;
import java.util.EventListener;
import java.util.Map;
import java.util.Set;
import javax.servlet.descriptor.JspConfigDescriptor;
/**
* ServletContext：Servlet上下文信息。
*
* 在同一JVM中运行的每个Web应用都有一个ServletContext对象（There is one context per "web application" per Java Virtual Machine.），
* 定义了Servlet与Servlet容器交互的一系列方法。
*
* 在Servlet初始化过程中，由Servlet容器通过ServletConfig对象提供给Servlet的init方法。
*
*/
public interface ServletContext {
/**
* The name of the <tt>ServletContext</tt> attribute which stores
* the private temporary directory (of type <tt>java.io.File</tt>)
* provided by the servlet container for the <tt>ServletContext</tt>
*/
public static final String TEMPDIR = "javax.servlet.context.tempdir";
/**
* The name of the <code>ServletContext</code> attribute whose value
* (of type <code>java.util.List<java.lang.String></code>) contains
* the list of names of JAR files in <code>WEB-INF/lib</code> ordered by
* their web fragment names (with possible exclusions if
* <code><absolute-ordering></code> without any
* <code><others/></code> is being used), or null if no
* absolute or relative ordering has been specified
*/
public static final String ORDERED_LIBS =
"javax.servlet.context.orderedLibs";
/**
* Returns the context path of the web application.
*
* <p>The context path is the portion of the request URI that is used
* to select the context of the request. The context path always comes
* first in a request URI. If this context is the "root" context
* rooted at the base of the Web server's URL name space, this path
* will be an empty string. Otherwise, if the context is not rooted at
* the root of the server's name space, the path starts with a /
* character but does not end with a / character.
*
* <p>It is possible that a servlet container may match a context by
* more than one context path. In such cases the
* {@link javax.servlet.http.HttpServletRequest#getContextPath()}
* will return the actual context path used by the request and it may
* differ from the path returned by this method.
* The context path returned by this method should be considered as the
* prime or preferred context path of the application.
*
* @return The context path of the web application, or "" for the
* root context
*
* @see javax.servlet.http.HttpServletRequest#getContextPath()
*
* @since Servlet 2.5
*/
public String getContextPath();
/**
* Returns a <code>ServletContext</code> object that
* corresponds to a specified URL on the server.
*
* <p>This method allows servlets to gain
* access to the context for various parts of the server, and as
* needed obtain {@link RequestDispatcher} objects from the context.
* The given path must be begin with <tt>/</tt>, is interpreted relative
* to the server's document root and is matched against the context
* roots of other web applications hosted on this container.
*
* <p>In a security conscious environment, the servlet container may
* return <code>null</code> for a given URL.
*
* @param uripath a <code>String</code> specifying the context path of
* another web application in the container.
* @return the <code>ServletContext</code> object that
* corresponds to the named URL, or null if either
none exists or the container wishes to restrict
* this access.
*
* @see RequestDispatcher
*/
public ServletContext getContext(String uripath);
/**
* Returns the major version of the Servlet API that this
* servlet container supports. All implementations that comply
* with Version 4.0 must have this method return the integer 4.
*
* @return 4
*/
public int getMajorVersion();
/**
* Returns the minor version of the Servlet API that this
* servlet container supports. All implementations that comply
* with Version 4.0 must have this method return the integer 0.
*
* @return 0
*/
public int getMinorVersion();
/**
* Gets the major version of the Servlet specification that the
* application represented by this ServletContext is based on.
*
* <p>The value returned may be different from {@link #getMajorVersion},
* which returns the major version of the Servlet specification
* supported by the Servlet container.
*
* @return the major version of the Servlet specification that the
* application represented by this ServletContext is based on
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public int getEffectiveMajorVersion();
/**
* Gets the minor version of the Servlet specification that the
* application represented by this ServletContext is based on.
*
* <p>The value returned may be different from {@link #getMinorVersion},
* which returns the minor version of the Servlet specification
* supported by the Servlet container.
*
* @return the minor version of the Servlet specification that the
* application represented by this ServletContext is based on
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public int getEffectiveMinorVersion();
/**
* Returns the MIME type of the specified file, or <code>null</code> if
* the MIME type is not known. The MIME type is determined
* by the configuration of the servlet container, and may be specified
* in a web application deployment descriptor. Common MIME
* types include <code>text/html</code> and <code>image/gif</code>.
*
* @param file a <code>String</code> specifying the name of a file
*
* @return a <code>String</code> specifying the file's MIME type
*/
public String getMimeType(String file);
/**
* Returns a directory-like listing of all the paths to resources
* within the web application whose longest sub-path matches the
* supplied path argument.
*
* <p>Paths indicating subdirectory paths end with a <tt>/</tt>.
*
* <p>The returned paths are all relative to the root of the web
* application, or relative to the <tt>/META-INF/resources</tt>
* directory of a JAR file inside the web application's
* <tt>/WEB-INF/lib</tt> directory, and have a leading <tt>/</tt>.
*
* <p>The returned set is not backed by the {@code ServletContext} object,
* so changes in the returned set are not reflected in the
* {@code ServletContext} object, and vice-versa.</p>
*
* <p>For example, for a web application containing:
*
* <pre>{@code
* /welcome.html
* /catalog/index.html
* /catalog/products.html
* /catalog/offers/books.html
* /catalog/offers/music.html
* /customer/login.jsp
* /WEB-INF/web.xml
* /WEB-INF/classes/com.acme.OrderServlet.class
* /WEB-INF/lib/catalog.jar!/META-INF/resources/catalog/moreOffers/books.html
* }</pre>
*
* <tt>getResourcePaths("/")</tt> would return
* <tt>{"/welcome.html", "/catalog/", "/customer/", "/WEB-INF/"}</tt>,
* and <tt>getResourcePaths("/catalog/")</tt> would return
* <tt>{"/catalog/index.html", "/catalog/products.html",
* "/catalog/offers/", "/catalog/moreOffers/"}</tt>.
*
* @param path the partial path used to match the resources,
* which must start with a <tt>/</tt>
* @return a Set containing the directory listing, or null if there
* are no resources in the web application whose path
* begins with the supplied path.
*
* @since Servlet 2.3
*/
public Set<String> getResourcePaths(String path);
/**
* Returns a URL to the resource that is mapped to the given path.
*
* <p>The path must begin with a <tt>/</tt> and is interpreted
* as relative to the current context root,
* or relative to the <tt>/META-INF/resources</tt> directory
* of a JAR file inside the web application's <tt>/WEB-INF/lib</tt>
* directory.
* This method will first search the document root of the
* web application for the requested resource, before searching
* any of the JAR files inside <tt>/WEB-INF/lib</tt>.
* The order in which the JAR files inside <tt>/WEB-INF/lib</tt>
* are searched is undefined.
*
* <p>This method allows the servlet container to make a resource
* available to servlets from any source. Resources
* can be located on a local or remote
* file system, in a database, or in a <code>.war</code> file.
*
* <p>The servlet container must implement the URL handlers
* and <code>URLConnection</code> objects that are necessary
* to access the resource.
*
* <p>This method returns <code>null</code>
* if no resource is mapped to the pathname.
*
* <p>Some containers may allow writing to the URL returned by
* this method using the methods of the URL class.
*
* <p>The resource content is returned directly, so be aware that
* requesting a <code>.jsp</code> page returns the JSP source code.
* Use a <code>RequestDispatcher</code> instead to include results of
* an execution.
*
* <p>This method has a different purpose than
* <code>java.lang.Class.getResource</code>,
* which looks up resources based on a class loader. This
* method does not use class loaders.
*
* @param path a <code>String</code> specifying
* the path to the resource
*
* @return the resource located at the named path,
* or <code>null</code> if there is no resource at that path
*
* @exception MalformedURLException if the pathname is not given in
* the correct form
*/
public URL getResource(String path) throws MalformedURLException;
/**
* Returns the resource located at the named path as
* an <code>InputStream</code> object.
*
* <p>The data in the <code>InputStream</code> can be
* of any type or length. The path must be specified according
* to the rules given in <code>getResource</code>.
* This method returns <code>null</code> if no resource exists at
* the specified path.
*
* <p>Meta-information such as content length and content type
* that is available via <code>getResource</code>
* method is lost when using this method.
*
* <p>The servlet container must implement the URL handlers
* and <code>URLConnection</code> objects necessary to access
* the resource.
*
* <p>This method is different from
* <code>java.lang.Class.getResourceAsStream</code>,
* which uses a class loader. This method allows servlet containers
* to make a resource available
* to a servlet from any location, without using a class loader.
*
*
* @param path a <code>String</code> specifying the path
* to the resource
*
* @return the <code>InputStream</code> returned to the
* servlet, or <code>null</code> if no resource
* exists at the specified path
*/
public InputStream getResourceAsStream(String path);
/**
*
* 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 must begin with a <tt>/</tt> and is interpreted as
* relative to the current context root. Use <code>getContext</code>
* to obtain a <code>RequestDispatcher</code> for resources in foreign
* contexts.
*
* <p>This method returns <code>null</code> if the
* <code>ServletContext</code> cannot return a
* <code>RequestDispatcher</code>.
*
* @param path a <code>String</code> specifying the pathname
* to the resource
*
* @return a <code>RequestDispatcher</code> object
* that acts as a wrapper for the resource
* at the specified path, or <code>null</code> if
* the <code>ServletContext</code> cannot return
* a <code>RequestDispatcher</code>
*
* @see RequestDispatcher
* @see ServletContext#getContext
*/
public RequestDispatcher getRequestDispatcher(String path);
/**
* Returns a {@link RequestDispatcher} object that acts
* as a wrapper for the named servlet.
*
* <p>Servlets (and JSP pages also) may be given names via server
* administration or via a web application deployment descriptor.
* A servlet instance can determine its name using
* {@link ServletConfig#getServletName}.
*
* <p>This method returns <code>null</code> if the
* <code>ServletContext</code>
* cannot return a <code>RequestDispatcher</code> for any reason.
*
* @param name a <code>String</code> specifying the name
* of a servlet to wrap
*
* @return a <code>RequestDispatcher</code> object
* that acts as a wrapper for the named servlet,
* or <code>null</code> if the <code>ServletContext</code>
* cannot return a <code>RequestDispatcher</code>
*
* @see RequestDispatcher
* @see ServletContext#getContext
* @see ServletConfig#getServletName
*/
public RequestDispatcher getNamedDispatcher(String name);
/**
* @deprecated As of Java Servlet API 2.1, with no direct replacement.
*
* <p>This method was originally defined to retrieve a servlet
* from a <code>ServletContext</code>. In this version, this method
* always returns <code>null</code> and remains only to preserve
* binary compatibility. This method will be permanently removed
* in a future version of the Java Servlet API.
*
* <p>In lieu of this method, servlets can share information using the
* <code>ServletContext</code> class and can perform shared business logic
* by invoking methods on common non-servlet classes.
*
* @param name the servlet name
* @return the {@code javax.servlet.Servlet Servlet} with the given name
* @throws ServletException if an exception has occurred that interfaces
* with servlet's normal operation
*/
@Deprecated
public Servlet getServlet(String name) throws ServletException;
/**
* @deprecated As of Java Servlet API 2.0, with no replacement.
*
* <p>This method was originally defined to return an
* <code>Enumeration</code> of all the servlets known to this servlet
* context.
* In this version, this method always returns an empty enumeration and
* remains only to preserve binary compatibility. This method
* will be permanently removed in a future version of the Java
* Servlet API.
*
* @return an <code>Enumeration</code> of {@code javax.servlet.Servlet Servlet}
*/
@Deprecated
public Enumeration<Servlet> getServlets();
/**
* @deprecated As of Java Servlet API 2.1, with no replacement.
*
* <p>This method was originally defined to return an
* <code>Enumeration</code>
* of all the servlet names known to this context. In this version,
* this method always returns an empty <code>Enumeration</code> and
* remains only to preserve binary compatibility. This method will
* be permanently removed in a future version of the Java Servlet API.
*
* @return an <code>Enumeration</code> of {@code javax.servlet.Servlet Servlet} names
*/
@Deprecated
public Enumeration<String> getServletNames();
/**
*
* Writes the specified message to a servlet log file, usually
* an event log. The name and type of the servlet log file is
* specific to the servlet container.
*
* @param msg a <code>String</code> specifying the
* message to be written to the log file
*/
public void log(String msg);
/**
* @deprecated As of Java Servlet API 2.1, use
* {@link #log(String message, Throwable throwable)}
* instead.
*
* <p>This method was originally defined to write an
* exception's stack trace and an explanatory error message
* to the servlet log file.
*
* @param exception the <code>Exception</code> error
* @param msg a <code>String</code> that describes the exception
*/
@Deprecated
public void log(Exception exception, String msg);
/**
* Writes an explanatory message and a stack trace
* for a given <code>Throwable</code> exception
* to the servlet log file. The name and type of the servlet log
* file is specific to the servlet container, usually an event log.
*
* @param message a <code>String</code> that
* describes the error or exception
*
* @param throwable the <code>Throwable</code> error
* or exception
*/
public void log(String message, Throwable throwable);
/**
* Gets the <i>real</i> path corresponding to the given
* <i>virtual</i> path.
*
* <p>For example, if <tt>path</tt> is equal to <tt>/index.html</tt>,
* this method will return the absolute file path on the server's
* filesystem to which a request of the form
* <tt>http://<host>:<port>/<contextPath>/index.html</tt>
* would be mapped, where <tt><contextPath></tt> corresponds to the
* context path of this ServletContext.
*
* <p>The real path returned will be in a form
* appropriate to the computer and operating system on
* which the servlet container is running, including the
* proper path separators.
*
* <p>Resources inside the <tt>/META-INF/resources</tt>
* directories of JAR files bundled in the application's
* <tt>/WEB-INF/lib</tt> directory must be considered only if the
* container has unpacked them from their containing JAR file, in
* which case the path to the unpacked location must be returned.
*
* <p>This method returns <code>null</code> if the servlet container
* is unable to translate the given <i>virtual</i> path to a
* <i>real</i> path.
*
* @param path the <i>virtual</i> path to be translated to a
* <i>real</i> path
*
* @return the <i>real</i> path, or <tt>null</tt> if the
* translation cannot be performed
*/
public String getRealPath(String path);
/**
* Returns the name and version of the servlet container on which
* the servlet is running.
*
* <p>The form of the returned string is
* <i>servername</i>/<i>versionnumber</i>.
* For example, the JavaServer Web Development Kit may return the string
* <code>JavaServer Web Dev Kit/1.0</code>.
*
* <p>The servlet container may return other optional information
* after the primary string in parentheses, for example,
* <code>JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86)</code>.
*
*
* @return a <code>String</code> containing at least the
* servlet container name and version number
*/
public String getServerInfo();
/**
* Returns a <code>String</code> containing the value of the named
* context-wide initialization parameter, or <code>null</code> if
* the parameter does not exist.
*
* <p>This method can make available configuration information useful
* to an entire web application. For example, it can provide a
* webmaster's email address or the name of a system that holds
* critical data.
*
* @param name a <code>String</code> containing the name of the
* parameter whose value is requested
*
* @return a <code>String</code> containing the value of the
* context's initialization parameter, or <code>null</code> if the
* context's initialization parameter does not exist.
*
* @throws NullPointerException if the argument {@code name} is
* {@code null}
*
* @see ServletConfig#getInitParameter
*/
public String getInitParameter(String name);
/**
* Returns the names of the context's initialization parameters as an
* <code>Enumeration</code> of <code>String</code> objects, or an
* empty <code>Enumeration</code> if the context has no initialization
* parameters.
*
* @return an <code>Enumeration</code> of <code>String</code>
* objects containing the names of the context's
* initialization parameters
*
* @see ServletConfig#getInitParameter
*/
public Enumeration<String> getInitParameterNames();
/**
* Sets the context initialization parameter with the given name and
* value on this ServletContext.
*
* @param name the name of the context initialization parameter to set
* @param value the value of the context initialization parameter to set
*
* @return true if the context initialization parameter with the given
* name and value was set successfully on this ServletContext, and false
* if it was not set because this ServletContext already contains a
* context initialization parameter with a matching name
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws NullPointerException if the name parameter is {@code null}
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public boolean setInitParameter(String name, String value);
/**
* Returns the servlet container attribute with the given name, or
* <code>null</code> if there is no attribute by that name.
*
* <p>An attribute allows a servlet container to give the
* servlet additional information not
* already provided by this interface. See your
* server documentation for information about its attributes.
* A list of supported attributes can be retrieved using
* <code>getAttributeNames</code>.
*
* <p>The attribute is returned as a <code>java.lang.Object</code>
* or some subclass.
*
* <p>Attribute names should follow the same convention as package
* names. The Java Servlet API specification reserves names
* matching <code>java.*</code>, <code>javax.*</code>,
* and <code>sun.*</code>.
*
* @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 no attribute
* exists matching the given name.
*
* @see ServletContext#getAttributeNames
*
* @throws NullPointerException if the argument {@code name} is
* {@code null}
*
*/
public Object getAttribute(String name);
/**
* Returns an <code>Enumeration</code> containing the
* attribute names available within this ServletContext.
*
* <p>Use the {@link #getAttribute} method with an attribute name
* to get the value of an attribute.
*
* @return an <code>Enumeration</code> of attribute
* names
*
* @see #getAttribute
*/
public Enumeration<String> getAttributeNames();
/**
* Binds an object to a given attribute name in this ServletContext. If
* the name specified is already used for an attribute, this
* method will replace the attribute with the new to the new attribute.
* <p>If listeners are configured on the <code>ServletContext</code> the
* container notifies them accordingly.
* <p>
* If a null value is passed, the effect is the same as calling
* <code>removeAttribute()</code>.
*
* <p>Attribute names should follow the same convention as package
* names. The Java Servlet API specification reserves names
* matching <code>java.*</code>, <code>javax.*</code>, and
* <code>sun.*</code>.
*
* @param name a <code>String</code> specifying the name
* of the attribute
*
* @param object an <code>Object</code> representing the
* attribute to be bound
*
* @throws NullPointerException if the name parameter is {@code null}
*
*/
public void setAttribute(String name, Object object);
/**
* Removes the attribute with the given name from
* this ServletContext. After removal, subsequent calls to
* {@link #getAttribute} to retrieve the attribute's value
* will return <code>null</code>.
*
* <p>If listeners are configured on the <code>ServletContext</code> the
* container notifies them accordingly.
*
* @param name a <code>String</code> specifying the name
* of the attribute to be removed
*/
public void removeAttribute(String name);
/**
* Returns the name of this web application corresponding to this
* ServletContext as specified in the deployment descriptor for this
* web application by the display-name element.
*
* @return The name of the web application or null if no name has been
* declared in the deployment descriptor.
*
* @since Servlet 2.3
*/
public String getServletContextName();
/**
* Adds the servlet with the given name and class name to this servlet
* context.
*
* <p>The registered servlet may be further configured via the returned
* {@link ServletRegistration} object.
*
* <p>The specified <tt>className</tt> will be loaded using the
* classloader associated with the application represented by this
* ServletContext.
*
* <p>If this ServletContext already contains a preliminary
* ServletRegistration for a servlet with the given <tt>servletName</tt>,
* it will be completed (by assigning the given <tt>className</tt> to it)
* and returned.
*
* <p>This method introspects the class with the given <tt>className</tt>
* for the {@link javax.servlet.annotation.ServletSecurity},
* {@link javax.servlet.annotation.MultipartConfig},
* <tt>javax.annotation.security.RunAs</tt>, and
* <tt>javax.annotation.security.DeclareRoles</tt> annotations.
* In addition, this method supports resource injection if the
* class with the given <tt>className</tt> represents a Managed Bean.
* See the Java EE platform and JSR 299 specifications for additional
* details about Managed Beans and resource injection.
*
* @param servletName the name of the servlet
* @param className the fully qualified class name of the servlet
*
* @return a ServletRegistration object that may be used to further
* configure the registered servlet, or <tt>null</tt> if this
* ServletContext already contains a complete ServletRegistration for
* a servlet with the given <tt>servletName</tt>
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws IllegalArgumentException if <code>servletName</code> is null
* or an empty String
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public ServletRegistration.Dynamic addServlet(
String servletName, String className);
/**
* Registers the given servlet instance with this ServletContext
* under the given <tt>servletName</tt>.
*
* <p>The registered servlet may be further configured via the returned
* {@link ServletRegistration} object.
*
* <p>If this ServletContext already contains a preliminary
* ServletRegistration for a servlet with the given <tt>servletName</tt>,
* it will be completed (by assigning the class name of the given servlet
* instance to it) and returned.
*
* @param servletName the name of the servlet
* @param servlet the servlet instance to register
*
* @return a ServletRegistration object that may be used to further
* configure the given servlet, or <tt>null</tt> if this
* ServletContext already contains a complete ServletRegistration for a
* servlet with the given <tt>servletName</tt> or if the same servlet
* instance has already been registered with this or another
* ServletContext in the same container
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @throws IllegalArgumentException if the given servlet instance
* implements {@link SingleThreadModel}, or <code>servletName</code> is null
* or an empty String
*
* @since Servlet 3.0
*/
public ServletRegistration.Dynamic addServlet(
String servletName, Servlet servlet);
/**
* Adds the servlet with the given name and class type to this servlet
* context.
*
* <p>The registered servlet may be further configured via the returned
* {@link ServletRegistration} object.
*
* <p>If this ServletContext already contains a preliminary
* ServletRegistration for a servlet with the given <tt>servletName</tt>,
* it will be completed (by assigning the name of the given
* <tt>servletClass</tt> to it) and returned.
*
* <p>This method introspects the given <tt>servletClass</tt> for
* the {@link javax.servlet.annotation.ServletSecurity},
* {@link javax.servlet.annotation.MultipartConfig},
* <tt>javax.annotation.security.RunAs</tt>, and
* <tt>javax.annotation.security.DeclareRoles</tt> annotations.
* In addition, this method supports resource injection if the
* given <tt>servletClass</tt> represents a Managed Bean.
* See the Java EE platform and JSR 299 specifications for additional
* details about Managed Beans and resource injection.
*
* @param servletName the name of the servlet
* @param servletClass the class object from which the servlet will be
* instantiated
*
* @return a ServletRegistration object that may be used to further
* configure the registered servlet, or <tt>null</tt> if this
* ServletContext already contains a complete ServletRegistration for
* the given <tt>servletName</tt>
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws IllegalArgumentException if <code>servletName</code> is null
* or an empty String
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public ServletRegistration.Dynamic addServlet(String servletName,
Class <? extends Servlet> servletClass);
/**
* Adds the servlet with the given jsp file to this servlet context.
*
* <p>The registered servlet may be further configured via the returned
* {@link ServletRegistration} object.
*
* <p>If this ServletContext already contains a preliminary
* ServletRegistration for a servlet with the given <tt>servletName</tt>,
* it will be completed (by assigning the given <tt>jspFile</tt> to it)
* and returned.
*
* @param servletName the name of the servlet
* @param jspFile the full path to a JSP file within the web application
* beginning with a `/'.
*
* @return a ServletRegistration object that may be used to further
* configure the registered servlet, or <tt>null</tt> if this
* ServletContext already contains a complete ServletRegistration for
* a servlet with the given <tt>servletName</tt>
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws IllegalArgumentException if <code>servletName</code> is null
* or an empty String
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 4.0
*/
public ServletRegistration.Dynamic addJspFile(
String servletName, String jspFile);
/**
* Instantiates the given Servlet class.
*
* <p>The returned Servlet instance may be further customized before it
* is registered with this ServletContext via a call to
* {@link #addServlet(String,Servlet)}.
*
* <p>The given Servlet class must define a zero argument constructor,
* which is used to instantiate it.
*
* <p>This method introspects the given <tt>clazz</tt> for
* the following annotations:
* {@link javax.servlet.annotation.ServletSecurity},
* {@link javax.servlet.annotation.MultipartConfig},
* <tt>javax.annotation.security.RunAs</tt>, and
* <tt>javax.annotation.security.DeclareRoles</tt>.
* In addition, this method supports resource injection if the
* given <tt>clazz</tt> represents a Managed Bean.
* See the Java EE platform and JSR 299 specifications for additional
* details about Managed Beans and resource injection.
*
* @param <T> the class of the Servlet to create
* @param clazz the Servlet class to instantiate
*
* @return the new Servlet instance
*
* @throws ServletException if the given <tt>clazz</tt> fails to be
* instantiated
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public <T extends Servlet> T createServlet(Class<T> clazz)
throws ServletException;
/**
* Gets the ServletRegistration corresponding to the servlet with the
* given <tt>servletName</tt>.
*
* @return the (complete or preliminary) ServletRegistration for the
* servlet with the given <tt>servletName</tt>, or null if no
* ServletRegistration exists under that name
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @param servletName the name of a servlet
* @since Servlet 3.0
*/
public ServletRegistration getServletRegistration(String servletName);
/**
* Gets a (possibly empty) Map of the ServletRegistration
* objects (keyed by servlet name) corresponding to all servlets
* registered with this ServletContext.
*
* <p>The returned Map includes the ServletRegistration objects
* corresponding to all declared and annotated servlets, as well as the
* ServletRegistration objects corresponding to all servlets that have
* been added via one of the <tt>addServlet</tt> and <tt>addJspFile</tt>
* methods.
*
* <p>If permitted, any changes to the returned Map must not affect this
* ServletContext.
*
* @return Map of the (complete and preliminary) ServletRegistration
* objects corresponding to all servlets currently registered with this
* ServletContext
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public Map<String, ? extends ServletRegistration> getServletRegistrations();
/**
* Adds the filter with the given name and class name to this servlet
* context.
*
* <p>The registered filter may be further configured via the returned
* {@link FilterRegistration} object.
*
* <p>The specified <tt>className</tt> will be loaded using the
* classloader associated with the application represented by this
* ServletContext.
*
* <p>If this ServletContext already contains a preliminary
* FilterRegistration for a filter with the given <tt>filterName</tt>,
* it will be completed (by assigning the given <tt>className</tt> to it)
* and returned.
*
* <p>This method supports resource injection if the class with the
* given <tt>className</tt> represents a Managed Bean.
* See the Java EE platform and JSR 299 specifications for additional
* details about Managed Beans and resource injection.
*
* @param filterName the name of the filter
* @param className the fully qualified class name of the filter
*
* @return a FilterRegistration object that may be used to further
* configure the registered filter, or <tt>null</tt> if this
* ServletContext already contains a complete FilterRegistration for
* a filter with the given <tt>filterName</tt>
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws IllegalArgumentException if <code>filterName</code> is null or
* an empty String
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public FilterRegistration.Dynamic addFilter(
String filterName, String className);
/**
* Registers the given filter instance with this ServletContext
* under the given <tt>filterName</tt>.
*
* <p>The registered filter may be further configured via the returned
* {@link FilterRegistration} object.
*
* <p>If this ServletContext already contains a preliminary
* FilterRegistration for a filter with the given <tt>filterName</tt>,
* it will be completed (by assigning the class name of the given filter
* instance to it) and returned.
*
* @param filterName the name of the filter
* @param filter the filter instance to register
*
* @return a FilterRegistration object that may be used to further
* configure the given filter, or <tt>null</tt> if this
* ServletContext already contains a complete FilterRegistration for a
* filter with the given <tt>filterName</tt> or if the same filter
* instance has already been registered with this or another
* ServletContext in the same container
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws IllegalArgumentException if <code>filterName</code> is null or
* an empty String
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public FilterRegistration.Dynamic addFilter(
String filterName, Filter filter);
/**
* Adds the filter with the given name and class type to this servlet
* context.
*
* <p>The registered filter may be further configured via the returned
* {@link FilterRegistration} object.
*
* <p>If this ServletContext already contains a preliminary
* FilterRegistration for a filter with the given <tt>filterName</tt>,
* it will be completed (by assigning the name of the given
* <tt>filterClass</tt> to it) and returned.
*
* <p>This method supports resource injection if the given
* <tt>filterClass</tt> represents a Managed Bean.
* See the Java EE platform and JSR 299 specifications for additional
* details about Managed Beans and resource injection.
*
* @param filterName the name of the filter
* @param filterClass the class object from which the filter will be
* instantiated
*
* @return a FilterRegistration object that may be used to further
* configure the registered filter, or <tt>null</tt> if this
* ServletContext already contains a complete FilterRegistration for a
* filter with the given <tt>filterName</tt>
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws IllegalArgumentException if <code>filterName</code> is null or
* an empty String
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public FilterRegistration.Dynamic addFilter(String filterName,
Class <? extends Filter> filterClass);
/**
* Instantiates the given Filter class.
*
* <p>The returned Filter instance may be further customized before it
* is registered with this ServletContext via a call to
* {@link #addFilter(String,Filter)}.
*
* <p>The given Filter class must define a zero argument constructor,
* which is used to instantiate it.
*
* <p>This method supports resource injection if the given
* <tt>clazz</tt> represents a Managed Bean.
* See the Java EE platform and JSR 299 specifications for additional
* details about Managed Beans and resource injection.
*
* @param <T> the class of the Filter to create
* @param clazz the Filter class to instantiate
*
* @return the new Filter instance
*
* @throws ServletException if the given <tt>clazz</tt> fails to be
* instantiated
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public <T extends Filter> T createFilter(Class<T> clazz)
throws ServletException;
/**
* Gets the FilterRegistration corresponding to the filter with the
* given <tt>filterName</tt>.
*
* @param filterName the name of a filter
* @return the (complete or preliminary) FilterRegistration for the
* filter with the given <tt>filterName</tt>, or null if no
* FilterRegistration exists under that name
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public FilterRegistration getFilterRegistration(String filterName);
/**
* Gets a (possibly empty) Map of the FilterRegistration
* objects (keyed by filter name) corresponding to all filters
* registered with this ServletContext.
*
* <p>The returned Map includes the FilterRegistration objects
* corresponding to all declared and annotated filters, as well as the
* FilterRegistration objects corresponding to all filters that have
* been added via one of the <tt>addFilter</tt> methods.
*
* <p>Any changes to the returned Map must not affect this
* ServletContext.
*
* @return Map of the (complete and preliminary) FilterRegistration
* objects corresponding to all filters currently registered with this
* ServletContext
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public Map<String, ? extends FilterRegistration> getFilterRegistrations();
/**
* Gets the {@link SessionCookieConfig} object through which various
* properties of the session tracking cookies created on behalf of this
* <tt>ServletContext</tt> may be configured.
*
* <p>Repeated invocations of this method will return the same
* <tt>SessionCookieConfig</tt> instance.
*
* @return the <tt>SessionCookieConfig</tt> object through which
* various properties of the session tracking cookies created on
* behalf of this <tt>ServletContext</tt> may be configured
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public SessionCookieConfig getSessionCookieConfig();
/**
* Sets the session tracking modes that are to become effective for this
* <tt>ServletContext</tt>.
*
* <p>The given <tt>sessionTrackingModes</tt> replaces any
* session tracking modes set by a previous invocation of this
* method on this <tt>ServletContext</tt>.
*
* @param sessionTrackingModes the set of session tracking modes to
* become effective for this <tt>ServletContext</tt>
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @throws IllegalArgumentException if <tt>sessionTrackingModes</tt>
* specifies a combination of <tt>SessionTrackingMode.SSL</tt> with a
* session tracking mode other than <tt>SessionTrackingMode.SSL</tt>,
* or if <tt>sessionTrackingModes</tt> specifies a session tracking mode
* that is not supported by the servlet container
*
* @since Servlet 3.0
*/
public void setSessionTrackingModes(Set<SessionTrackingMode> sessionTrackingModes);
/**
* Gets the session tracking modes that are supported by default for this
* <tt>ServletContext</tt>.
*
* <p>The returned set is not backed by the {@code ServletContext} object,
* so changes in the returned set are not reflected in the
* {@code ServletContext} object, and vice-versa.</p>
*
* @return set of the session tracking modes supported by default for
* this <tt>ServletContext</tt>
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public Set<SessionTrackingMode> getDefaultSessionTrackingModes();
/**
* Gets the session tracking modes that are in effect for this
* <tt>ServletContext</tt>.
*
* <p>The session tracking modes in effect are those provided to
* {@link #setSessionTrackingModes setSessionTrackingModes}.
*
* <p>The returned set is not backed by the {@code ServletContext} object,
* so changes in the returned set are not reflected in the
* {@code ServletContext} object, and vice-versa.</p>
*
* @return set of the session tracking modes in effect for this
* <tt>ServletContext</tt>
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public Set<SessionTrackingMode> getEffectiveSessionTrackingModes();
/**
* Adds the listener with the given class name to this ServletContext.
*
* <p>The class with the given name will be loaded using the
* classloader associated with the application represented by this
* ServletContext, and must implement one or more of the following
* interfaces:
* <ul>
* <li>{@link ServletContextAttributeListener}
* <li>{@link ServletRequestListener}
* <li>{@link ServletRequestAttributeListener}
* <li>{@link javax.servlet.http.HttpSessionAttributeListener}
* <li>{@link javax.servlet.http.HttpSessionIdListener}
* <li>{@link javax.servlet.http.HttpSessionListener}
* </ul>
*
* <p>If this ServletContext was passed to
* {@link ServletContainerInitializer#onStartup}, then the class with
* the given name may also implement {@link ServletContextListener},
* in addition to the interfaces listed above.
*
* <p>As part of this method call, the container must load the class
* with the specified class name to ensure that it implements one of
* the required interfaces.
*
* <p>If the class with the given name implements a listener interface
* whose invocation order corresponds to the declaration order (i.e.,
* if it implements {@link ServletRequestListener},
* {@link ServletContextListener}, or
* {@link javax.servlet.http.HttpSessionListener}),
* then the new listener will be added to the end of the ordered list of
* listeners of that interface.
*
* <p>This method supports resource injection if the class with the
* given <tt>className</tt> represents a Managed Bean.
* See the Java EE platform and JSR 299 specifications for additional
* details about Managed Beans and resource injection.
*
* @param className the fully qualified class name of the listener
*
* @throws IllegalArgumentException if the class with the given name
* does not implement any of the above interfaces, or if it implements
* {@link ServletContextListener} and this ServletContext was not
* passed to {@link ServletContainerInitializer#onStartup}
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public void addListener(String className);
/**
* Adds the given listener to this ServletContext.
*
* <p>The given listener must be an instance of one or more of the
* following interfaces:
* <ul>
* <li>{@link ServletContextAttributeListener}
* <li>{@link ServletRequestListener}
* <li>{@link ServletRequestAttributeListener}
* <li>{@link javax.servlet.http.HttpSessionAttributeListener}
* <li>{@link javax.servlet.http.HttpSessionIdListener}
* <li>{@link javax.servlet.http.HttpSessionListener}
* </ul>
*
* <p>If this ServletContext was passed to
* {@link ServletContainerInitializer#onStartup}, then the given
* listener may also be an instance of {@link ServletContextListener},
* in addition to the interfaces listed above.
*
* <p>If the given listener is an instance of a listener interface whose
* invocation order corresponds to the declaration order (i.e., if it
* is an instance of {@link ServletRequestListener},
* {@link ServletContextListener}, or
* {@link javax.servlet.http.HttpSessionListener}),
* then the listener will be added to the end of the ordered list of
* listeners of that interface.
*
* @param <T> the class of the EventListener to add
* @param t the listener to be added
*
* @throws IllegalArgumentException if the given listener is not
* an instance of any of the above interfaces, or if it is an instance
* of {@link ServletContextListener} and this ServletContext was not
* passed to {@link ServletContainerInitializer#onStartup}
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public <T extends EventListener> void addListener(T t);
/**
* Adds a listener of the given class type to this ServletContext.
*
* <p>The given <tt>listenerClass</tt> must implement one or more of the
* following interfaces:
* <ul>
* <li>{@link ServletContextAttributeListener}
* <li>{@link ServletRequestListener}
* <li>{@link ServletRequestAttributeListener}
* <li>{@link javax.servlet.http.HttpSessionAttributeListener}
* <li>{@link javax.servlet.http.HttpSessionIdListener}
* <li>{@link javax.servlet.http.HttpSessionListener}
* </ul>
*
* <p>If this ServletContext was passed to
* {@link ServletContainerInitializer#onStartup}, then the given
* <tt>listenerClass</tt> may also implement
* {@link ServletContextListener}, in addition to the interfaces listed
* above.
*
* <p>If the given <tt>listenerClass</tt> implements a listener
* interface whose invocation order corresponds to the declaration order
* (i.e., if it implements {@link ServletRequestListener},
* {@link ServletContextListener}, or
* {@link javax.servlet.http.HttpSessionListener}),
* then the new listener will be added to the end of the ordered list
* of listeners of that interface.
*
* <p>This method supports resource injection if the given
* <tt>listenerClass</tt> represents a Managed Bean.
* See the Java EE platform and JSR 299 specifications for additional
* details about Managed Beans and resource injection.
*
* @param listenerClass the listener class to be instantiated
*
* @throws IllegalArgumentException if the given <tt>listenerClass</tt>
* does not implement any of the above interfaces, or if it implements
* {@link ServletContextListener} and this ServletContext was not passed
* to {@link ServletContainerInitializer#onStartup}
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.0
*/
public void addListener(Class <? extends EventListener> listenerClass);
/**
* Instantiates the given EventListener class.
*
* <p>The specified EventListener class must implement at least one of
* the {@link ServletContextListener},
* {@link ServletContextAttributeListener},
* {@link ServletRequestListener},
* {@link ServletRequestAttributeListener},
* {@link javax.servlet.http.HttpSessionAttributeListener},
* {@link javax.servlet.http.HttpSessionIdListener}, or
* {@link javax.servlet.http.HttpSessionListener}
* interfaces.
*
* <p>The returned EventListener instance may be further customized
* before it is registered with this ServletContext via a call to
* {@link #addListener(EventListener)}.
*
* <p>The given EventListener class must define a zero argument
* constructor, which is used to instantiate it.
*
* <p>This method supports resource injection if the given
* <tt>clazz</tt> represents a Managed Bean.
* See the Java EE platform and JSR 299 specifications for additional
* details about Managed Beans and resource injection.
*
* @param <T> the class of the EventListener to create
* @param clazz the EventListener class to instantiate
*
* @return the new EventListener instance
*
* @throws ServletException if the given <tt>clazz</tt> fails to be
* instantiated
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @throws IllegalArgumentException if the specified EventListener class
* does not implement any of the
* {@link ServletContextListener},
* {@link ServletContextAttributeListener},
* {@link ServletRequestListener},
* {@link ServletRequestAttributeListener},
* {@link javax.servlet.http.HttpSessionAttributeListener},
* {@link javax.servlet.http.HttpSessionIdListener}, or
* {@link javax.servlet.http.HttpSessionListener}
* interfaces.
*
* @since Servlet 3.0
*/
public <T extends EventListener> T createListener(Class<T> clazz)
throws ServletException;
/**
* Gets the <code><jsp-config></code> related configuration
* that was aggregated from the <code>web.xml</code> and
* <code>web-fragment.xml</code> descriptor files of the web application
* represented by this ServletContext.
*
* @return the <code><jsp-config></code> related configuration
* that was aggregated from the <code>web.xml</code> and
* <code>web-fragment.xml</code> descriptor files of the web application
* represented by this ServletContext, or null if no such configuration
* exists
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @see javax.servlet.descriptor.JspConfigDescriptor
*
* @since Servlet 3.0
*/
public JspConfigDescriptor getJspConfigDescriptor();
/**
* Gets the class loader of the web application represented by this
* ServletContext.
*
* <p>If a security manager exists, and the caller's class loader
* is not the same as, or an ancestor of the requested class loader,
* then the security manager's <code>checkPermission</code> method is
* called with a <code>RuntimePermission("getClassLoader")</code>
* permission to check whether access to the requested class loader
* should be granted.
*
* @return the class loader of the web application represented by this
* ServletContext
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @throws SecurityException if a security manager denies access to
* the requested class loader
*
* @since Servlet 3.0
*/
public ClassLoader getClassLoader();
/**
* Declares role names that are tested using <code>isUserInRole</code>.
*
* <p>Roles that are implicitly declared as a result of their use within
* the {@link ServletRegistration.Dynamic#setServletSecurity
* setServletSecurity} or {@link ServletRegistration.Dynamic#setRunAsRole
* setRunAsRole} methods of the {@link ServletRegistration} interface need
* not be declared.
*
* @param roleNames the role names being declared
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @throws IllegalArgumentException if any of the argument roleNames is
* null or the empty string
*
* @throws IllegalStateException if the ServletContext has already
* been initialized
*
* @since Servlet 3.0
*/
public void declareRoles(String... roleNames);
/**
* Returns the configuration name of the logical host on which the
* ServletContext is deployed.
*
* Servlet containers may support multiple logical hosts. This method must
* return the same name for all the servlet contexts deployed on a logical
* host, and the name returned by this method must be distinct, stable per
* logical host, and suitable for use in associating server configuration
* information with the logical host. The returned value is NOT expected
* or required to be equivalent to a network address or hostname of the
* logical host.
*
* @return a <code>String</code> containing the configuration name of the
* logical host on which the servlet context is deployed.
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 3.1
*/
public String getVirtualServerName();
/**
* Gets the session timeout in minutes that are supported by default for
* this <tt>ServletContext</tt>.
*
* @return the session timeout in minutes that are supported by default for
* this <tt>ServletContext</tt>
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 4.0
*/
public int getSessionTimeout();
/**
* Sets the session timeout in minutes for this ServletContext.
*
* @param sessionTimeout session timeout in minutes
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 4.0
*/
public void setSessionTimeout(int sessionTimeout);
/**
* Gets the request character encoding that are supported by default for
* this <tt>ServletContext</tt>. This method returns null if no request
* encoding character encoding has been specified in deployment descriptor
* or container specific configuration (for all web applications in the
* container).
*
* @return the request character encoding that are supported by default for
* this <tt>ServletContext</tt>
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 4.0
*/
public String getRequestCharacterEncoding();
/**
* Sets the request character encoding for this ServletContext.
*
* @param encoding request character encoding
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 4.0
*/
public void setRequestCharacterEncoding(String encoding);
/**
* Gets the response character encoding that are supported by default for
* this <tt>ServletContext</tt>. This method returns null if no response
* encoding character encoding has been specified in deployment descriptor
* or container specific configuration (for all web applications in the
* container).
*
* @return the request character encoding that are supported by default for
* this <tt>ServletContext</tt>
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 4.0
*/
public String getResponseCharacterEncoding();
/**
* Sets the response character encoding for this ServletContext.
*
* @param encoding response character encoding
*
* @throws IllegalStateException if this ServletContext has already
* been initialized
*
* @throws UnsupportedOperationException if this ServletContext was
* passed to the {@link ServletContextListener#contextInitialized} method
* of a {@link ServletContextListener} that was neither declared in
* <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated
* with {@link javax.servlet.annotation.WebListener}
*
* @since Servlet 4.0
*/
public void setResponseCharacterEncoding(String encoding);
}
2.4 ServletContextListener
ServletContextListener是ServletContext的生命周期变化监听器，主要关注ServletContext初始化、关闭事件。
package javax.servlet;
import java.util.EventListener;
/**
* 用于接收ServletContext声明周期变化通知事件的接口。
*/
public interface ServletContextListener extends EventListener {
/**
* 接收Web应用初始化过程开始的通知。
* Receives notification that the web application initialization
* process is starting.
*
* 在filter和servlet对象初始化前调用。
* <p>All ServletContextListeners are notified of context
* initialization before any filters or servlets in the web
* application are initialized.
*/
default public void contextInitialized(ServletContextEvent sce) {}
/**
* 接收ServletContext即将关闭的通知。
* Receives notification that the ServletContext is about to be
* shut down.
*
* 该方法在所有Servlet和filter被销毁后调用。
* <p>All servlets and filters will have been destroyed before any
* ServletContextListeners are notified of context
* destruction.
*/
default public void contextDestroyed(ServletContextEvent sce) {}
}
2.5 Filter
Filter用于在请求到达Servlet前，对请求进行预处理；或 在Servlet给出响应后，对请求进行后处理。
/**
* <p>A filter is an object that performs
* filtering tasks on either the request to a resource (a servlet or static content), or on the response
* from a resource, or both.</p>
*
* <p>Filters perform filtering in the <code>doFilter</code> method.
* Every Filter has access to a FilterConfig object from which it can obtain
* its initialization parameters, and a reference to the ServletContext which
* it can use, for example, to load resources needed for filtering tasks.
*
* <p>Filters are configured in the deployment descriptor of a web
* application.
*
* <p>Examples that have been identified for this design are:
* <ol>
* <li>Authentication Filters
* <li>Logging and Auditing Filters
* <li>Image conversion Filters
* <li>Data compression Filters
* <li>Encryption Filters
* <li>Tokenizing Filters
* <li>Filters that trigger resource access events
* <li>XSL/T filters
* <li>Mime-type chain Filter
* </ol>
*
* @since Servlet 2.3
*/
public interface Filter {
/**
* <p>Called by the web container
* to indicate to a filter that it is being placed into service.</p>
*
* <p>The servlet container calls the init
* method exactly once after instantiating the filter. The init
* method must complete successfully before the filter is asked to do any
* filtering work.</p>
*
* <p>The web container cannot place the filter into service if the init
* method either</p>
* <ol>
* <li>Throws a ServletException
* <li>Does not return within a time period defined by the web container
* </ol>
*
* @implSpec
* The default implementation takes no action.
*
* @param filterConfig a <code>FilterConfig</code> object containing the
* filter's configuration and initialization parameters
* @throws ServletException if an exception has occurred that interferes with
* the filter's normal operation
*/
default public void init(FilterConfig filterConfig) throws ServletException {}
/**
* The <code>doFilter</code> method of the Filter is called by the
* container each time a request/response pair is passed through the
* chain due to a client request for a resource at the end of the chain.
* The FilterChain passed in to this method allows the Filter to pass
* on the request and response to the next entity in the chain.
*
* <p>A typical implementation of this method would follow the following
* pattern:
* <ol>
* <li>Examine the request
* <li>Optionally wrap the request object with a custom implementation to
* filter content or headers for input filtering
* <li>Optionally wrap the response object with a custom implementation to
* filter content or headers for output filtering
* <li>
* <ul>
* <li><strong>Either</strong> invoke the next entity in the chain
* using the FilterChain object
* (<code>chain.doFilter()</code>),
* <li><strong>or</strong> not pass on the request/response pair to
* the next entity in the filter chain to
* block the request processing
* </ul>
* <li>Directly set headers on the response after invocation of the
* next entity in the filter chain.
* </ol>
*
* @param request the <code>ServletRequest</code> object contains the client's request
* @param response the <code>ServletResponse</code> object contains the filter's response
* @param chain the <code>FilterChain</code> for invoking the next filter or the resource
* @throws IOException if an I/O related error has occurred during the processing
* @throws ServletException if an exception occurs that interferes with the
* filter's normal operation
*
* @see UnavailableException
*/
public void doFilter(ServletRequest request, ServletResponse response,
FilterChain chain)
throws IOException, ServletException;
/**
* <p>Called by the web container
* to indicate to a filter that it is being
* taken out of service.</p>
*
* <p>This method is only called once all threads within the filter's
* doFilter method have exited or after a timeout period has passed.
* After the web container calls this method, it will not call the
* doFilter method again on this instance of the filter.</p>
*
* <p>This method gives the filter an opportunity to clean up any
* resources that are being held (for example, memory, file handles,
* threads) and make sure that any persistent state is synchronized
* with the filter's current state in memory.</p>
*
* @implSpec
* The default implementation takes no action.
*/
default public void destroy() {}
}
三、Servlet容器——Tomcat
在日常工作中，Tomcat是常用的Servlet容器。
3.1 Tomcat默认实现Servlet
Tomcat中基于Servlet实现了两个默认的Servlet，在/Tomcat路径/conf/web.xml中定义如下：
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
version="3.1">
<!-- The default servlet for all web applications, that serves static -->
<!-- resources. It processes all requests that are not mapped to other -->
<!-- servlets with servlet mappings (defined either here or in your own -->
<!-- web.xml file). -->
<!-- 默认servlet -->
<servlet>
<servlet-name>default</servlet-name>
<servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
<init-param>
<param-name>debug</param-name>
<param-value>0</param-value>
</init-param>
<init-param>
<param-name>listings</param-name>
<param-value>false</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<!-- The JSP page compiler and execution servlet, which is the mechanism -->
<!-- used by Tomcat to support JSP pages. Traditionally, this servlet -->
<!-- is mapped to the URL pattern "*.jsp". -->
<servlet>
<servlet-name>jsp</servlet-name>
<servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
<init-param>
<param-name>fork</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>xpoweredBy</param-name>
<param-value>false</param-value>
</init-param>
<load-on-startup>3</load-on-startup>
</servlet>
<!-- 映射 -->
<!-- The mapping for the default servlet -->
<servlet-mapping>
<servlet-name>default</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
<!-- The mappings for the JSP servlet -->
<servlet-mapping>
<servlet-name>jsp</servlet-name>
<url-pattern>*.jsp</url-pattern>
<url-pattern>*.jspx</url-pattern>
</servlet-mapping>
</web-app>
从定义中可以看到，jsp请求通过名为jsp的Servlet处理，其他请求由名为default的Servlet处理。
部署在当前tomcat中的所有应用都能使用上述两个默认Servlet。
3.2 具体实现
可从官网下载Tomcat源码来查看。
四、实践
基于Servlet + Tomcat实现GET请求处理，整个工程代码结构如图。
ServletDemo
├── pom.xml
└── src
└── main
├── java
│ └── com
│ └── dfx
│ └── servletdemo
│ ├── listener
│ │ └── DemoListener.java
│ └── servlet
│ ├── Demo2Servlet.java
│ └── DemoServlet.java
└── webapp
├── WEB-INF
│ └── web.xml
├── health.html
├── index.jsp
└── test
└── health2.html
4.1 pom
添加以下依赖。
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>4.0.1</version>
<scope>provided</scope>
</dependency>
4.2 自定义ServletContextListener
为监听ServletContext生命周期，自定义实现了ServletContextListener。
package com.dfx.servletdemo.listener;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;
/**
* 监听ServletContext启动
*/
public class DemoListener implements ServletContextListener {
/**
* ServletContext初始化回调
*
* @param sce
*/
@Override
public void contextInitialized(ServletContextEvent sce) {
System.out.println("ServletContext正在初始化。。。");
System.out.println("事件 = " + sce);
System.out.println("参数[servletDemoDate] = " + sce.getServletContext().getInitParameter("servletDemoDate"));
}
/**
* ServletContext销毁回调
*
* @param sce
*/
@Override
public void contextDestroyed(ServletContextEvent sce) {
System.out.println("ServletContext将要销毁。。。");
System.out.println("事件：" + sce);
}
}
4.3 自定义Servlet
自定义DemoServlet，重写了servlet。
package com.dfx.servletdemo.servlet;
import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.io.OutputStream;
public class DemoServlet extends HttpServlet {
@Override
public void init(ServletConfig config) throws ServletException {
super.init(config);
System.out.println("DemoServlet正在初始化。。。");
System.out.println("init参数[initParam] = " + config.getInitParameter("initParam"));
System.out.println(config.getServletContext().toString());
}
@Override
public void doGet(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException {
OutputStream out = resp.getOutputStream();
out.write("hello, get".getBytes());
}
}
为验证同一Web应用中的不同Servlet是否共享ServletContext，又实现了一个Demo2Servlet。
package com.dfx.servletdemo.servlet;
import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.io.OutputStream;
public class Demo2Servlet extends HttpServlet {
@Override
public void init(ServletConfig config) throws ServletException {
super.init(config);
System.out.println("Demo2Servlet正在初始化。。。");
System.out.println("init参数[initParam] = " + config.getInitParameter("initParam"));
System.out.println(config.getServletContext().toString());
}
@Override
public void doGet(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException {
OutputStream out = resp.getOutputStream();
out.write("hello,2, get".getBytes());
}
}
4.4 Web.xml
<!DOCTYPE web-app PUBLIC
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd" >
<web-app>
<display-name>Archetype Created Web Application</display-name>
<context-param>
<param-name>servletDemoDate</param-name>
<param-value>20200801</param-value>
</context-param>
<!-- 注册自定义listener，可多个 -->
<listener>
<listener-class>com.dfx.servletdemo.listener.DemoListener</listener-class>
</listener>
<!-- 注册自定义servlet，可多个 -->
<servlet>
<servlet-name>demoServlet</servlet-name>
<servlet-class>com.dfx.servletdemo.servlet.DemoServlet</servlet-class>
<init-param>
<param-name>initParam</param-name>
<param-value>demo-111</param-value>
</init-param>
<load-on-startup>4</load-on-startup>
</servlet>
<servlet>
<servlet-name>demo2Servlet</servlet-name>
<servlet-class>com.dfx.servletdemo.servlet.Demo2Servlet</servlet-class>
<init-param>
<param-name>initParam</param-name>
<param-value>demo2-222</param-value>
</init-param>
<load-on-startup>4</load-on-startup>
</servlet>
<!-- 使用tomcat默认servlet default来处理html静态资源 -->
<servlet-mapping>
<servlet-name>default</servlet-name>
<url-pattern>*.html</url-pattern>
</servlet-mapping>
<!-- 使用tomcat默认servlet 来处理jsp静态资源 -->
<servlet-mapping>
<servlet-name>jsp</servlet-name>
<url-pattern>*.jsp</url-pattern>
</servlet-mapping>
<!-- 自定义demoServlet -->
<servlet-mapping>
<servlet-name>demoServlet</servlet-name>
<url-pattern>*.demo</url-pattern>
</servlet-mapping>
<!-- 自定义demoServlet2 -->
<servlet-mapping>
<servlet-name>demo2Servlet</servlet-name>
<url-pattern>*.demo2</url-pattern>
</servlet-mapping>
<welcome-file-list>
<welcome-file>index.jsp</welcome-file>
</welcome-file-list>
</web-app>
4.5 其他静态资源
index.jsp
<html>
<body>
<h2>Hello, i'm index.jsp!</h2>
</body>
</html>
health.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>欢迎页</title>
</head>
<body>
Hello, I'm health.html.
</body>
</html>
4.5 启动验证
1. ServletContext为同一Web应用中的不同Servlet共享
从应用启动日志中可以看到，DemoServlet和Demo2Servlet中打印出的ServletContext的hashCode相同，证明为同一Bean。
2.应用能使用Tomcat中默认Servlet来做资源映射
3. 自定义Servlet能够请求路径处理以.demo 或 .demo2结尾的GET请求
4. 自定义ServletContextListener能够正常监听ServletContext的启动与销毁
五、web.xml中组件加载顺序
servlet中不同组件按照如下顺序从上到下进行初始化：
- context-param
- listener
- filter
- servlet
CSDN联合极客时间，共同打造面向开发者的精品内容学习社区，助力成长！
更多推荐
0
0- 0
已为社区贡献2条内容
所有评论(0)