Servlet-映设配置
[TOC]
Servlet 映射配置
在 Java Web 应用中,客户端浏览器并不能直接通过类名访问服务器端的 Servlet 实例,而是通过统一的 HTTP URL 发起请求。Servlet 映射配置的核心作用是将公开的访问路径(URL Pattern)与内部具体的 Servlet 实现类进行绑定,实现外部请求路由与内部代码结构的解耦。
当客户端请求到达 Web 容器时,容器内部的路由组件(如 Tomcat 中的 Mapper)会首先剥离请求 URL 中的应用上下文路径(Context Path),然后拿着剩余的相对路径在映射表中进行检索,最终将请求派发给匹配的 Servlet 实例。
注册配置机制
Servlet 规范提供了三种注册与映射配置方式:基于 web.xml 部署描述符的声明式配置、基于 @WebServlet 注解的声明式配置(Servlet 3.0 引入),以及基于 ServletRegistration 接口的编程式动态配置(Servlet 3.0 引入)。
配置体系的核心组件与接口 UML 类图如下:

web.xml
在 Servlet 3.0 之前,所有的 Servlet 映射必须在 WEB-INF/web.xml 部署描述符中通过 XML 标签声明。即使在现代项目中,当需要集中管理路由、或为第三方 Jar 包中未标注注解的 Servlet 配置映射时,依然会使用该方式。
web.xml 配置由两个核心标签块组成,通过内部的 <servlet-name> 进行关联:
<servlet>标签块:用于向容器注册一个 Servlet 实例,指定其内部唯一标识名(<servlet-name>)与完整限定类名(<servlet-class>)。<servlet-mapping>标签块:用于将已注册的内部标识名(<servlet-name>)绑定到一个或多个外部访问路径(<url-pattern>)。xml<!-- 1. 声明 Servlet 实例与内部标识名 --> <!-- 将内部名称映射到具体的 Servlet 实现类 --> <servlet> <servlet-name>orderServlet</servlet-name> <servlet-class>com.example.servlet.OrderServlet</servlet-class> </servlet> <!-- 2. 绑定外部访问路径 --> <!-- 支持在同一个映射块中声明多个 url-pattern --> <servlet-mapping> <servlet-name>orderServlet</servlet-name> <url-pattern>/order/create</url-pattern> <url-pattern>/order/detail</url-pattern> </servlet-mapping>
@WebServlet
从 Servlet 3.0 规范开始,容器支持通过 jakarta.servlet.annotation.WebServlet 注解直接在 Servlet 实现类上声明映射关系。容器启动时会自动扫描类路径(Classpath)下的所有字节码文件,识别该注解并完成路由注册。
@WebServlet 的核心属性如下:
urlPatterns/value:类型为String[],用于指定一个或多个 URL 映射路径。两个属性互为别名,但不能同时在同一注解中显式声明,否则会引发冲突报错。name:指定当前 Servlet 的内部名称,等价于<servlet-name>。若不指定,默认取当前类的完整限定类名。loadOnStartup:指定容器启动时的预加载优先级,默认值为-1(延迟加载)。initParams:类型为WebInitParam[],用于配置当前 Servlet 的局部初始化参数。asyncSupported:布尔值,指定当前 Servlet 是否支持异步处理模式,默认为false。java// 1. 使用 @WebServlet 注解声明路由映射 // urlPatterns 支持配置多个访问路径,等价于 value 属性 @WebServlet( name = "userServlet", urlPatterns = {"/user/profile", "/user/settings"}, loadOnStartup = 1 ) public class UserServlet extends HttpServlet {// 2. 处理匹配路由的 GET 请求 // 客户端访问任一配置路径均会派发至此方法 @Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { resp.getWriter().write("User Center"); } }
@WebInitParam
jakarta.servlet.annotation.WebInitParam 是专门配合 @WebServlet 或 @WebFilter 使用的嵌套注解,用于在注解声明中注入键值对形式的局部初始化参数,等价于 web.xml 中的 <init-param> 标签。
// 1. 通过 initParams 属性嵌套 @WebInitParam 注解
// 为当前 Servlet 注入局部初始化参数
@WebServlet(
urlPatterns = "/config",
initParams = {
@WebInitParam(name = "charset", value = "UTF-8"),
@WebInitParam(name = "maxRetries", value = "3")
}
)
public class ConfigServlet extends HttpServlet {
}ServletRegistration
除了静态的 XML 与注解配置,Servlet 3.0 还引入了 jakarta.servlet.ServletRegistration 接口及其子接口 ServletRegistration.Dynamic,允许在容器启动阶段通过 Java 代码动态注册 Servlet。这一机制是 Spring MVC 等现代框架实现“零 XML 配置”(如基于 ServletContainerInitializer 自动注册 DispatcherServlet)的底层基石。
动态注册必须遵循严格的时机限制:只能在 ServletContextListener.contextInitialized 或 ServletContainerInitializer.onStartup 方法执行期间调用;一旦 ServletContext 完成初始化并开始接收请求,再调用注册方法将直接抛出 IllegalStateException。
// 1. 通过 ServletContext 动态注册 Servlet 实例
// 返回 ServletRegistration.Dynamic 接口以支持后续配置
ServletRegistration.Dynamic dynamic = servletContext.addServlet(
"dynamicOrderServlet",
new OrderServlet()
);
// 2. 绑定 URL 映射路径与启动加载优先级
// 必须在 ServletContext 初始化阶段完成调用
dynamic.addMapping("/api/orders/*");
dynamic.setLoadOnStartup(1);配置覆盖与合并规则
在实际工程中,web.xml、注解与编程式配置可能同时存在。Servlet 规范对多种配置方式的加载顺序与覆盖行为制定了明确规则。
metadata-complete
web.xml 根标签 <web-app> 提供了一个 metadata-complete 布尔属性,用于控制容器是否扫描字节码中的注解与 Web 分片(Web Fragment):
metadata-complete="false"(默认值):容器在启动时不仅解析web.xml,还会扫描所有类和 Jar 包中的@WebServlet、@WebFilter、@WebListener注解以及ServletContainerInitializer,并将所有配置合并。metadata-complete="true":容器认为web.xml中的元数据已经是完整且最终的,完全跳过注解扫描阶段。此时代码中标注的所有@WebServlet注解都会失效。
优先级与冲突处理
当 metadata-complete="false" 时,若同一个 Servlet 同时在 @WebServlet 和 web.xml 中进行了配置,容器按以下规则合并与覆盖(web.xml 优先级高于注解):
同名合并与覆盖:如果
web.xml中的<servlet-name>与@WebServlet(name = "...")完全一致,容器将两者视为同一个 Servlet 实例。此时web.xml中配置的<url-pattern>会直接覆盖注解中的urlPatterns,注解中的路径映射不再先生效;同理,同名的<init-param>也会覆盖@WebInitParam。异名重复实例化:如果
web.xml与@WebServlet指向同一个类,但两者的servlet-name不同,容器会将它们视为两个独立的 Servlet 实例,分别完成初始化并同时绑定各自的映射路径。
路由匹配规则
当请求到达容器时,容器会先从请求 URI 中去除应用上下文路径(Context Path),得到用于路由匹配的相对路径。Servlet 规范严格定义了四种合法的 url-pattern 语法格式,按匹配优先级从高到低依次为:精确匹配、路径匹配、扩展名匹配、缺省匹配。
容器解析请求 URL 并按优先级路由至目标 Servlet 的 UML 活动图如下:

