ServletContext接口规约

Servlet4.0的ServletContext对象

4.1 ServletContext接口简介

ServletContext是定义Servlet运行的WebApplication的视图。ServletContainer

有义务提供ServletContext实现类。Servlet可以使用ServletContext对象记录日志，读取URI，存储属性，该属性可以处于其他ServletContext的Servlet对象读取。

一个ServletContexts 是WebServer的已知的根path。如一个ServletContext是被引导至http://localhost/catlog,则所有以/catlog开头的请求都将路由至该ServletContext。

4.2 ServletContext的作用域

在一个WebApplication中，至存在一个ServletContext对象。这种情况，WebApplication可以分布式部署，则意味着一个WebApplication的一个JVM虚拟机只拥有一个ServletContext。

4.3 初始化参数

在ServletContext的下面方法中Servlet可以获取到部署时传递给应用程序的初始化参数。

• getInitParameter()
• getInitParameterNames()

初始化参数包括研发传递给应用程序的邮件地址，系统名称等等。

4.4 配置方法

从Servlet3.0开始加入了以下方法支持编程式定义Servlet、Filter、以及URL。

这些方法只能在初始化应用的时候调用，如在ServletContextListener的contextinitalezed()方法中调用，或者是在ServletContainerInitializer的实现类的onStartup的方法。除了可以添加Servlet和Filter，还可以寻找Registration实例。

4.4.1 编程式添加Servlet

编程式添加Servlet对框架开发者是很有用的。框架开发者可以使用这个方法声明控制器Servlet。该方法返回值是ServletRegistration或者是ServletRegistration.Dynamic允许你可以自定义Servlet的初始化参数和URL映射。

下面是这个方法的重载版本。

4.4.1.1 addServlet(String servletName, String className)

这个方法声明Servlet，并且给定名称和类名称添加到ServletContext中。

4.4.1.2 addServlet(String servletName, Servlet servlet)

这个方法声明Servlet，并且给定名称和Servlet实例添加到ServletContext中。

4.4.1.2 addServlet(String servletName, Class <? extends Servlet> servletClass)

这个方法声明Servlet，并且给定名称和Servlet类实例添加到ServletContext中。

4.4.1.4 addJspFile(String servletName, String jspfile)

这个方法声明Servlet，并且给定名称和jspfile实例化Serlet对象添加到ServletContext中。

4.4.1.5 <T extends Servlet> T createServlet(Class<T> clazz)

该方法创建Servlet实例，这种方法需要支持除了@WebServlet以外的所有注解。

方法返回Servlet实例，该实例可以自定义配置，再调用ServletContext.add(String,Servlet)方法添加到ServletContext中。

4.4.1.6 ServletRegistration getServletRegistration(String servletName)

这个方法返回ServletRegistration实例，如果没有则返回Null。

4.4.1.7 Map<String, ? extends ServletRegistration> getServletRegistrations()

这个方法键值对的map对象，值类型是ServletRegistration实例，如果没有则返回Null。

4.4.2 编程式添加Filter

4.4.2.1 addFilter(String filterName, String className)

这个方法声明filter，并以指定的名称添加到ServletContext中。

4.4.2.2 addFilter(String filterName, Filter filter)

这个方法声明filter，并以指定的名称和Filter实例添加到ServletContext中。

4.4.2.3 addFilter(String filterName, Class <? extends Filter> filterClass)

这种方法声明filter，并以指定的名称和Filter类实例添加到ServletContext中。

4.4.2.4 <T extends Filter> T createFilter(Class<T> clazz)

创建一个Filter对象，这个方法支持所有的注解。该方法返回的Filter对象，可以再次自定义，并且调用ServetletContext.addFilter(String,Filter)添加到ServletContext中。

4.4.2.5 FilterRegistration getFilterRegistration(String filterName)

这个方法返回对应filter名称的FilterRegistration，可能返回NULL如果该名称下没有FilterRegistration。

4.4.2.6 Map<String, ? extends FilterRegistration> getFilterRegistrations()

这个方法返回filter名称为key的map.

4.4.3 编程式添加和配置监听者

4.4.3.1 void addListener(String className)

使用指定类名添加监听者到ServletContext。该类会被应用程序的加载器加载。该类至少需要实现以下一个接口：

