Skip to content

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 类图如下:

image-20261029154325870

web.xml ​

在 Servlet 3.0 之前,所有的 Servlet 映射必须在 WEB-INF/web.xml 部署描述符中通过 XML 标签声明。即使在现代项目中,当需要集中管理路由、或为第三方 Jar 包中未标注注解的 Servlet 配置映射时,依然会使用该方式。

web.xml 配置由两个核心标签块组成,通过内部的 <servlet-name> 进行关联:

  1. <servlet> 标签块:用于向容器注册一个 Servlet 实例,指定其内部唯一标识名(<servlet-name>)与完整限定类名(<servlet-class>)。

  2. <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> 标签。

java
// 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。

java
// 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):

  1. metadata-complete="false"(默认值):容器在启动时不仅解析 web.xml,还会扫描所有类和 Jar 包中的 @WebServlet、@WebFilter、@WebListener 注解以及 ServletContainerInitializer,并将所有配置合并。

  2. metadata-complete="true":容器认为 web.xml 中的元数据已经是完整且最终的,完全跳过注解扫描阶段。此时代码中标注的所有 @WebServlet 注解都会失效。

优先级与冲突处理 ​

当 metadata-complete="false" 时,若同一个 Servlet 同时在 @WebServlet 和 web.xml 中进行了配置,容器按以下规则合并与覆盖(web.xml 优先级高于注解):

  1. 同名合并与覆盖:如果 web.xml 中的 <servlet-name> 与 @WebServlet(name = "...") 完全一致,容器将两者视为同一个 Servlet 实例。此时 web.xml 中配置的 <url-pattern> 会直接覆盖注解中的 urlPatterns,注解中的路径映射不再先生效;同理,同名的 <init-param> 也会覆盖 @WebInitParam。

  2. 异名重复实例化:如果 web.xml 与 @WebServlet 指向同一个类,但两者的 servlet-name 不同,容器会将它们视为两个独立的 Servlet 实例,分别完成初始化并同时绑定各自的映射路径。

路由匹配规则 ​

当请求到达容器时,容器会先从请求 URI 中去除应用上下文路径(Context Path),得到用于路由匹配的相对路径。Servlet 规范严格定义了四种合法的 url-pattern 语法格式,按匹配优先级从高到低依次为:精确匹配、路径匹配、扩展名匹配、缺省匹配。

容器解析请求 URL 并按优先级路由至目标 Servlet 的 UML 活动图如下:

image-20261029154400593

精确匹配 ​

精确匹配要求客户端请求的相对路径必须与配置的 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

当客户端发起不同请求时,容器的派发结果如下:

  1. 请求 /abc/def:同时符合规则 A(精确匹配)和规则 B(路径匹配)。由于精确匹配优先级最高,最终派发给 ServletA。

  2. 请求 /abc/def.do:同时符合规则 B(路径匹配 /abc/_)和规则 D(扩展名匹配 _.do)。由于路径匹配(第 2 级)优先于扩展名匹配(第 3 级),最终派发给 ServletB。

  3. 请求 /abc/vip/order.do:同时符合规则 B(/abc/_)、规则 C(/abc/vip/_)和规则 D(_.do)。首先路径匹配优先于扩展名匹配,排除规则 D;其次在路径匹配内部遵循“最长前缀优先”原则,/abc/vip/_长于/abc/\*,最终派发给 ServletC。

  4. 请求 /user/login.do:精确匹配与路径匹配均未命中,命中规则 D(扩展名匹配 \*.do),最终派发给 ServletD。

  5. 请求 /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 时,内部装配与委托流程如下:

  1. 解析配置元数据:Web 容器读取 web.xml 中该 <servlet> 标签下的 <init-param>,或扫描类上的 @WebInitParam 注解,提取出所有键值对参数。

  2. 创建配置对象:容器为该 Servlet 专门创建一个实现了 ServletConfig 接口的内部封装对象(例如在 Apache Tomcat 中,容器使用 StandardWrapper 维护 Servlet 元数据,并通过门面类 StandardWrapperFacade 实现 ServletConfig 接口以限制外部非法访问容器内部方法)。

  3. 关联全局上下文:容器将代表整个 Web 应用的 ServletContext 引用注入到该 ServletConfig 对象中。

  4. 传入初始化方法:容器调用 Servlet.init(ServletConfig config) 方法,将组装完毕的 ServletConfig 实例传递给 Servlet。

  5. 基类保存与方法委托:GenericServlet 同时实现了 Servlet 和 ServletConfig 接口,它在 init(ServletConfig) 中将传入的配置对象保存至内部成员变量 this.config,并将自身实现的 getInitParameter 等方法全部委托给 this.config 执行。