精确匹配
精确匹配要求客户端请求的相对路径必须与配置的 url-pattern 字符串完全一致(区分大小写)。配置格式必须以正斜杠 / 开头,且不包含通配符 *。
- 配置示例:
/user/login、/order/create.html - 匹配示例:配置为
/user/login时,仅当请求路径严格为/user/login时才会命中;访问/user/login/或/user/login/1均不会命中。 - 优先级:最高(第 1 级)。
路径匹配
路径匹配(又称前缀匹配)以正斜杠 / 开头,并以 /* 结尾,用于匹配某个目录前缀下的所有子路径。
- 配置示例:
/user/*、/api/v1/*、/* - 匹配示例:配置为
/user/*时,可匹配/user/profile、/user/detail/101以及/user本身。 - 最长路径优先原则:当存在多个路径匹配规则同时覆盖当前请求时,路径前缀最长的规则优先生效。例如请求
/user/vip/list同时符合/user/*和/user/vip/*,容器会优先派发给/user/vip/*对应的 Servlet。 - 优先级:次高(第 2 级),仅次于精确匹配。
扩展名匹配
扩展名匹配(又称后缀匹配)以 *. 开头,后接具体的文件扩展名,用于拦截所有以特定后缀结尾的请求,而不关心其前置目录层级。注意扩展名匹配绝不能以 / 开头。
- 配置示例:
*.do、*.action、*.jsp - 匹配示例:配置为
*.do时,无论是/login.do还是/a/b/c/pay.do均会命中。 - 非法混用限制:规范严禁将路径匹配与扩展名匹配混用。例如
/user/*.do或/*.do均属于非法语法,Web 容器在启动解析阶段会直接抛出IllegalArgumentException导致应用启动失败。 - 优先级:第 3 级,低于所有的精确匹配与路径匹配。
缺省匹配
缺省匹配仅包含一个单独的正斜杠 /,表示当前应用的默认路由(Default Servlet)。当一个请求既未命中精确匹配,也未命中任何路径匹配和扩展名匹配时,最终会交由配置了 / 的缺省 Servlet 兜底处理。
- 配置示例:
/ - 容器内置
DefaultServlet:在 Tomcat 等容器的全局conf/web.xml中,默认已经注册了一个名为default、映射路径为/的内置DefaultServlet,专门负责读取静态资源文件(如.html、.css、.js、.png)以及在找不到资源时生成404 Not Found响应。 - 覆盖风险:如果开发者在自己的应用中显式将一个自定义 Servlet 映射到
/,则会覆盖容器内置的DefaultServlet,导致所有静态资源请求全部进入自定义 Servlet 而无法正常访问。 - 优先级:最低(第 4 级)。
/ 与 /* 的核心区别
在路由配置中,/ 与 /* 极易混淆,但两者在容器内部的语义和优先级截然不同:
| 对比维度 | 路径匹配 /* | 缺省匹配 / |
|---|---|---|
| 匹配分类 | 属于路径匹配(前缀通配符) | 属于缺省匹配(Default Servlet) |
| 匹配优先级 | 第 2 级(高于扩展名匹配 *.jsp、*.do) | 第 4 级(最低,仅在其他规则全部落空时生效) |
| 对 JSP 的影响 | 会强制拦截 *.jsp 请求,导致 JSP 无法交由 JspServlet 编译渲染 | 不会拦截 *.jsp,因为 *.jsp 属于扩展名匹配(第 3 级),优先于 / |
| 典型应用场景 | 通常用于 Filter(过滤器)拦截全站请求,极少用于 Servlet | 常用于前端控制器(如 Spring MVC 的 DispatcherServlet)接管全站未匹配路由 |
映射匹配优先级与综合示例
假设当前 Web 应用中注册了以下 5 个映射规则,下表展示了不同请求路径到达时的匹配决策过程:
| 已注册规则编号 | 配置的 url-pattern | 所属匹配类型 | 绑定的目标组件 |
|---|---|---|---|
| 规则 A | /abc/def | 精确匹配(第 1 级) | ServletA |
| 规则 B | /abc/* | 路径匹配(第 2 级,前缀较短) | ServletB |
| 规则 C | /abc/vip/* | 路径匹配(第 2 级,前缀较长) | ServletC |
| 规则 D | *.do | 扩展名匹配(第 3 级) | ServletD |
| 规则 E | / | 缺省匹配(第 4 级) | ServletE |
当客户端发起不同请求时,容器的派发结果如下:
请求
/abc/def:同时符合规则 A(精确匹配)和规则 B(路径匹配)。由于精确匹配优先级最高,最终派发给ServletA。请求
/abc/def.do:同时符合规则 B(路径匹配/abc/_)和规则 D(扩展名匹配_.do)。由于路径匹配(第 2 级)优先于扩展名匹配(第 3 级),最终派发给ServletB。请求
/abc/vip/order.do:同时符合规则 B(/abc/_)、规则 C(/abc/vip/_)和规则 D(_.do)。首先路径匹配优先于扩展名匹配,排除规则 D;其次在路径匹配内部遵循“最长前缀优先”原则,/abc/vip/_长于/abc/\*,最终派发给ServletC。请求
/user/login.do:精确匹配与路径匹配均未命中,命中规则 D(扩展名匹配\*.do),最终派发给ServletD。请求
/static/logo.png:前三级匹配全部落空,最终由兜底的规则 E(缺省匹配/)接管,派发给ServletE。
ServletConfig 接口
在 Java Web 应用开发中,编写业务 Servlet 时常需要注入一些外部配置信息(例如字符编码集、第三方接口密钥、超时时间或文件路径)。如果将这些参数硬编码在 Java 源码中,每次修改参数都必须重新编译打包。为此,Servlet 规范提供了 jakarta.servlet.ServletConfig(旧版为 javax.servlet.ServletConfig)接口,专门用于在 Servlet 初始化阶段向其传递局部配置信息。
每个注册的 Servlet 在 Web 容器中都拥有一个唯一且专属的 ServletConfig 实例。不同 Servlet 之间的 ServletConfig 对象完全隔离,一个 Servlet 无法通过自己的 ServletConfig 读取其他 Servlet 的初始化参数。
架构与装配机制
ServletConfig 对象的生命周期与对应的 Servlet 实例紧密绑定,完全由 Web 容器负责创建与装配。
当容器启动或首次接收到匹配请求、准备初始化某个 Servlet 时,内部装配与委托流程如下:
解析配置元数据:Web 容器读取
web.xml中该<servlet>标签下的<init-param>,或扫描类上的@WebInitParam注解,提取出所有键值对参数。创建配置对象:容器为该 Servlet 专门创建一个实现了
ServletConfig接口的内部封装对象(例如在 Apache Tomcat 中,容器使用StandardWrapper维护 Servlet 元数据,并通过门面类StandardWrapperFacade实现ServletConfig接口以限制外部非法访问容器内部方法)。关联全局上下文:容器将代表整个 Web 应用的
ServletContext引用注入到该ServletConfig对象中。传入初始化方法:容器调用
Servlet.init(ServletConfig config)方法,将组装完毕的ServletConfig实例传递给 Servlet。基类保存与方法委托:
GenericServlet同时实现了Servlet和ServletConfig接口,它在init(ServletConfig)中将传入的配置对象保存至内部成员变量this.config,并将自身实现的getInitParameter等方法全部委托给this.config执行。
Web 容器(以 Tomcat 为例)装配 ServletConfig 并由 GenericServlet 进行委托的 UML 类图如下:

ServletConfig
ServletConfig 接口结构非常精简,一共只定义了 4 个只读方法,用于在运行时获取当前 Servlet 的身份标识、局部初始化参数以及全局上下文对象。
getServletName
public String getServletName() 方法用于返回当前 Servlet 实例在容器中注册的唯一标识名称:
- 若通过
web.xml配置,返回<servlet-name>标签中定义的字符串。 - 若通过
@WebServlet注解配置且显式指定了name属性,返回该属性的值。 - 若通过
@WebServlet注解配置但未指定name属性,默认返回当前 Servlet 类的完整限定类名(如com.example.servlet.MailServlet)。
getInitParameter
public String getInitParameter(String name) 方法根据指定的参数名(区分大小写)获取对应的局部初始化参数值:
- 所有初始化参数在底层均以
String类型存储;若业务需要数值或布尔类型,需在获取后自行转换(如Integer.parseInt())。 - 如果指定的参数名不存在,该方法返回
null;若传入的参数名name本身为null,则会抛出NullPointerException。
getInitParameterNames
public Enumeration<String> getInitParameterNames() 方法返回当前 Servlet 所有局部初始化参数名称的枚举集合(Enumeration<String>):
- 开发者可结合
hasMoreElements()与nextElement()遍历所有参数键名,再配合getInitParameter(name)批量读取配置。 - 如果当前 Servlet 没有配置任何初始化参数,该方法会返回一个空的
Enumeration对象(而非null),因此遍历前无需进行非空判断。
getServletContext
public ServletContext getServletContext() 方法返回当前 Servlet 所属 Web 应用的全局上下文对象(ServletContext):
ServletConfig是连接“局部 Servlet 组件”与“全局 Web 应用环境”的桥梁。- 容器在初始化
ServletConfig时会将全局唯一的ServletContext引用存入其中,使 Servlet 能够随时通过配置对象访问应用级共享数据与容器服务。
局部参数配置方式
在 Java Web 应用中,向 ServletConfig 注入局部初始化参数共有三种标准方式。无论采用哪种方式,Servlet 内部读取参数的 API 代码完全一致。
web.xml
在 WEB-INF/web.xml 中,局部初始化参数通过 <init-param> 标签声明,且必须嵌套在目标 <servlet> 标签内部。每个 <init-param> 包含一个 <param-name>(参数键)和一个 <param-value>(参数值)。
<!-- 1. 注册 Servlet 组件 -->
<!-- init-param 必须声明在对应的 servlet 标签内部 -->
<servlet>
<servlet-name>mailServlet</servlet-name>
<servlet-class>com.example.servlet.MailServlet</servlet-class>
<!-- 2. 配置第一个局部初始化参数:邮件服务器地址 -->
<!-- 仅当前 mailServlet 实例可通过 ServletConfig 读取 -->
<init-param>
<param-name>smtpHost</param-name>
<param-value>smtp.example.com</param-value>
</init-param>
<!-- 3. 配置第二个局部初始化参数:连接超时毫秒数 -->
<!-- 所有参数值在底层均以字符串形式存储 -->
<init-param>
<param-name>timeout</param-name>
<param-value>5000</param-value>
</init-param>
</servlet>@WebInitParam
在使用注解开发时,可通过 @WebServlet 的 initParams 属性嵌套一个或多个 @WebInitParam 注解来声明局部参数。
// 1. 使用 @WebInitParam 声明局部初始化参数
// 容器启动或首次加载时将其封装至专属的 ServletConfig 实例中
@WebServlet(
name = "mailServlet",
urlPatterns = "/mail/send",
initParams = {
@WebInitParam(name = "smtpHost", value = "smtp.example.com"),
@WebInitParam(name = "timeout", value = "5000")
}
)
public class MailServlet extends HttpServlet {
private String smtpHost;
// 2. 在无参 init 方法中直接调用继承自 GenericServlet 的委托方法
// 等价于调用 this.getServletConfig().getInitParameter("smtpHost")
@Override
public void init() throws ServletException {
this.smtpHost = this.getInitParameter("smtpHost");
}
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException {
// 3. 获取显式的 ServletConfig 引用并读取 Servlet 注册名称
// 输出结果为注解或 web.xml 中定义的 name 属性值
ServletConfig config = this.getServletConfig();
String servletName = config.getServletName();
// 4. 遍历当前 Servlet 实例的所有初始化参数名称与对应值
// getInitParameterNames 返回包含所有键名的 Enumeration 枚举对象
Enumeration<String> paramNames = config.getInitParameterNames();
while (paramNames.hasMoreElements()) {
String name = paramNames.nextElement();
String value = config.getInitParameter(name);
resp.getWriter().println(servletName + " -> " + name + ": " + value);
}
}
}setInitParameter
在采用编程式动态注册 Servlet 时,可通过 ServletRegistration.Dynamic 接口继承自 Registration 的 setInitParameter(String name, String value) 或 setInitParameters(Map<String, String> initParameters) 方法注入局部参数。
// 1. 在容器启动阶段通过 ServletContext 动态注册 Servlet
// 获取用于动态配置的 ServletRegistration.Dynamic 实例
ServletRegistration.Dynamic dynamic = servletContext.addServlet(
"mailServlet",
MailServlet.class
);
// 2. 向当前 Servlet 注入局部初始化参数
// 注入的参数最终会封装至该 Servlet 专属的 ServletConfig 对象中
dynamic.setInitParameter("smtpHost", "smtp.example.com");
dynamic.setInitParameter("timeout", "5000");
dynamic.addMapping("/mail/send");配置获取与初始化陷阱
在继承 HttpServlet 编写业务类时,理解 GenericServlet 对 ServletConfig 的封装机制,能够避免常见的空指针异常。
GenericServlet
由于 GenericServlet 已经实现了 ServletConfig 接口,并在内部将所有方法委托给成员变量 config,因此在 HttpServlet 的子类中,以下两种获取配置的方式完全等价:
先获取配置对象再调用:
this.getServletConfig().getInitParameter("smtpHost")。直接调用实例方法:
this.getInitParameter("smtpHost")或this.getServletContext()。
init
在实际开发中,切勿在构造方法(Constructor)中调用 getInitParameter(),因为执行构造器时容器尚未调用 init(ServletConfig),此时内部 config 引用必为 null。
此外,在重写 init 方法读取配置时,必须注意带参 init(ServletConfig) 与无参 init() 的区别:
重写带参
init(ServletConfig)的隐患:如果子类直接重写了public void init(ServletConfig config),却忘记在方法体第一行调用super.init(config),那么父类GenericServlet中的this.config = config赋值逻辑就会被跳过。这会导致后续在doGet、doPost中调用getServletConfig()、getInitParameter()或getServletContext()时直接抛出NullPointerException。重写无参
init()的最佳实践:父类GenericServlet的带参init(ServletConfig)在保存完this.config后,会自动调用无参的init()钩子方法。因此,子类只需重写无参的public void init(),即可安全地直接调用this.getInitParameter()。java// 1. 方式一:重写带参 init(ServletConfig) 方法 // 必须在首行显式调用 super.init(config),否则父类 config 成员变量为 null @Override public void init(ServletConfig config) throws ServletException { // 2. 将容器传入的 config 对象交由父类 GenericServlet 保存 // 若遗漏此行,后续在 doGet 中调用 getInitParameter 将抛出 NullPointerException super.init(config); String host = config.getInitParameter("smtpHost"); } // 3. 方式二(推荐):直接重写 GenericServlet 提供的无参 init() 方法 // 父类已自动完成 config 成员变量的保存,可直接调用委托方法 @Override public void init() throws ServletException { String host = this.getInitParameter("smtpHost"); }
作用域与特性边界
在使用 ServletConfig 管理配置时,需要明确其设计边界与限制:
| 特性维度 | ServletConfig 详细规则 |
|---|---|
| 实例数量 | 每个注册的 <servlet> 或 @WebServlet 对应 1 个独立实例 |
| 作用域范围 | 局部作用域(Servlet 级别),仅对当前绑定的 Servlet 实例可见,其他 Servlet 无法访问 |
| 生命周期 | 在容器调用当前 Servlet 的 init 方法前创建,随当前 Servlet 实例的销毁而销毁 |
| 读写权限 | 运行期严格只读。接口仅提供 getInitParameter 读取方法,不提供任何运行期修改或删除参数的方法 |
| 数据类型限制 | 仅支持 String 类型的键值对配置,不支持像域对象(Attribute)那样挂载任意 Java 对象引用 |
API: ServletConfig
元数据获取
StringgetServletName():(),组件名称获取。返回当前 Servlet 实例在部署描述符(web.xml)或@WebServlet注解中注册的唯一标识名称;若属于未显式指定名称的匿名注册,则返回该 Servlet 实现类的完整限定类名。ServletContextgetServletContext():(),全局上下文获取。返回当前 Servlet 所属 Web 应用程序的ServletContext全局上下文单例对象,用于与 Web 容器交互或访问应用域共享资源。
注意事项:
ServletConfig实例由 Web 容器在初始化目标 Servlet 前创建并专属绑定,不同 Servlet 实例之间的ServletConfig彼此隔离,但它们调用getServletContext()返回的均是当前 Web 应用内同一个ServletContext引用。
import jakarta.servlet.ServletConfig;
import jakarta.servlet.ServletContext;
import java.lang.reflect.Proxy;
import java.util.Collections;
import java.util.Enumeration;
public class ServletConfigMetadataDemo {
public static void main(String[] args) {
ServletContext mockContext = (ServletContext) Proxy.newProxyInstance(
ServletContext.class.getClassLoader(),
new Class<?>[]{ServletContext.class},
(proxy, method, methodArgs) -> {
if ("getContextPath".equals(method.getName())) return "/mall";
return null;
}
);
ServletConfig config = new ServletConfig() {
@Override
public String getServletName() {
return "orderServlet";
}
@Override
public ServletContext getServletContext() {
return mockContext;
}
@Override
public String getInitParameter(String name) { return null; }
@Override
public Enumeration<String> getInitParameterNames() {
return Collections.emptyEnumeration();
}
};
// 1. 获取当前 Servlet 注册的唯一标识名称
String servletName = config.getServletName();
System.out.println("Servlet Name: " + servletName);
// 2. 获取当前 Servlet 关联的全局 ServletContext 对象
ServletContext context = config.getServletContext();
System.out.println("Context Path: " + context.getContextPath());
}
}参数读取
StringgetInitParameter():(String name),局部参数获取。根据指定的参数名称返回当前 Servlet 的局部初始化参数值(包含<init-param>或@WebInitParam配置项);若指定的参数名称不存在,则返回null。Enumeration<String>
getInitParameterNames():(),局部参数名枚举。返回当前 Servlet 所有局部初始化参数名称的Enumeration枚举集合;若当前 Servlet 未配置任何初始化参数,则返回一个空的Enumeration对象而非null。
注意事项:
getInitParameter()的参数名称严格区分大小写,且若传入的参数名name为null,容器实现将直接抛出NullPointerException。ServletConfig仅提供运行期只读的局部参数访问能力,无法读取<context-param>全局上下文参数,也不提供任何运行期动态修改或删除局部参数的方法。
import jakarta.servlet.ServletConfig;
import jakarta.servlet.ServletContext;
import java.util.Collections;
import java.util.Enumeration;
import java.util.LinkedHashMap;
import java.util.Map;
public class ServletConfigParamDemo {
public static void main(String[] args) {
Map<String, String> initParams = new LinkedHashMap<>();
initParams.put("smtpHost", "smtp.example.com");
initParams.put("timeout", "5000");
ServletConfig config = new ServletConfig() {
@Override
public String getServletName() { return "mailServlet"; }
@Override
public ServletContext getServletContext() { return null; }
@Override
public String getInitParameter(String name) {
return initParams.get(name);
}
@Override
public Enumeration<String> getInitParameterNames() {
return Collections.enumeration(initParams.keySet());
}
};
// 1. 根据参数名读取单个局部初始化参数值
String host = config.getInitParameter("smtpHost");
System.out.println("Direct read smtpHost: " + host);
// 2. 枚举并遍历当前 Servlet 的所有局部初始化参数
Enumeration<String> names = config.getInitParameterNames();
while (names.hasMoreElements()) {
String name = names.nextElement();
System.out.println(name + " = " + config.getInitParameter(name));
}
}
}ServletContext 接口
jakarta.servlet.ServletContext(早期版本为 javax.servlet.ServletContext)是 Servlet 规范中代表整个 Web 应用程序的核心接口,又称“全局应用上下文”。当 Web 容器启动并加载某个 Web 应用时,会为该应用创建一个全局唯一的 ServletContext 实例;当 Web 应用被卸载或容器关闭时,该实例随之销毁。
在同一个 JVM 进程内,一个 Web 应用只拥有一个 ServletContext 对象。应用内的所有 Servlet、Filter(过滤器)和 Listener(监听器)都共享这同一个实例,并通过它与 Web 容器进行交互、读取全局配置、加载应用内资源或在全局范围内共享数据。
架构与生命周期
在 Web 容器(以 Apache Tomcat 为例)内部,每个部署的 Web 应用对应一个 StandardContext 容器组件。为了防止业务代码通过强制类型转换调用容器内部的高危管理方法,Tomcat 采用门面模式(Facade Pattern),使用 ApplicationContext 封装 StandardContext,再对外暴露仅实现 ServletContext 接口的 ApplicationContextFacade 实例。
ServletContext 的底层实现结构以及与其他核心组件的引用关系如下:

ServletContext 的生命周期严格绑定于整个 Web 应用,分为三个阶段:
创建时机:Web 容器启动并加载 Web 应用时,在初始化任何 Filter 和 Servlet 之前(仅次于
ServletContainerInitializer),容器率先创建ServletContext实例,并触发ServletContextListener.contextInitialized事件。存活阶段:在整个 Web 应用运行期间,
ServletContext始终常驻内存,供所有并发请求与组件访问。销毁时机:当 Web 应用被停止、重新部署或容器正常关闭时,容器在调用完所有 Servlet 和 Filter 的
destroy()方法之后,触发ServletContextListener.contextDestroyed事件,最后销毁ServletContext实例并释放应用域内存。
实例获取方式
在业务代码中,开发者可以通过多种途径获取当前 Web 应用的 ServletContext 实例。无论通过哪种途径获取,返回的都是容器内同一个单例对象的引用(使用 == 比较结果恒为 true)。
ServletConfig
ServletConfig 接口定义了 getServletContext() 方法。由于 GenericServlet 已经实现了 ServletConfig 接口并完成了方法委托,因此在继承自 HttpServlet 的子类中,既可以通过 this.getServletConfig().getServletContext() 获取,也可以直接调用 this.getServletContext()。
ServletRequest
从 Servlet 3.0 规范开始,ServletRequest 接口新增了 getServletContext() 方法。在处理请求时,可以直接通过传入的 HttpServletRequest 对象调用 req.getServletContext() 获取全局上下文。
HttpSession
HttpSession 接口同样提供了 getServletContext() 方法,支持通过当前用户的会话对象 req.getSession().getServletContext() 获取全局上下文。
// 1. 通过继承自 GenericServlet 的方法直接获取
// 底层委托给 this.getServletConfig().getServletContext()
ServletContext ctxFromConfig = this.getServletContext();
// 2. 通过本次请求的 HttpServletRequest 对象获取
// Servlet 3.0 及以上版本支持直接从请求对象拿取全局上下文
ServletContext ctxFromReq = req.getServletContext();
// 3. 通过当前会话的 HttpSession 对象获取
// 三个途径获取到的引用指向容器内同一个实例,三者 == 比较结果为 true
ServletContext ctxFromSession = req.getSession().getServletContext();全局初始化参数
与 ServletConfig 仅针对单个 Servlet 的局部参数不同,ServletContext 维护的全局初始化参数(Context Init Parameters)对当前 Web 应用内的所有 Servlet、Filter 和 Listener 均可见,常用于配置全局字符集、系统环境标识或公共配置文件路径。
需要注意,标准 Servlet 规范没有提供用于配置全局初始化参数的注解(不存在类似 @WebContextParam 的注解),全局参数只能通过 web.xml 或编程式 API 配置。
context-param
在 WEB-INF/web.xml 中,全局初始化参数通过 <context-param> 标签声明,直接放置在根标签 <web-app> 下,绝不能嵌套在某个 <servlet> 标签内部。
<!-- 1. 配置第一个全局初始化参数:应用名称 -->
<!-- 直接声明在 web-app 根标签下,对所有 Servlet 与 Filter 可见 -->
<context-param>
<param-name>appName</param-name>
<param-value>OrderManagementSystem</param-value>
</context-param>
<!-- 2. 配置第二个全局初始化参数:全局字符集 -->
<!-- 不可嵌套在某个具体的 servlet 标签内部 -->
<context-param>
<param-name>globalCharset</param-name>
<param-value>UTF-8</param-value>
</context-param>setInitParameter
从 Servlet 3.0 开始,ServletContext 提供了 public boolean setInitParameter(String name, String value) 方法,支持通过代码动态写入全局初始化参数:
- 调用时机限制:该方法只能在容器启动阶段(即
ServletContextListener.contextInitialized或ServletContainerInitializer.onStartup执行期间)调用;一旦应用初始化完成,再调用该方法将抛出IllegalStateException。 - 防覆盖机制:如果指定的全局参数名已经存在(例如已在
web.xml中配置),该方法不会覆盖原有值,而是直接返回false;仅当设置成功时返回true。
getInitParameter
public String getInitParameter(String name) 方法用于根据参数名读取全局初始化参数的值。若参数不存在则返回 null。注意区分调用主体:读取 <context-param> 必须调用 ServletContext.getInitParameter,调用 ServletConfig.getInitParameter 只能读取当前 Servlet 的 <init-param>。
getInitParameterNames
public Enumeration<String> getInitParameterNames() 方法返回当前 Web 应用所有全局初始化参数名称的枚举集合;若未配置任何全局参数,则返回一个空的 Enumeration。
// 1. 获取全局唯一的 ServletContext 实例
// 不能使用 ServletConfig.getInitParameter 读取全局参数
ServletContext context = this.getServletContext();
// 2. 按参数名读取指定的全局初始化参数
// 若参数名不存在则返回 null
String appName = context.getInitParameter("appName");
// 3. 遍历当前 Web 应用配置的所有全局参数键名
// 结合 getInitParameter 批量获取配置值
Enumeration<String> names = context.getInitParameterNames();
while (names.hasMoreElements()) {
String name = names.nextElement();
String value = context.getInitParameter(name);
resp.getWriter().println(name + " = " + value);
}应用域数据共享
在 Servlet 规范中,能够在特定范围内通过键值对存取 Java 对象的组件被称为域对象(Scope Object)。ServletContext 是作用范围最大的域对象,称为应用域(Application Scope),其内部维护了一个全局的 Map<String, Object>(在 Tomcat 中底层为 ConcurrentHashMap)。
凡是存入 ServletContext 域中的数据,在整个 Web 应用运行期间,可被所有客户端请求和所有 Servlet 跨线程共享。
setAttribute
public void setAttribute(String name, Object object) 方法用于向应用域中存入或更新共享属性:
- 若指定的属性名不存在,则新增该键值对,并触发
ServletContextAttributeListener.attributeAdded事件。 - 若指定的属性名已存在,则使用新对象覆盖旧对象,并触发
attributeReplaced事件。 - 若传入的
object值本身为null,其效果等同于调用removeAttribute(name)。
getAttribute
public Object getAttribute(String name) 方法用于根据属性名从应用域中获取已存储的对象。由于返回值类型为 Object,获取后需根据实际存入的类型进行向下转型;若属性名不存在,则返回 null。
removeAttribute
public void removeAttribute(String name) 方法用于从应用域中彻底移除指定名称的属性,并触发 ServletContextAttributeListener.attributeRemoved 事件。
并发安全问题
虽然 Tomcat 等容器在 ServletContext 底层使用 ConcurrentHashMap 存储属性,保证了单次 getAttribute 或 setAttribute 调用不会破坏哈希表结构,但复合操作(如“先读取、再修改、后写回”)以及存入的可变对象本身并不是线程安全的。
由于所有请求工作线程并发访问同一个 ServletContext,在操作应用域属性时需遵守以下并发规范:
优先存储只读数据:应用域最适合存放启动时加载的全局只读字典、配置缓存或本身线程安全的连接池对象。
使用并发容器或原子类:若需要在应用域统计全局状态(如全站访问量计数),应直接存入
AtomicInteger、LongAdder或ConcurrentHashMap等并发安全对象,通过其自身的原子方法更新状态,避免非同步的“读-改-写”操作。java// 1. 向应用域存入线程安全的原子计数器对象 // 整个 Web 应用内的所有 Servlet 与请求均可访问该属性 ServletContext context = this.getServletContext(); context.setAttribute("visitCount", new AtomicInteger(0)); // 2. 从应用域读取共享属性并执行向下转型 // 使用 AtomicInteger.incrementAndGet() 保证多线程并发累加安全 AtomicInteger counter = (AtomicInteger) context.getAttribute("visitCount"); int currentVisits = counter.incrementAndGet(); // 3. 从应用域移除指定的全局属性 // 移除后再次调用 getAttribute("tempCache") 将返回 null context.removeAttribute("tempCache");
路径解析与资源读取
在 Web 应用打包部署到服务器后,项目目录结构与开发阶段的源码目录结构存在明显差异(例如 Java 源码被编译至 /WEB-INF/classes 目录下)。如果在代码中使用 new FileInputStream("db.properties") 等相对路径读取文件,JVM 会以容器启动命令所在的目录(如 tomcat/bin)作为相对路径起点,从而导致 FileNotFoundException。
ServletContext 提供了感知 Web 应用根目录的路径转换与资源读取 API,彻底屏蔽了底层部署目录的差异。
getContextPath
public String getContextPath() 方法用于获取当前 Web 应用在容器中部署的上下文路径前缀(Context Path):
- 如果应用以子路径形式部署(例如访问地址为
http://localhost:8080/mall/index.html),该方法返回"/mall"(以/开头,但不以/结尾)。 - 如果应用部署在容器的默认根上下文下(例如 Tomcat 的
webapps/ROOT目录,访问地址为http://localhost:8080/index.html),该方法返回空字符串""。 - 该方法常用于在重定向(
sendRedirect)或生成前端页面链接时动态拼接应用前缀,避免硬编码上下文名称。
getRealPath
public String getRealPath(String path) 方法用于将 Web 应用内的虚拟相对路径(以 / 开头,代表当前 Web 应用的根目录)转换为服务器操作系统磁盘上的绝对物理路径。
- 例如当应用部署在
/opt/tomcat/webapps/mall时,调用context.getRealPath("/WEB-INF/config.xml")将返回"/opt/tomcat/webapps/mall/WEB-INF/config.xml"。 - 使用局限性:如果 Web 容器配置为不解压
.war归档文件直接运行(如unpackWARs="false")或从远程存储加载应用,服务器磁盘上根本不存在对应的解压目录,此时调用getRealPath必定返回null。
getResourceAsStream
public InputStream getResourceAsStream(String path) 方法直接以字节输入流的形式读取 Web 应用内的指定资源文件。
参数
path必须以正斜杠/开头,代表当前 Web 应用的根目录(即包含WEB-INF的那一层目录)。若要读取 Maven/Gradle 项目
src/main/resources下的配置文件(编译后位于WEB-INF/classes目录),应传入"/WEB-INF/classes/文件名"。核心优势:即使应用以未解压的
.war包形式直接运行,getResourceAsStream依然能够直接从压缩包内流式读取文件内容,不会像getRealPath那样失效返回null。java// 1. 获取当前 Web 应用部署的上下文路径 // 例如返回 "/shop",若部署为 ROOT 根应用则返回空字符串 "" ServletContext context = this.getServletContext(); String contextPath = context.getContextPath(); // 2. 将 Web 根路径下的相对路径映射为服务器磁盘绝对路径 // 若 WAR 包未解压直接运行,该方法会返回 null String realPath = context.getRealPath("/WEB-INF/config/app.properties"); // 3. 以字节输入流形式直接读取 Web 应用内的资源文件 // 路径必须以 "/" 开头,代表当前 Web 应用的根目录 try (InputStream in = context.getResourceAsStream("/WEB-INF/classes/db.properties")) { Properties props = new Properties(); props.load(in); }
全局上下文与局部配置对比
ServletContext 与第 5 章介绍的 ServletConfig 均能提供初始化参数读取功能,但两者的职责边界与作用域截然不同:
| 对比维度 | ServletConfig(局部配置) | ServletContext(全局上下文) |
|---|---|---|
| 实例数量 | 每个注册的 Servlet 实例各自拥有 1 个独立对象 | 整个 Web 应用全局仅拥有 1 个单例对象 |
| 作用域范围 | 仅对当前绑定的单个 Servlet 可见 | 对当前 Web 应用内的所有 Servlet、Filter、Listener 可见 |
| XML 配置标签 | 嵌套在 <servlet> 内部的 <init-param> | 直接声明在 <web-app> 根标签下的 <context-param> |
| 注解配置支持 | 支持 @WebServlet 嵌套 @WebInitParam | 无对应标准注解,仅支持 web.xml 或编程式设置 |
| 域对象能力 | 不是域对象,不支持 setAttribute 动态存取数据 | 是应用域对象,支持通过 setAttribute 全局共享对象 |
| 附加核心能力 | 仅提供 Servlet 名称、局部参数与全局上下文引用 | 提供路径解析、资源流加载、日志记录、动态注册组件等能力 |
API: ServletContext
环境信息
final StringServletContext.TEMPDIR:临时目录属性名。常量值为"jakarta.servlet.context.tempdir"(旧版为"javax.servlet.context.tempdir"),用于通过getAttribute()获取 Web 容器为当前应用分配的专属磁盘临时目录(返回类型为File)。final StringServletContext.ORDERED_LIBS:依赖排序属性名。常量值为"jakarta.servlet.context.orderedLibs",用于通过getAttribute()获取当前 Web 应用内WEB-INF/lib下按加载顺序排列的 Jar 包名称列表(返回类型为List<String>)。StringgetContextPath():(),上下文路径获取。返回当前 Web 应用在容器中部署的 URI 路径前缀(以/开头但不以/结尾);若应用部署在容器的默认根路径(ROOT)下,则返回空字符串""。StringgetServletContextName():(),应用显示名获取。返回当前 Web 应用在web.xml的<display-name>标签中声明的名称;若未声明则返回null。StringgetServerInfo():(),容器信息获取。返回当前运行环境的 Web 容器名称与版本号字符串(格式如"Apache Tomcat/10.1.30")。StringgetVirtualServerName():(),虚拟主机名获取。返回当前 Web 应用所属逻辑虚拟主机的配置名称(格式通常包含引擎名与主机名,如"Catalina/localhost")。intgetMajorVersion():(),规范主版本获取。返回当前 Web 容器所支持的 Servlet 规范最高主版本号(例如支持 Servlet 6.0 的容器返回6)。intgetMinorVersion():(),规范次版本获取。返回当前 Web 容器所支持的 Servlet 规范最高次版本号(例如支持 Servlet 6.0 的容器返回0)。intgetEffectiveMajorVersion():(),生效主版本获取。返回当前 Web 应用自身部署描述符(web.xml)所声明采用的 Servlet 规范主版本号。intgetEffectiveMinorVersion():(),生效次版本获取。返回当前 Web 应用自身部署描述符(web.xml)所声明采用的 Servlet 规范次版本号。StringgetMimeType():(String file),媒体类型推断。根据传入的文件名后缀匹配容器内置或web.xml配置的<mime-mapping>映射表,返回对应的 MIME 内容类型字符串(如"text/html"、"image/png");若无法识别则返回null。ClassLoadergetClassLoader():(),类加载器获取。返回用于加载当前 Web 应用类路径(WEB-INF/classes与WEB-INF/lib)的专属类加载器实例。log():容器日志记录重载族。将指定的应用运行日志或异常堆栈信息写入 Web 容器的统一日志文件中。
void:(String msg),纯文本日志记录。将指定的普通文本消息写入当前 Web 容器的日志文件中。void:(String message, Throwable throwable),异常堆栈日志记录。将指定的错误描述消息以及关联的Throwable异常完整调用栈一并写入容器日志文件中。
注意事项:
- 每个 Web 应用在启动时,Web 容器都必须创建一个可写的专属临时目录,并以
ServletContext.TEMPDIR为键存入应用域属性中,供文件上传等场景缓存临时文件。- 早期规范中的
log(Exception exception, String msg)、获取 Servlet 实例的getServlet(String)、getServlets()、getServletNames()方法均已在早期版本中废弃,并在 Jakarta Servlet 6.0 中被彻底移除。
import jakarta.servlet.ServletContext;
import java.io.File;
import java.lang.reflect.Proxy;
public class ServletContextEnvDemo {
public static void main(String[] args) {
ServletContext context = (ServletContext) Proxy.newProxyInstance(
ServletContext.class.getClassLoader(),
new Class<?>[]{ServletContext.class},
(proxy, method, methodArgs) -> {
switch (method.getName()) {
case "getContextPath": return "/mall";
case "getServletContextName": return "MallWebApp";
case "getServerInfo": return "Apache Tomcat/10.1.30";
case "getVirtualServerName": return "default-host/localhost";
case "getMajorVersion": return 6;
case "getMinorVersion": return 0;
case "getEffectiveMajorVersion": return 6;
case "getEffectiveMinorVersion": return 0;
case "getMimeType": return "image/png";
case "getClassLoader": return ServletContextEnvDemo.class.getClassLoader();
case "getAttribute":
if (ServletContext.TEMPDIR.equals(methodArgs[0])) {
return new File(System.getProperty("java.io.tmpdir"));
}
return null;
case "log":
System.out.println("[Container Log] " + methodArgs[0]);
return null;
default: return null;
}
}
);
// 1. 读取容器内置临时目录常量属性与上下文基础标识信息
File tempDir = (File) context.getAttribute(ServletContext.TEMPDIR);
System.out.println("Temp Dir (" + ServletContext.TEMPDIR + "): " + tempDir);
System.out.println("Context Path: " + context.getContextPath());
System.out.println("Context Name: " + context.getServletContextName());
System.out.println("Server Info: " + context.getServerInfo());
System.out.println("Virtual Server: " + context.getVirtualServerName());
// 2. 获取容器支持的 Servlet 规范版本与文件 MIME 类型
System.out.println("Servlet Version: " + context.getMajorVersion() + "." + context.getMinorVersion());
System.out.println("MIME Type of logo.png: " + context.getMimeType("logo.png"));
System.out.println("ClassLoader: " + context.getClassLoader());
// 3. 调用 log 重载方法向容器日志通道输出普通文本与异常堆栈
context.log("Application environment initialized");
context.log("Simulated warning with exception", new IllegalArgumentException("Invalid arg"));
}
}参数配置
StringgetInitParameter():(String name),全局参数读取。根据指定的参数名称读取当前 Web 应用的全局上下文初始化参数(<context-param>或编程式注入项);若参数不存在则返回null。Enumeration<String>getInitParameterNames():(),全局参数名枚举。返回当前 Web 应用所有全局初始化参数名称的Enumeration枚举集合;若无任何参数则返回空枚举。booleansetInitParameter():(String name, String value),全局参数动态写入。在容器启动阶段向当前应用动态写入指定的全局初始化参数;若设置成功返回true,若同名全局参数已存在则放弃覆盖并返回false。StringgetRequestCharacterEncoding():(),请求默认编码获取。返回当前 Web 应用全局配置的默认请求字符编码名称(自 Servlet 4.0 引入);若未配置则返回null。voidsetRequestCharacterEncoding():(String encoding),请求默认编码设置。在容器启动阶段统一设置当前 Web 应用所有请求的默认字符编码集(等价于<request-character-encoding>)。StringgetResponseCharacterEncoding():(),响应默认编码获取。返回当前 Web 应用全局配置的默认响应字符编码名称(自 Servlet 4.0 引入);若未配置则返回null。voidsetResponseCharacterEncoding():(String encoding),响应默认编码设置。在容器启动阶段统一设置当前 Web 应用所有响应的默认字符编码集(等价于<response-character-encoding>)。intgetSessionTimeout():(),会话超时获取。返回当前 Web 应用全局配置的默认HttpSession空闲超时时间(单位:分钟,自 Servlet 4.0 引入)。voidsetSessionTimeout():(int sessionTimeout),会话超时设置。在容器启动阶段设置全局默认的HttpSession空闲超时时间(单位:分钟);若传入0或负数表示会话永不超时。SessionCookieConfig
getSessionCookieConfig():(),会话 Cookie 配置获取。返回用于配置会话追踪 Cookie(如JSESSIONID的名称、HttpOnly、Secure、MaxAge属性)的SessionCookieConfig对象。voidsetSessionTrackingModes():(Set<SessionTrackingMode> sessionTrackingModes),会话追踪模式设置。在容器启动阶段指定当前 Web 应用启用的会话追踪机制集合(可选值包括COOKIE、URL、SSL)。Set<SessionTrackingMode>
getDefaultSessionTrackingModes():(),默认追踪模式获取。返回当前 Web 容器默认支持的会话追踪模式不可变集合。Set<SessionTrackingMode>
getEffectiveSessionTrackingModes():(),生效追踪模式获取。返回当前 Web 应用实际正在生效的会话追踪模式不可变集合。JspConfigDescriptorgetJspConfigDescriptor():(),JSP 配置描述符获取。返回汇总了web.xml与 Web 分片中<jsp-config>标签配置的描述符对象;若未配置则返回null。voiddeclareRoles():(String... roleNames),安全角色声明。在容器启动阶段编程式声明当前 Web 应用使用到的安全角色名称列表(供HttpServletRequest.isUserInRole校验使用)。
注意事项:
- 所有带修改语义的配置方法(包括
setInitParameter()、setRequestCharacterEncoding()、setResponseCharacterEncoding()、setSessionTimeout()、setSessionTrackingModes()、declareRoles()以及对getSessionCookieConfig()返回对象的写操作)只能在ServletContextListener.contextInitialized()或ServletContainerInitializer.onStartup()阶段调用;一旦应用完成初始化开始接收请求,再调用这些方法将直接抛出IllegalStateException。
import jakarta.servlet.ServletContext;
import jakarta.servlet.SessionTrackingMode;
import java.lang.reflect.Proxy;
import java.util.Collections;
import java.util.Enumeration;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Set;
public class ServletContextConfigDemo {
public static void main(String[] args) {
Map<String, String> initParams = new LinkedHashMap<>();
initParams.put("appName", "OrderSystem");
final int[] sessionTimeout = {30};
final String[] reqEncoding = {"UTF-8"};
ServletContext context = (ServletContext) Proxy.newProxyInstance(
ServletContext.class.getClassLoader(),
new Class<?>[]{ServletContext.class},
(proxy, method, methodArgs) -> {
switch (method.getName()) {
case "setInitParameter":
return initParams.putIfAbsent((String) methodArgs[0], (String) methodArgs[1]) == null;
case "getInitParameter":
return initParams.get((String) methodArgs[0]);
case "getInitParameterNames":
return Collections.enumeration(initParams.keySet());
case "setSessionTimeout":
sessionTimeout[0] = (Integer) methodArgs[0];
return null;
case "getSessionTimeout":
return sessionTimeout[0];
case "setRequestCharacterEncoding":
reqEncoding[0] = (String) methodArgs[0];
return null;
case "getRequestCharacterEncoding":
return reqEncoding[0];
case "getEffectiveSessionTrackingModes":
return Set.of(SessionTrackingMode.COOKIE);
default: return null;
}
}
);
// 1. 动态写入全局初始化参数并校验同名参数防覆盖机制
boolean addedNew = context.setInitParameter("env", "production");
boolean addedDuplicate = context.setInitParameter("appName", "NewName");
System.out.println("Added env: " + addedNew + ", Duplicate appName: " + addedDuplicate);
// 2. 读取并枚举所有全局初始化参数
Enumeration<String> names = context.getInitParameterNames();
while (names.hasMoreElements()) {
String key = names.nextElement();
System.out.println(key + " = " + context.getInitParameter(key));
}
// 3. 配置并读取全局会话超时时间、请求字符编码与会话追踪模式
context.setSessionTimeout(60);
context.setRequestCharacterEncoding("UTF-8");
System.out.println("Session Timeout (min): " + context.getSessionTimeout());
System.out.println("Request Encoding: " + context.getRequestCharacterEncoding());
System.out.println("Tracking Modes: " + context.getEffectiveSessionTrackingModes());
}
}属性管理
ObjectgetAttribute():(String name),应用域属性读取。根据指定的属性名称从全局应用域中获取共享的 Java 对象引用;若属性不存在则返回null。Enumeration<String>getAttributeNames():(),应用域属性名枚举。返回当前应用域中已绑定的所有属性名称的Enumeration枚举集合。voidsetAttribute():(String name, Object object),应用域属性写入。将给定的对象绑定到全局应用域的指定名称下;若同名属性已存在则覆盖旧值并触发ServletContextAttributeListener.attributeReplaced事件,若传入的object为null则等效于调用removeAttribute(name)。voidremoveAttribute():(String name),应用域属性移除。从全局应用域中彻底移除指定名称的属性,并触发ServletContextAttributeListener.attributeRemoved事件。
注意事项:
- 应用域属性在整个 Web 应用运行期内被所有并发请求线程共享,单次
getAttribute()与setAttribute()调用虽由容器底层并发哈希表保障结构安全,但“先读后改再写”的复合操作不具备原子性,存储可变状态时必须自行同步或使用 JUC 并发安全类。- 属性名称建议避免使用
java.、javax.、jakarta.、sun.或com.sun.前缀,这些命名空间被规范保留供容器内部系統属性使用。
import jakarta.servlet.ServletContext;
import java.lang.reflect.Proxy;
import java.util.Collections;
import java.util.Enumeration;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
public class ServletContextAttributeDemo {
public static void main(String[] args) {
Map<String, Object> attributes = new ConcurrentHashMap<>();
ServletContext context = (ServletContext) Proxy.newProxyInstance(
ServletContext.class.getClassLoader(),
new Class<?>[]{ServletContext.class},
(proxy, method, methodArgs) -> {
switch (method.getName()) {
case "setAttribute":
if (methodArgs[1] == null) {
attributes.remove((String) methodArgs[0]);
} else {
attributes.put((String) methodArgs[0], methodArgs[1]);
}
return null;
case "getAttribute":
return attributes.get((String) methodArgs[0]);
case "removeAttribute":
attributes.remove((String) methodArgs[0]);
return null;
case "getAttributeNames":
return Collections.enumeration(attributes.keySet());
default: return null;
}
}
);
// 1. 向应用域存入全局共享属性并根据属性名读取
context.setAttribute("siteTitle", "Java Developer Portal");
context.setAttribute("maxConnections", 200);
System.out.println("siteTitle: " + context.getAttribute("siteTitle"));
// 2. 枚举当前应用域中存在的所有属性名称
Enumeration<String> attrNames = context.getAttributeNames();
while (attrNames.hasMoreElements()) {
String name = attrNames.nextElement();
System.out.println("Attribute [" + name + "] = " + context.getAttribute(name));
}
// 3. 从应用域移除指定属性并验证读取结果
context.removeAttribute("maxConnections");
System.out.println("After remove maxConnections: " + context.getAttribute("maxConnections"));
}
}资源调度
StringgetRealPath():(String path),物理路径转换。将当前 Web 应用根目录下的虚拟相对路径(如"/WEB-INF/web.xml")转换为宿主操作系统磁盘上的绝对物理路径;若应用以未解压的.war归档包形式直接运行或资源不存在无法映射,则返回null。URLgetResource():(String path),资源 URL 获取。返回指向当前 Web 应用内指定虚拟路径(必须以'/'开头,包含WEB-INF/lib/*.jar内的/META-INF/resources静态资源)的URL对象;若资源不存在则返回null。InputStreamgetResourceAsStream():(String path),资源字节流获取。直接打开并返回读取当前 Web 应用内指定虚拟路径资源的InputStream字节输入流;即使应用以未解压的.war包形式运行也能正常读取,若资源不存在则返回null。Set<String>getResourcePaths():(String path),目录资源路径枚举。返回当前 Web 应用内指定目录路径(必须以'/'开头)下所有直属文件及子目录虚拟路径的不可变集合(子目录路径以'/'结尾);若目录为空或不存在则返回null。RequestDispatchergetRequestDispatcher():(String path),路径请求调度器获取。根据以'/'开头的上下文相对路径封装并返回RequestDispatcher实例,用于将请求服务端转发(forward)或包含(include)至目标资源;若路径不以'/'开头或无法解析则返回null。RequestDispatchergetNamedDispatcher():(String name),命名请求调度器获取。根据 Servlet 在容器中的注册名称(servlet-name)封装并返回RequestDispatcher实例,常用于向未绑定公开 URL 映射的内部 Servlet 或容器内置default、jsp组件转发请求;若找不到对应名称则返回null。ServletContextgetContext():(String uripath),跨应用上下文获取。根据以'/'开头的外部 URI 路径返回同一容器中对应其他 Web 应用的ServletContext对象,用于跨应用请求调度;出于安全隔离考虑,主流容器默认禁用跨上下文访问并返回null(需在容器配置中显式开启crossContext="true")。
注意事项:
ServletContext.getRequestDispatcher(String path)的参数path必须以正斜杠'/'开头(代表当前 Web 应用的根目录),不支持不带'/'的相对路径;而ServletRequest.getRequestDispatcher(String path)则同时支持以'/'开头的绝对路径和相对于当前请求目录的相对路径。getResource()与getResourceAsStream()传入的path同样必须以'/'开头(否则getResource()将抛出MalformedURLException),其根目录对应打包后的 Web 根目录(即WEB-INF所在的父目录),读取类路径资源时需传入"/WEB-INF/classes/..."。
import jakarta.servlet.RequestDispatcher;
import jakarta.servlet.ServletContext;
import java.io.ByteArrayInputStream;
import java.io.InputStream;
import java.lang.reflect.Proxy;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.util.Set;
public class ServletContextResourceDemo {
public static void main(String[] args) throws Exception {
RequestDispatcher mockDispatcher = (RequestDispatcher) Proxy.newProxyInstance(
RequestDispatcher.class.getClassLoader(),
new Class<?>[]{RequestDispatcher.class},
(proxy, method, methodArgs) -> null
);
ServletContext context = (ServletContext) Proxy.newProxyInstance(
ServletContext.class.getClassLoader(),
new Class<?>[]{ServletContext.class},
(proxy, method, methodArgs) -> {
switch (method.getName()) {
case "getRealPath":
return "/opt/tomcat/webapps/mall" + methodArgs[0];
case "getResourcePaths":
return Set.of("/WEB-INF/web.xml", "/WEB-INF/classes/");
case "getResource":
return URI.create("file:///opt/tomcat/webapps/mall" + methodArgs[0]).toURL();
case "getResourceAsStream":
return new ByteArrayInputStream("db.url=jdbc:mysql://localhost:3306/mall".getBytes(StandardCharsets.UTF_8));
case "getRequestDispatcher":
case "getNamedDispatcher":
return mockDispatcher;
default: return null;
}
}
);
// 1. 解析 Web 应用内虚拟路径对应的磁盘真实路径与子目录资源列表
System.out.println("Real Path: " + context.getRealPath("/WEB-INF/web.xml"));
System.out.println("Resource Paths: " + context.getResourcePaths("/WEB-INF/"));
System.out.println("Resource URL: " + context.getResource("/WEB-INF/web.xml"));
// 2. 以字节输入流形式读取 Web 应用内的配置文件内容
try (InputStream in = context.getResourceAsStream("/WEB-INF/classes/db.properties")) {
String content = new String(in.readAllBytes(), StandardCharsets.UTF_8);
System.out.println("Stream Content: " + content);
}
// 3. 按路径或组件名称获取请求转发器 RequestDispatcher
RequestDispatcher pathDisp = context.getRequestDispatcher("/index.jsp");
RequestDispatcher namedDisp = context.getNamedDispatcher("default");
System.out.println("Dispatched instances valid: " + (pathDisp != null && namedDisp != null));
}
}动态注册
addServlet():Servlet 动态注册重载族。在容器启动阶段以指定的组件名称向当前 Web 应用动态注册 Servlet,返回
ServletRegistration.Dynamic配置句柄以继续绑定 URL 映射、启动顺序或局部参数;若同名 Servlet 已完成完整注册,则返回null。ServletRegistration.Dynamic:(String servletName, String className),按类名动态注册 Servlet。使用组件名称与实现类的完整限定类名字符串向容器注册 Servlet。ServletRegistration.Dynamic:(String servletName, Servlet servlet),按实例动态注册 Servlet。直接将已创建的Servlet对象实例以指定名称注册到容器中。ServletRegistration.Dynamic:(String servletName, Class<? extends Servlet> servletClass),按类型动态注册 Servlet。使用组件名称与Servlet实现类的Class对象向容器注册 Servlet。
ServletRegistration.DynamicaddJspFile():(String servletName, String jspFile),JSP 文件动态注册。在容器启动阶段将指定的 JSP 文件路径(以'/'开头)作为命名 Servlet 组件注册到容器中,返回ServletRegistration.Dynamic配置句柄。<T Servlet extends> TcreateServlet():(Class<T> clazz),托管 Servlet 实例创建。由 Web 容器根据给定的Class类型反射实例化一个Servlet对象,并自动对其执行容器级的依赖注入(如@Inject、@Resource),供后续调用addServlet(String, Servlet)注册使用。ServletRegistrationgetServletRegistration():(String servletName),单个 Servlet 注册信息查询。根据组件名称返回对应的ServletRegistration注册元数据对象;若不存在则返回null。Map<String, ? ServletRegistration extends>
getServletRegistrations():(),全量 Servlet 注册表获取。返回当前 Web 应用中所有已注册 Servlet 的名称与对应ServletRegistration组成的不可变映射表。addFilter():Filter 动态注册重载族。在容器启动阶段以指定的过滤器名称向当前 Web 应用动态注册
Filter,返回FilterRegistration.Dynamic配置句柄以继续绑定拦截路径或目标 Servlet。FilterRegistration.Dynamic:(String filterName, String className),按类名动态注册 Filter。使用过滤器名称与实现类的完整限定类名字符串向容器注册 Filter。FilterRegistration.Dynamic:(String filterName, Filter filter),按实例动态注册 Filter。直接将已创建的Filter对象实例以指定名称注册到容器中。FilterRegistration.Dynamic:(String filterName, Class<? extends Filter> filterClass),按类型动态注册 Filter。使用过滤器名称与Filter实现类的Class对象向容器注册 Filter。
<T Filter extends> TcreateFilter():(Class<T> clazz),托管 Filter 实例创建。由 Web 容器实例化给定的Filter类型并完成容器托管的依赖注入,供后续调用addFilter(String, Filter)注册使用。FilterRegistrationgetFilterRegistration():(String filterName),单个 Filter 注册信息查询。根据过滤器名称返回对应的FilterRegistration注册元数据对象;若不存在则返回null。Map<String, ? FilterRegistration extends>
getFilterRegistrations():(),全量 Filter 注册表获取。返回当前 Web 应用中所有已注册 Filter 的名称与对应FilterRegistration组成的不可变映射表。addListener():Listener 动态注册重载族。在容器启动阶段向当前 Web 应用动态追加注册生命周期或属性变更事件监听器(需实现
ServletContextListener、HttpSessionListener、ServletRequestListener等标准子接口之一)。void:(String className),按类名动态注册 Listener。根据监听器实现类的完整限定类名字符串向容器注册监听器。<T EventListener extends> void:(T t),按实例动态注册 Listener。直接将已创建的监听器对象实例注册到容器中。void:(Class<? extends EventListener> listenerClass),按类型动态注册 Listener。根据监听器实现类的Class对象向容器注册监听器。
<T EventListener extends> TcreateListener():(Class<T> clazz),托管 Listener 实例创建。由 Web 容器实例化给定的EventListener类型并完成依赖注入,供后续调用addListener(T)注册使用。
注意事项:
- 所有动态注册与组件创建方法(
addServlet、addJspFile、createServlet、addFilter、createFilter、addListener、createListener)只能在容器启动阶段(即ServletContainerInitializer.onStartup()或由其注册的ServletContextListener.contextInitialized()中)调用;一旦ServletContext初始化完成,再调用将抛出IllegalStateException。- 若在
ServletContextListener.contextInitialized()内部调用addListener(),则不能再注册ServletContextListener类型的监听器(因为此时contextInitialized事件已经在派发中),否则容器将直接抛出IllegalArgumentException。
import jakarta.servlet.FilterRegistration;
import jakarta.servlet.ServletContext;
import jakarta.servlet.ServletRegistration;
import jakarta.servlet.http.HttpServlet;
import java.lang.reflect.Proxy;
import java.util.EventListener;
import java.util.Map;
public class ServletContextRegistrationDemo {
static class DynamicDemoServlet extends HttpServlet {}
static class CustomAppListener implements EventListener {}
public static void main(String[] args) throws Exception {
ServletRegistration.Dynamic mockServletReg = (ServletRegistration.Dynamic) Proxy.newProxyInstance(
ServletRegistration.Dynamic.class.getClassLoader(),
new Class<?>[]{ServletRegistration.Dynamic.class},
(proxy, method, methodArgs) -> null
);
FilterRegistration.Dynamic mockFilterReg = (FilterRegistration.Dynamic) Proxy.newProxyInstance(
FilterRegistration.Dynamic.class.getClassLoader(),
new Class<?>[]{FilterRegistration.Dynamic.class},
(proxy, method, methodArgs) -> null
);
ServletContext context = (ServletContext) Proxy.newProxyInstance(
ServletContext.class.getClassLoader(),
new Class<?>[]{ServletContext.class},
(proxy, method, methodArgs) -> {
switch (method.getName()) {
case "addServlet":
case "addJspFile":
System.out.println("Registered Servlet: " + methodArgs[0]);
return mockServletReg;
case "addFilter":
System.out.println("Registered Filter: " + methodArgs[0]);
return mockFilterReg;
case "addListener":
System.out.println("Registered Listener: " + methodArgs[0]);
return null;
case "getServletRegistrations":
return Map.of("demoServlet", mockServletReg);
default: return null;
}
}
);
// 1. 在容器启动阶段编程式动态注册 Servlet 与 JSP 组件
ServletRegistration.Dynamic servletReg = context.addServlet("demoServlet", DynamicDemoServlet.class);
servletReg.addMapping("/dynamic/*");
context.addJspFile("homeJsp", "/WEB-INF/views/home.jsp");
// 2. 编程式动态注册 Filter 过滤器与 Listener 监听器
context.addFilter("authFilter", "com.example.filter.AuthFilter");
context.addListener(CustomAppListener.class);
// 3. 查询当前应用已注册的 Servlet 注册表信息
System.out.println("Servlet Registrations: " + context.getServletRegistrations().keySet());
}
}