• javax.servlet.ServletContextAttributeListener
• javax.servlet.ServletRequestListener
• javax.servlet.ServletRequestAttributeListener
• javax.servlet.http.HttpSessionListener
• javax.servlet.http.HttpSessionAttributeListener
• javax.servlet.http.HttpSessionIdListener

4.4.3.2 <T extends EventListener> void addListener(T t)

添加监听者到ServletContext，监听者需要是以任意接口的实例：

• javax.servlet.ServletContextAttributeListener
• javax.servlet.ServletRequestListener
• javax.servlet.ServletRequestAttributeListener
• javax.servlet.http.HttpSessionListener
• javax.servlet.http.HttpSessionAttributeListener
• javax.servlet.http.HttpSessionIdListener

4.4.3.3 void addListener(Class <? extends EventListener> listenerClass)

添加监听者到ServletContext，这个类需要是继承以下任意的接口：

• javax.servlet.ServletContextAttributeListener
• javax.servlet.ServletRequestListener
• javax.servlet.ServletRequestAttributeListener
• javax.servlet.http.HttpSessionListener
• javax.servlet.http.HttpSessionAttributeListener
• javax.servlet.http.HttpSessionIdListener

4.4.3.4 <T extends EventListener> void createListener(Class<T> clazz)

使用指定的EventListener类创建监听者，EventListener类需要继承以下任意一个接口：

• javax.servlet.ServletContextAttributeListener
• javax.servlet.ServletRequestListener
• javax.servlet.ServletRequestAttributeListener
• javax.servlet.http.HttpSessionListener
• javax.servlet.http.HttpSessionAttributeListener
• javax.servlet.http.HttpSessionIdListener

4.4.3.5 以编程方式添加Servlet、Filter和Listener的注解要求

以编程的方式添加或者创建Servlet,除了添加Servlet实例的情况之外，都需要在类上声明下面的注解：@ServletSecurity, @RunAs, @DeclareRoles, @MultipartConfig。

Filter和Listeners不需要注解。

除了添加实例以外，以编程的方式添加Servlet、Filter、Listener，这些组件的资源注入的前提是组件是CDI Managed Bean。

4.4.4 编程方式配置超时时间

ServletContext接口支持以编程的方式设置Servlet的执行超时时间，单位为分钟，设置0或者小于0的数字，意味着Servlet不超时。

• getSessionTimeout()
• setSessionTimeout(int timeout)

4.4.5 以编程的方式配置字符集编码

下述方法ServletContext允许WebApplication设置和自定义request和response的编码字符集。

• getRequestCharacterEncoding()
• setRequestCharacterEncoding(String encoding)
• getResponseCharacterEncoding()
• setResponseCharacterEncoding(String encoding)

若部署时没有指定request字符集，或者是容器配置也没有指定字符集，则getRequestCharacterEncoding()返回NULL。

若部署时没有指定response字符集，或者是容器配置也没有指定字符集，则getResponseCharacterEncoding()返回NULL。

4.5 上下文的属性

Servlet可以绑定一个包含属性的对象到ServletContext中，这样，同一个WebApplication不同ServletContext的上下文就可以访问该属性了。ServletContext提供如下的方法访问属性：

• setAttribute
• getAttribute
• getAttributeNames
• removeAttribute

4.5.1 分布式容器中的上下文属性

上下文属性是虚拟机创建的本地属性，分布式部署的WebApplication容器，若希望其他容器访问上下文属性，则需要将上下文存储到Sesion中、数据库中、企业Bean 组件中。

4.6 资源

ServletContext接口只支持访问WebApplication的静态资源，包括HTML、GIF和JPEG文件，如下访问可以访问:

• getResource
• getResourceAsStream

将带有/前导符的字符串作为参数，该参数可以是相对于上下文根目录的路径，或者是相对于JAR包内WEB-INF/lib目录下的/META-Inf/Resource的目录。

4.7 多主机和上下文

WebServer支持多个本地主机通信一个机器的IP。这种本地主机叫做虚拟主机。

虚拟主机的Servlet上下文是互相隔离的。

getVirtualServerName()方法会返回虚拟主机的Servlet名称。每个虚拟主机的Servlet名称都是独一无二的。

4.8 重新加载的注意事项

Container 提供者没有提供重新加载的机制，但是要实现重加载，则必须要确保Servlet等相关类需要在同一个加载器里加载。