Web 容器(以 Tomcat 为例)装配 ServletConfig 并由 GenericServlet 进行委托的 UML 类图如下:

image-20261029154504016

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>(参数值)。

xml
<!-- 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 注解来声明局部参数。

java
// 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) 方法注入局部参数。

java
// 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 的子类中,以下两种获取配置的方式完全等价:

  1. 先获取配置对象再调用:this.getServletConfig().getInitParameter("smtpHost")。

  2. 直接调用实例方法:this.getInitParameter("smtpHost") 或 this.getServletContext()。

init ​

在实际开发中,切勿在构造方法(Constructor)中调用 getInitParameter(),因为执行构造器时容器尚未调用 init(ServletConfig),此时内部 config 引用必为 null。

此外,在重写 init 方法读取配置时,必须注意带参 init(ServletConfig) 与无参 init() 的区别:

  1. 重写带参 init(ServletConfig) 的隐患:如果子类直接重写了 public void init(ServletConfig config),却忘记在方法体第一行调用 super.init(config),那么父类 GenericServlet 中的 this.config = config 赋值逻辑就会被跳过。这会导致后续在 doGet、doPost 中调用 getServletConfig()、getInitParameter() 或 getServletContext() 时直接抛出 NullPointerException。

  2. 重写无参 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 ​

元数据获取 ​

  • String getServletName():(),组件名称获取。返回当前 Servlet 实例在部署描述符(web.xml)或 @WebServlet 注解中注册的唯一标识名称;若属于未显式指定名称的匿名注册,则返回该 Servlet 实现类的完整限定类名。

  • ServletContext getServletContext():(),全局上下文获取。返回当前 Servlet 所属 Web 应用程序的 ServletContext 全局上下文单例对象,用于与 Web 容器交互或访问应用域共享资源。

注意事项:

  1. ServletConfig 实例由 Web 容器在初始化目标 Servlet 前创建并专属绑定,不同 Servlet 实例之间的 ServletConfig 彼此隔离,但它们调用 getServletContext() 返回的均是当前 Web 应用内同一个 ServletContext 引用。
java
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());
  }
}

参数读取 ​

  • String getInitParameter():(String name),局部参数获取。根据指定的参数名称返回当前 Servlet 的局部初始化参数值(包含 <init-param> 或 @WebInitParam 配置项);若指定的参数名称不存在,则返回 null。

  • Enumeration<String>
    getInitParameterNames()
    :(),局部参数名枚举。返回当前 Servlet 所有局部初始化参数名称的 Enumeration 枚举集合;若当前 Servlet 未配置任何初始化参数,则返回一个空的 Enumeration 对象而非 null。

注意事项:

  1. getInitParameter() 的参数名称严格区分大小写,且若传入的参数名 name 为 null,容器实现将直接抛出 NullPointerException。
  2. ServletConfig 仅提供运行期只读的局部参数访问能力,无法读取 <context-param> 全局上下文参数,也不提供任何运行期动态修改或删除局部参数的方法。
java
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 的底层实现结构以及与其他核心组件的引用关系如下:

image-20261029154552000

ServletContext 的生命周期严格绑定于整个 Web 应用,分为三个阶段:

  1. 创建时机:Web 容器启动并加载 Web 应用时,在初始化任何 Filter 和 Servlet 之前(仅次于 ServletContainerInitializer),容器率先创建 ServletContext 实例,并触发 ServletContextListener.contextInitialized 事件。

  2. 存活阶段:在整个 Web 应用运行期间,ServletContext 始终常驻内存,供所有并发请求与组件访问。

  3. 销毁时机:当 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() 获取全局上下文。

java
// 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> 标签内部。

xml
<!-- 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。

java
// 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,在操作应用域属性时需遵守以下并发规范:

  1. 优先存储只读数据:应用域最适合存放启动时加载的全局只读字典、配置缓存或本身线程安全的连接池对象。

  2. 使用并发容器或原子类:若需要在应用域统计全局状态(如全站访问量计数),应直接存入 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 String ServletContext.TEMPDIR:临时目录属性名。常量值为 "jakarta.servlet.context.tempdir"(旧版为 "javax.servlet.context.tempdir"),用于通过 getAttribute() 获取 Web 容器为当前应用分配的专属磁盘临时目录(返回类型为 File)。

  • final String ServletContext.ORDERED_LIBS:依赖排序属性名。常量值为 "jakarta.servlet.context.orderedLibs",用于通过 getAttribute() 获取当前 Web 应用内 WEB-INF/lib 下按加载顺序排列的 Jar 包名称列表(返回类型为 List<String>)。

  • String getContextPath():(),上下文路径获取。返回当前 Web 应用在容器中部署的 URI 路径前缀(以 / 开头但不以 / 结尾);若应用部署在容器的默认根路径(ROOT)下,则返回空字符串 ""。

  • String getServletContextName():(),应用显示名获取。返回当前 Web 应用在 web.xml 的 <display-name> 标签中声明的名称;若未声明则返回 null。

  • String getServerInfo():(),容器信息获取。返回当前运行环境的 Web 容器名称与版本号字符串(格式如 "Apache Tomcat/10.1.30")。

  • String getVirtualServerName():(),虚拟主机名获取。返回当前 Web 应用所属逻辑虚拟主机的配置名称(格式通常包含引擎名与主机名,如 "Catalina/localhost")。

  • int getMajorVersion():(),规范主版本获取。返回当前 Web 容器所支持的 Servlet 规范最高主版本号(例如支持 Servlet 6.0 的容器返回 6)。

  • int getMinorVersion():(),规范次版本获取。返回当前 Web 容器所支持的 Servlet 规范最高次版本号(例如支持 Servlet 6.0 的容器返回 0)。

  • int getEffectiveMajorVersion():(),生效主版本获取。返回当前 Web 应用自身部署描述符(web.xml)所声明采用的 Servlet 规范主版本号。

  • int getEffectiveMinorVersion():(),生效次版本获取。返回当前 Web 应用自身部署描述符(web.xml)所声明采用的 Servlet 规范次版本号。

  • String getMimeType():(String file),媒体类型推断。根据传入的文件名后缀匹配容器内置或 web.xml 配置的 <mime-mapping> 映射表,返回对应的 MIME 内容类型字符串(如 "text/html"、"image/png");若无法识别则返回 null。

  • ClassLoader getClassLoader():(),类加载器获取。返回用于加载当前 Web 应用类路径(WEB-INF/classes 与 WEB-INF/lib)的专属类加载器实例。

  • log():容器日志记录重载族。将指定的应用运行日志或异常堆栈信息写入 Web 容器的统一日志文件中。

    • void:(String msg),纯文本日志记录。将指定的普通文本消息写入当前 Web 容器的日志文件中。
    • void:(String message, Throwable throwable),异常堆栈日志记录。将指定的错误描述消息以及关联的 Throwable 异常完整调用栈一并写入容器日志文件中。

注意事项:

  1. 每个 Web 应用在启动时,Web 容器都必须创建一个可写的专属临时目录,并以 ServletContext.TEMPDIR 为键存入应用域属性中,供文件上传等场景缓存临时文件。
  2. 早期规范中的 log(Exception exception, String msg)、获取 Servlet 实例的 getServlet(String)、getServlets()、getServletNames() 方法均已在早期版本中废弃,并在 Jakarta Servlet 6.0 中被彻底移除。
java
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"));
  }
}

参数配置 ​

  • String getInitParameter():(String name),全局参数读取。根据指定的参数名称读取当前 Web 应用的全局上下文初始化参数(<context-param> 或编程式注入项);若参数不存在则返回 null。

  • Enumeration<String> getInitParameterNames():(),全局参数名枚举。返回当前 Web 应用所有全局初始化参数名称的 Enumeration 枚举集合;若无任何参数则返回空枚举。

  • boolean setInitParameter():(String name, String value),全局参数动态写入。在容器启动阶段向当前应用动态写入指定的全局初始化参数;若设置成功返回 true,若同名全局参数已存在则放弃覆盖并返回 false。

  • String getRequestCharacterEncoding():(),请求默认编码获取。返回当前 Web 应用全局配置的默认请求字符编码名称(自 Servlet 4.0 引入);若未配置则返回 null。

  • void setRequestCharacterEncoding():(String encoding),请求默认编码设置。在容器启动阶段统一设置当前 Web 应用所有请求的默认字符编码集(等价于 <request-character-encoding>)。

  • String getResponseCharacterEncoding():(),响应默认编码获取。返回当前 Web 应用全局配置的默认响应字符编码名称(自 Servlet 4.0 引入);若未配置则返回 null。

  • void setResponseCharacterEncoding():(String encoding),响应默认编码设置。在容器启动阶段统一设置当前 Web 应用所有响应的默认字符编码集(等价于 <response-character-encoding>)。

  • int getSessionTimeout():(),会话超时获取。返回当前 Web 应用全局配置的默认 HttpSession 空闲超时时间(单位:分钟,自 Servlet 4.0 引入)。

  • void setSessionTimeout():(int sessionTimeout),会话超时设置。在容器启动阶段设置全局默认的 HttpSession 空闲超时时间(单位:分钟);若传入 0 或负数表示会话永不超时。

  • SessionCookieConfig
    getSessionCookieConfig()
    :(),会话 Cookie 配置获取。返回用于配置会话追踪 Cookie(如 JSESSIONID 的名称、HttpOnly、Secure、MaxAge 属性)的 SessionCookieConfig 对象。

  • void setSessionTrackingModes():(Set<SessionTrackingMode> sessionTrackingModes),会话追踪模式设置。在容器启动阶段指定当前 Web 应用启用的会话追踪机制集合(可选值包括 COOKIE、URL、SSL)。

  • Set<SessionTrackingMode>
    getDefaultSessionTrackingModes()
    :(),默认追踪模式获取。返回当前 Web 容器默认支持的会话追踪模式不可变集合。

  • Set<SessionTrackingMode>
    getEffectiveSessionTrackingModes()
    :(),生效追踪模式获取。返回当前 Web 应用实际正在生效的会话追踪模式不可变集合。

  • JspConfigDescriptor getJspConfigDescriptor():(),JSP 配置描述符获取。返回汇总了 web.xml 与 Web 分片中 <jsp-config> 标签配置的描述符对象;若未配置则返回 null。

  • void declareRoles():(String... roleNames),安全角色声明。在容器启动阶段编程式声明当前 Web 应用使用到的安全角色名称列表(供 HttpServletRequest.isUserInRole 校验使用)。

注意事项:

  1. 所有带修改语义的配置方法(包括 setInitParameter()、setRequestCharacterEncoding()、setResponseCharacterEncoding()、setSessionTimeout()、setSessionTrackingModes()、declareRoles() 以及对 getSessionCookieConfig() 返回对象的写操作)只能在 ServletContextListener.contextInitialized() 或 ServletContainerInitializer.onStartup() 阶段调用;一旦应用完成初始化开始接收请求,再调用这些方法将直接抛出 IllegalStateException。
java
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());
  }
}

属性管理 ​

  • Object getAttribute():(String name),应用域属性读取。根据指定的属性名称从全局应用域中获取共享的 Java 对象引用;若属性不存在则返回 null。

  • Enumeration<String> getAttributeNames():(),应用域属性名枚举。返回当前应用域中已绑定的所有属性名称的 Enumeration 枚举集合。

  • void setAttribute():(String name, Object object),应用域属性写入。将给定的对象绑定到全局应用域的指定名称下;若同名属性已存在则覆盖旧值并触发 ServletContextAttributeListener.attributeReplaced 事件,若传入的 object 为 null 则等效于调用 removeAttribute(name)。

  • void removeAttribute():(String name),应用域属性移除。从全局应用域中彻底移除指定名称的属性,并触发 ServletContextAttributeListener.attributeRemoved 事件。

注意事项:

  1. 应用域属性在整个 Web 应用运行期内被所有并发请求线程共享,单次 getAttribute() 与 setAttribute() 调用虽由容器底层并发哈希表保障结构安全,但“先读后改再写”的复合操作不具备原子性,存储可变状态时必须自行同步或使用 JUC 并发安全类。
  2. 属性名称建议避免使用 java.、javax.、jakarta.、sun. 或 com.sun. 前缀,这些命名空间被规范保留供容器内部系統属性使用。
java
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"));
  }
}

资源调度 ​

  • String getRealPath():(String path),物理路径转换。将当前 Web 应用根目录下的虚拟相对路径(如 "/WEB-INF/web.xml")转换为宿主操作系统磁盘上的绝对物理路径;若应用以未解压的 .war 归档包形式直接运行或资源不存在无法映射,则返回 null。

  • URL getResource():(String path),资源 URL 获取。返回指向当前 Web 应用内指定虚拟路径(必须以 '/' 开头,包含 WEB-INF/lib/*.jar 内的 /META-INF/resources 静态资源)的 URL 对象;若资源不存在则返回 null。

  • InputStream getResourceAsStream():(String path),资源字节流获取。直接打开并返回读取当前 Web 应用内指定虚拟路径资源的 InputStream 字节输入流;即使应用以未解压的 .war 包形式运行也能正常读取,若资源不存在则返回 null。

  • Set<String> getResourcePaths():(String path),目录资源路径枚举。返回当前 Web 应用内指定目录路径(必须以 '/' 开头)下所有直属文件及子目录虚拟路径的不可变集合(子目录路径以 '/' 结尾);若目录为空或不存在则返回 null。

  • RequestDispatcher getRequestDispatcher():(String path),路径请求调度器获取。根据以 '/' 开头的上下文相对路径封装并返回 RequestDispatcher 实例,用于将请求服务端转发(forward)或包含(include)至目标资源;若路径不以 '/' 开头或无法解析则返回 null。

  • RequestDispatcher getNamedDispatcher():(String name),命名请求调度器获取。根据 Servlet 在容器中的注册名称(servlet-name)封装并返回 RequestDispatcher 实例,常用于向未绑定公开 URL 映射的内部 Servlet 或容器内置 default、jsp 组件转发请求;若找不到对应名称则返回 null。

  • ServletContext getContext():(String uripath),跨应用上下文获取。根据以 '/' 开头的外部 URI 路径返回同一容器中对应其他 Web 应用的 ServletContext 对象,用于跨应用请求调度;出于安全隔离考虑,主流容器默认禁用跨上下文访问并返回 null(需在容器配置中显式开启 crossContext="true")。

注意事项:

  1. ServletContext.getRequestDispatcher(String path) 的参数 path 必须以正斜杠 '/' 开头(代表当前 Web 应用的根目录),不支持不带 '/' 的相对路径;而 ServletRequest.getRequestDispatcher(String path) 则同时支持以 '/' 开头的绝对路径和相对于当前请求目录的相对路径。
  2. getResource() 与 getResourceAsStream() 传入的 path 同样必须以 '/' 开头(否则 getResource() 将抛出 MalformedURLException),其根目录对应打包后的 Web 根目录(即 WEB-INF 所在的父目录),读取类路径资源时需传入 "/WEB-INF/classes/..."。
java
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.Dynamic addJspFile():(String servletName, String jspFile),JSP 文件动态注册。在容器启动阶段将指定的 JSP 文件路径(以 '/' 开头)作为命名 Servlet 组件注册到容器中,返回 ServletRegistration.Dynamic 配置句柄。

  • <T Servlet extends> T createServlet():(Class<T> clazz),托管 Servlet 实例创建。由 Web 容器根据给定的 Class 类型反射实例化一个 Servlet 对象,并自动对其执行容器级的依赖注入(如 @Inject、@Resource),供后续调用 addServlet(String, Servlet) 注册使用。

  • ServletRegistration getServletRegistration():(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> T createFilter():(Class<T> clazz),托管 Filter 实例创建。由 Web 容器实例化给定的 Filter 类型并完成容器托管的依赖注入,供后续调用 addFilter(String, Filter) 注册使用。

  • FilterRegistration getFilterRegistration():(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> T createListener():(Class<T> clazz),托管 Listener 实例创建。由 Web 容器实例化给定的 EventListener 类型并完成依赖注入,供后续调用 addListener(T) 注册使用。

注意事项:

  1. 所有动态注册与组件创建方法(addServlet、addJspFile、createServlet、addFilter、createFilter、addListener、createListener)只能在容器启动阶段(即 ServletContainerInitializer.onStartup() 或由其注册的 ServletContextListener.contextInitialized() 中)调用;一旦 ServletContext 初始化完成,再调用将抛出 IllegalStateException。
  2. 若在 ServletContextListener.contextInitialized() 内部调用 addListener(),则不能再注册 ServletContextListener 类型的监听器(因为此时 contextInitialized 事件已经在派发中),否则容器将直接抛出 IllegalArgumentException。
java
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());
  }
}