Skip to content

Listener ​

[TOC]

概述 ​

Listener(监听器) 是 JavaWeb Servlet 规范定义的三大核心组件之一,与 Servlet 和 Filter 并列运行在 Web 容器中。Servlet 负责处理请求并生成响应,Filter 负责在请求与响应流转前后进行拦截处理,而 Listener 则专注于监听 Web 容器内部特定域对象的状态变化,并在事件发生时自动触发预设的回调逻辑。

通过 Listener,开发者无需在业务 Servlet 中硬编码系统级钩子逻辑,即可实现全局资源初始化与释放、在线人数统计、会话属性审计、请求耗时监控以及缓存同步等横切需求,从而将容器状态感知与业务请求处理彻底解耦。

观察者模式 ​

Servlet Listener 在底层采用经典的观察者模式(事件驱动模型),由 Web 容器充当事件调度中心,统一管理事件触发与回调分发。整个模型围绕四个核心角色协同运作:

事件源 ​

事件源是被监听的目标对象。在 Servlet 规范中,事件源固定为三大域对象:ServletContext、HttpSession 和 ServletRequest。它们分别对应应用级、会话级和请求级的数据作用域,其创建、销毁以及内部属性的增删改操作都会对外产生事件。

事件对象 ​

事件对象继承自 java.util.EventObject,用于封装事件发生时的上下文快照。容器在触发事件时会构造对应的事件对象实例,内部持有事件源引用,部分属性类事件对象还会额外携带发生变更的属性名与属性值。

监听器 ​

监听器实现自 java.util.EventListener 标记接口的子接口,是开发者编写业务逻辑的入口。Web 容器通过接口类型识别监听器关注的事件种类,并在对应事件发生时调用接口约定的回调方法。

事件分发器 ​

事件分发器由具体的 Servlet 容器(如 Tomcat 中的 StandardContext、StandardSession、Request 等内部组件)承担,负责维护监听器注册表并在事件源状态改变时同步派发事件。

标准事件监听的完整运行流程如下:

  1. Web 容器启动时,解析注解、配置类或部署描述符中声明的监听器,反射实例化后按接口类型归类存入容器内部的监听器列表。

  2. 运行期间,当三大域对象发生创建、销毁、属性变更或会话标识变更等操作时,容器构造对应的 EventObject 子类实例。

  3. 容器遍历匹配该事件类型的监听器列表,依次同步调用对应的回调方法,并将事件对象作为参数传入。

  4. 监听器执行回调逻辑完毕后控制权交还容器,容器继续执行后续生命周期流程或请求处理链路。

image-20261120221555372

监听器分类 ​

按照监听的事件性质与注册方式的不同,Servlet 规范(Servlet 3.1 及以上版本)定义的监听器可以划分为三大类别。所有监听器接口均继承自 JDK 标准标记接口 java.util.EventListener。

域生命周期监听器 ​

域生命周期监听器用于监听三大域对象的诞生与消亡过程,以及会话标识的变更。该类监听器必须在容器中显式注册才能生效,包含以下核心接口:

  • ServletContextListener:监听 Web 应用启动与关闭,常用于加载全局配置文件、初始化数据库连接池、启动或停止后台定时任务。
  • HttpSessionListener:监听客户端会话的创建与失效,常用于统计当前活跃会话数或清理会话绑定的外部资源。
  • HttpSessionIdListener:Servlet 3.1 新增,监听 HttpSession 的唯一标识(JSESSIONID)变更事件,常用于防范会话固定攻击后同步更新服务端映射表。
  • ServletRequestListener:监听每次 HTTP 请求的到达与结束,常用于记录请求全链路耗时、初始化线程上下文(如 ThreadLocal)并在请求结束后执行清理。

域属性变更监听器 ​

域属性变更监听器用于监控三大域对象中键值对属性的新增、移除与覆盖替换操作,同样需要在容器中显式注册:

  • ServletContextAttributeListener:监听应用域全局属性变更,常用于审计全局共享配置或缓存字典的动态刷新。
  • HttpSessionAttributeListener:监听会话域属性变更,常用于感知用户登录凭证写入与注销移除,辅助实现单点登录踢人或在线用户清单维护。
  • ServletRequestAttributeListener:监听请求域属性变更,常用于在请求转发链条中追踪数据传递状态或辅助调试。

感知型监听器 ​

感知型监听器与上述两类全局监听器截然不同,它由存放在 HttpSession 中的普通 JavaBean 对象自身实现,用于让对象感知自己在会话中的状态流转:

  • HttpSessionBindingListener:当实现该接口的对象被放入 HttpSession 或从中移除时,自动触发对象自身的绑定与解绑回调。
  • HttpSessionActivationListener:当服务器发生会话钝化(序列化至磁盘持久化)或活化(反序列化恢复至内存)时,自动通知会话内的对象完成瞬态资源释放或重建。

感知型监听器无需通过 @WebListener 或 web.xml 注册。每当业务代码操作 HttpSession 属性或容器执行钝化活化时,容器会自动检测目标对象是否实现了对应接口并直接触发回调。

监听类别作用对象核心监听器接口对应事件对象是否需要注册
域生命周期监听ServletContextServletContextListenerServletContextEvent是
域生命周期监听HttpSessionHttpSessionListenerHttpSessionEvent是
域生命周期监听HttpSessionHttpSessionIdListenerHttpSessionEvent是
域生命周期监听ServletRequestServletRequestListenerServletRequestEvent是
域属性变更监听ServletContextServletContextAttributeListenerServletContextAttributeEvent是
域属性变更监听HttpSessionHttpSessionAttributeListenerHttpSessionBindingEvent是
域属性变更监听ServletRequestServletRequestAttributeListenerServletRequestAttributeEvent是
感知型监听HttpSession 中的对象HttpSessionBindingListenerHttpSessionBindingEvent否
感知型监听HttpSession 中的对象HttpSessionActivationListenerHttpSessionEvent否

包名版本说明:Tomcat 9 及以下版本(对应 Servlet 4.0 及更早规范)中,监听器接口位于 javax.servlet 与 javax.servlet.http 包下;Tomcat 10 及以上版本(对应 Jakarta Servlet 5.0/6.0)已整体迁移至 jakarta.servlet 与 jakarta.servlet.http 包下,二者类结构与语义完全一致。

image-20261120221617742

示例: 监听 Web 应用启停 ​

以下示例演示最基础的监听器写法:通过实现 ServletContextListener 并标注 @WebListener,在 Web 应用启动时记录应用启动时间戳至全局上下文,在应用关闭前自动清理该属性。

java
package com.example.listener;

import javax.servlet.ServletContext;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;
import javax.servlet.annotation.WebListener;

// 1. 使用 @WebListener 声明监听器,并实现 ServletContextListener 接口
@WebListener
public class AppLifecycleListener implements ServletContextListener {

  // 2. Web 应用启动完成时由容器自动回调,适合初始化全局资源
  @Override
  public void contextInitialized(ServletContextEvent sce) {
    ServletContext context = sce.getServletContext();
    String contextPath = context.getContextPath();

    context.setAttribute("appStartTime", System.currentTimeMillis());
    System.out.println("Web 应用已启动,上下文路径: " + contextPath);
  }

  // 3. Web 应用正常关闭或重新部署前由容器自动回调,用于释放全局资源
  @Override
  public void contextDestroyed(ServletContextEvent sce) {
    ServletContext context = sce.getServletContext();

    context.removeAttribute("appStartTime");
    System.out.println("Web 应用已销毁,全局资源已清理");
  }
}

将该类部署至 Servlet 3.0 及以上容器后,无需修改 web.xml,容器启动时会自动扫描 @WebListener 注解并注册实例。需要注意的是,回调方法运行在容器主启动线程中,若回调内部抛出未捕获异常,可能导致 Web 应用部署失败;同时应避免在监听器中执行长时间阻塞操作,以免拖慢容器启动或请求响应速度。

注册配置 ​

Servlet Listener 并非所有类型都需要向 Web 容器显式注册。依据事件触发来源的不同,监听器在注册要求上存在明确边界:

  • 必须注册的监听器:域生命周期监听器(ServletContextListener、HttpSessionListener、HttpSessionIdListener、ServletRequestListener)与域属性变更监听器(ServletContextAttributeListener、HttpSessionAttributeListener、ServletRequestAttributeListener)属于容器级全局组件,必须通过配置文件、注解或编程 API 注册到容器中才能接收事件派发。
  • 无需注册的监听器:感知型监听器(HttpSessionBindingListener、HttpSessionActivationListener)由存放在 HttpSession 中的普通对象自身实现。容器在执行会话属性存取或钝化活化时会自动检测对象类型并直接触发回调,因此无需也不能将其作为全局监听器注册。

Servlet 规范为全局监听器提供了三种标准注册方式,分别适配传统 XML 部署、零配置注解开发与框架级动态装配场景。

web.xml ​

在部署描述符 WEB-INF/web.xml 中,可以通过 <listener> 标签静态声明监听器。容器在启动解析 web.xml 时,会读取 <listener-class> 指定的全限定类名,通过反射完成实例化并按接口类型归类注册。

使用 web.xml 注册具备以下特点:

  • 顺序可控:容器严格按照 <listener> 标签在 web.xml 中的出现顺序完成初始化与事件分发,适用于多个监听器之间存在初始化依赖的场景。
  • 参数解耦:监听器本身无法像 Servlet 或 Filter 那样配置组件级 <init-param>,但在 web.xml 中可以配合 <context-param> 定义应用级全局参数,再由监听器在回调中通过 ServletContext 读取。
  • 外部可维护:无需重新编译 Java 源码,仅修改部署描述符即可启用、替换或调整监听器的加载顺序。

示例: web.xml 注册监听器 ​

以下配置声明了一个全局配置文件路径参数,并按先后顺序注册了数据源初始化监听器与缓存预热监听器:

xml
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         version="4.0">
  <!-- 1. 配置应用级全局初始化参数,供监听器启动时读取 -->
  <context-param>
    <param-name>appConfigLocation</param-name>
    <param-value>/WEB-INF/config/app.properties</param-value>
  </context-param>

  <!-- 2. 按声明顺序注册全局监听器,先初始化底层数据源 -->
  <listener>
    <listener-class>com.example.listener.DataSourceInitListener</listener-class>
  </listener>

  <!-- 3. 依赖数据源的监听器声明在后,销毁时则按相反顺序先释放 -->
  <listener>
    <listener-class>com.example.listener.CacheWarmupListener</listener-class>
  </listener>
</web-app>

@WebListener ​

从 Servlet 3.0 开始,规范引入了 @WebListener 注解用于实现声明式注册。只需将该注解标注在实现了一个或多个全局监听器接口的类上,容器启动时便会自动扫描类路径并完成注册,彻底省去 web.xml 中的重复配置。

使用 @WebListener 需注意以下核心约束:

  • 扫描前提:项目必须运行在 Servlet 3.0 及以上版本的容器中;若存在 web.xml,其根节点 version 需为 3.0 及以上,且 metadata-complete 属性不能设置为 true(一旦设为 true,容器会认为配置已完整并跳过全部注解扫描)。
  • 无需路径映射:与 @WebServlet 和 @WebFilter 不同,监听器响应的是容器内部事件而非特定 URL 请求,因此 @WebListener 不包含 urlPatterns 等路径属性,仅提供一个可选的 value 属性用于填写描述信息。
  • 多接口单实例复用:同一个类可以同时实现多个监听器接口并仅标注一次 @WebListener。容器只会为该类创建一个实例,并将其同时挂载到对应的多个事件监听器列表中,便于在应用生命周期与会话事件之间直接共享状态。
  • 顺序不确定:规范未定义多个 @WebListener 注解类的扫描与执行先后顺序,不同容器可能因类路径文件读取顺序不同而产生差异。

示例: @WebListener 注册多接口监听器 ​

以下示例演示单个类同时实现 ServletContextListener 与 HttpSessionListener,并通过 @WebListener 完成统一注册:

java
package com.example.listener;

import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;
import javax.servlet.annotation.WebListener;
import javax.servlet.http.HttpSessionEvent;
import javax.servlet.http.HttpSessionListener;

// 1. 单个类实现多个监听器接口,标注一次 @WebListener 即可由容器复用同一实例
@WebListener("全局启动与会话审计监听器")
public class AuditCompositeListener implements ServletContextListener, HttpSessionListener {

  // 2. 应用启动时初始化审计上下文
  @Override
  public void contextInitialized(ServletContextEvent sce) {
    String appName = sce.getServletContext().getServletContextName();
    System.out.println("审计模块已就绪,应用名称: " + appName);
  }

  // 3. 新会话建立时记录会话标识
  @Override
  public void sessionCreated(HttpSessionEvent se) {
    String sessionId = se.getSession().getId();
    System.out.println("创建新会话: " + sessionId);
  }

  // 4. 会话过期或主动注销时输出销毁记录
  @Override
  public void sessionDestroyed(HttpSessionEvent se) {
    String sessionId = se.getSession().getId();
    System.out.println("销毁会话: " + sessionId);
  }
}

编程式动态注册 ​

Servlet 3.0 同步扩展了 ServletContext 的编程式注册能力,允许开发者在 Web 应用启动初始化阶段通过 addListener 方法动态添加监听器。该方法支持传入监听器全限定类名、Class 对象或已构造好的监听器实例三种形式,其中直接传入实例的重载方式允许在构造监听器时注入自定义依赖,摆脱了必须依赖无参构造方法的限制。

编程式注册在框架集成(如 Spring MVC 的 WebApplicationInitializer)中极为常见,但 Servlet 规范对其调用时机与目标类型施加了严格限制:

  1. 调用时机限制:动态注册只能在 ServletContainerInitializer.onStartup 或 ServletContextListener.contextInitialized 执行期间完成。一旦 Web 应用初始化结束并开始对外提供服务,再次调用 addListener 会直接抛出 IllegalStateException。

  2. 监听器类型限制:目标类必须是合法的全局监听器接口实现类;如果传入 HttpSessionBindingListener、HttpSessionActivationListener 或未实现标准监听器接口的类型,容器会抛出 IllegalArgumentException。

  3. ServletContextListener 的特殊限制:只有在 ServletContainerInitializer.onStartup 阶段,才允许通过 addListener 动态注册 ServletContextListener。如果在 ServletContextListener.contextInitialized 回调中尝试继续注册另一个 ServletContextListener,容器会抛出 IllegalArgumentException。

  4. 调用来源限制:如果某个 ServletContextListener 既未声明在 web.xml 或 web-fragment.xml 中,也未标注 @WebListener(例如由 ServletContainerInitializer 动态添加或在 TLD 文件中声明的监听器),则在其 contextInitialized 方法内调用 addListener 会抛出 UnsupportedOperationException。

  5. 只增不减:Servlet 规范未提供 removeListener 之类的运行时注销接口,监听器一旦成功注册便会伴随整个 Web 应用的生命周期直至应用卸载。

示例: 动态注册监听器 ​

以下示例在引导监听器的启动回调中读取配置开关,按条件以实例注入和类对象两种方式动态注册其他监听器:

java
package com.example.listener;

import javax.servlet.ServletContext;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;
import javax.servlet.annotation.WebListener;

// 1. 声明引导监听器,在应用初始化阶段按条件动态挂载其他监听器
@WebListener
public class DynamicListenerRegistrar implements ServletContextListener {

  // 2. 读取运行环境开关,按需通过 ServletContext 动态注册监听器
  @Override
  public void contextInitialized(ServletContextEvent sce) {
    ServletContext context = sce.getServletContext();
    String traceEnabled = context.getInitParameter("requestTraceEnabled");

    // 3. 通过实例重载注册,支持向监听器构造方法直接注入配置参数
    if ("true".equalsIgnoreCase(traceEnabled)) {
      context.addListener(new RequestTraceListener("[TRACE]"));
    }

    // 4. 通过 Class 对象注册,由容器反射调用其无参构造方法创建实例
    context.addListener(OnlineSessionCounter.class);
  }
}

注册方式对比 ​

三种注册方式可以共存于同一个 Web 应用中,容器在启动阶段会按固定流程将它们合并汇总至上下文内部的监听器注册表中。选型时可根据排序要求、配置复杂度与动态装配需求进行权衡:

对比维度web.xml@WebListener编程式动态注册
支持版本Servlet 2.3+Servlet 3.0+Servlet 3.0+
排序确定性严格按声明顺序执行顺序未定义严格按代码调用顺序执行
条件化注册不支持不支持支持按环境变量或配置动态决定
构造方法依赖注入不支持(须无参构造)不支持(须无参构造)传入实例时支持带参构造
典型适用场景需精确控制启停顺序或零源码改动调整独立且无顺序依赖的业务监听框架自动装配或条件开启的监控组件

image-20261120221652882

执行顺序 ​

当 Web 应用中同时包含 Servlet、Filter 和多个 Listener 时,容器对各组件的初始化与销毁时机有严格的先后契约。

三大组件启停顺序 ​

在 Web 容器的完整生命周期中,Listener 处于最外层,优先级高于 Filter 和 Servlet:

  1. 启动初始化阶段:ServletContextListener.contextInitialized 最先执行,其次执行所有 Filter.init,最后初始化配置了 load-on-startup 的 Servlet.init。规范保证在任何 Filter 或 Servlet 开始初始化之前,所有 ServletContextListener 的启动回调均已完成,因此 Filter 和 Servlet 可以安全地从 ServletContext 中获取监听器提前准备好的连接池、配置或 IoC 容器。

  2. 关闭销毁阶段:顺序与启动阶段严格相反。容器先依次调用所有 Servlet.destroy,再调用所有 Filter.destroy,待全部 Servlet 与 Filter 完成销毁后,最后才触发 ServletContextListener.contextDestroyed。这一设计确保业务请求和过滤器在收尾期间仍能正常使用全局底层资源,避免资源被提前释放。

多监听器执行顺序 ​

当应用中注册了多个同类型监听器时,容器遵循以下优先级与对称回调规则:

  • 配置源优先级:部署描述符的优先级高于注解。web.xml 中声明的监听器先于 web-fragment.xml 及 @WebListener 注解扫描到的监听器注册;多个 JAR 包中的 web-fragment.xml 可通过 web.xml 中的 <absolute-ordering> 或片段内的 <ordering> 控制先后顺序。
  • 创建正序、销毁逆序:对于成对出现的生命周期事件(如 ServletContextListener 的 contextInitialized 与 contextDestroyed,以及 ServletRequestListener 的 requestInitialized 与 requestDestroyed),假设按顺序注册了监听器 A 与监听器 B,则初始化阶段按 A -> B 顺序回调,而销毁阶段按 B -> A 逆序回调,形成类似栈结构(LIFO)的对称包裹关系,保证后启动的依赖组件先于底层基础组件释放。
  • 避免重复混配:不要同时通过编程式 addListener 再次注册已被 web.xml 或 @WebListener 声明的监听器实例,否则同一事件将触发多次重复回调。若需要明确覆盖注解的默认顺序,应移除 @WebListener 改由 web.xml 统一管理。

image-20261120221718159

实例化与线程安全 ​

监听器在容器中的实例化方式和并发调用特征与 Servlet 类似,开发时需注意以下运行细节:

  • 无参构造要求:通过 web.xml、@WebListener 或 addListener(Class) / addListener(String) 注册的监听器类,必须提供 public 访问权限的无参构造方法,否则容器反射实例化阶段会抛出异常并导致 Web 应用启动失败。
  • 上下文内单实例:在单个 Web 应用中,容器只会为每个已注册的监听器项创建一个实例,该实例自容器启动后常驻内存直至应用停止。
  • 并发回调与线程安全:虽然 ServletContextListener 仅在应用启停时由容器主线程单次触发,但 HttpSession 与 ServletRequest 相关的监听器会被多个 HTTP 工作线程高并发同步调用。如果监听器内部需要维护跨请求或跨会话的共享状态(例如统计在线人数或活跃请求数),严禁使用普通非线程安全的成员变量(如 int 计数器或普通 HashMap),而应采用 AtomicInteger、LongAdder 或 ConcurrentHashMap 等并发安全组件。

API: WebListener【待补充】 ​

域生命周期监听 ​

域生命周期监听用于捕获 Web 容器中三大作用域对象(ServletContext、HttpSession、ServletRequest)的创建、销毁以及会话标识变更事件。这类监听器均属于容器级全局组件,必须通过 web.xml、@WebListener 或编程式 addListener 注册到容器后才会生效。

从时间跨度上看,三大域对象的生命周期呈严格嵌套关系:整个 Web 应用运行期间仅存在一个 ServletContext;在其存活期内,容器会为不同客户端并发创建并维护成百上千个 HttpSession;而每个客户端在一次会话中又会发起多次独立的 ServletRequest。

image-20261120221743493

ServletContextListener ​

ServletContextListener 负责监听 Web 应用本身的启动与关闭。由于每个 Web 应用在单个 JVM 中只对应一个 ServletContext 实例,该监听器在应用完整生命周期内只会各触发一次初始化回调与销毁回调。

触发时机 ​

  1. 初始化回调:容器部署并启动 Web 应用、创建好 ServletContext 对象后,在任何 Filter 和 Servlet 初始化之前同步调用 contextInitialized。

  2. 销毁回调:容器正常关闭、卸载或重新部署 Web 应用时,等待所有 Servlet 和 Filter 完成销毁后,在 ServletContext 彻底释放前同步调用 contextDestroyed。

典型场景与注意事项 ​

ServletContextListener 是全局基础设施挂载与回收的标准入口,常见用途包括初始化与关闭数据库连接池、启动或停止全局定时调度任务、加载只读字典缓存至应用域,以及引导 Spring 等上层框架的根容器启动(如 Spring 的 ContextLoaderListener)。

在实际使用中需注意以下边界:

  • 异常停机不触发销毁:contextDestroyed 仅在容器正常关闭或热重部署时触发;若 JVM 遭遇强制终止(如 kill -9)或服务器断电,销毁回调不会执行,因此关键业务状态不能仅依赖销毁回调落盘。
  • 防止类加载器内存泄漏:如果在启动阶段创建了自定义线程池、定时任务或注册了 JDBC 驱动,必须在 contextDestroyed 中显式停止线程并释放资源,否则残留的活跃线程会持有 Web 应用类加载器引用,导致 Tomcat 热部署时触发元空间(Metaspace)内存溢出。
  • 严禁阻塞与未捕获异常:启动回调运行在容器部署主线程上,耗时过长会直接拖慢应用启动速度;若回调内部抛出未捕获的运行时异常,容器会判定应用初始化失败并中止部署。

示例: 全局线程池初始化与释放 ​

以下示例通过 ServletContextListener 在 Web 应用启动时创建固定大小的线程池并放入应用域,在应用停止前执行优雅停机与兜底强制中断:

java
package com.example.listener;

import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
import javax.servlet.ServletContext;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;
import javax.servlet.annotation.WebListener;

// 1. 监听应用启停,统一托管全局后台线程池
@WebListener
public class GlobalExecutorListener implements ServletContextListener {

  // 2. 应用启动时创建固定大小的线程池并存入应用域供业务复用
  @Override
  public void contextInitialized(ServletContextEvent sce) {
    ServletContext context = sce.getServletContext();
    ExecutorService executor = Executors.newFixedThreadPool(4);

    context.setAttribute("globalExecutor", executor);
  }

  // 3. 应用关闭时优雅停机,防止遗留后台线程导致类加载器内存泄漏
  @Override
  public void contextDestroyed(ServletContextEvent sce) {
    ServletContext context = sce.getServletContext();
    ExecutorService executor = (ExecutorService) context.getAttribute("globalExecutor");

    if (executor == null) {
      return;
    }

    // 4. 拒绝新任务并等待存量任务在超时前执行完毕
    executor.shutdown();
    try {
      if (!executor.awaitTermination(5, TimeUnit.SECONDS)) {
        executor.shutdownNow();
      }
    } catch (InterruptedException e) {
      executor.shutdownNow();
      Thread.currentThread().interrupt();
    }
  }
}

HttpSessionListener ​

HttpSessionListener 负责监听客户端会话的创建与失效过程。通过该接口,应用可以在会话维度统一完成资源计数、会话审计以及关联临时文件的清理。

触发时机 ​

  1. 会话创建:当服务端首次为客户端分配 HttpSession 时触发 sessionCreated。并非所有 HTTP 请求都会触发该回调——只有当 Servlet 调用 request.getSession() / request.getSession(true) 且当前请求未携带有效会话标识,或客户端访问了未声明 session="false" 的 JSP 页面时,容器才会真正创建会话。

  2. 会话销毁:以下三种情况会触发 sessionDestroyed:

    • 业务代码主动调用 session.invalidate() 注销会话。
    • 会话空闲时间超过 maxInactiveInterval(Tomcat 默认为 30 分钟),由容器后台扫描线程检测到过期后执行清理。
    • Web 应用关闭或卸载,且容器未开启会话持久化钝化策略。

典型场景与注意事项 ​

在基于 HttpSessionListener 实现统计或清理逻辑时,需要明确容器的底层行为边界:

  • 销毁回调先于属性清空:Servlet 规范规定容器在使会话真正失效前调用 sessionDestroyed,因此在销毁回调内部依然可以通过事件对象获取 HttpSession 并读取其中存储的属性(如当前登录用户名),用于记录登出日志或清理外部资源。
  • 超时销毁存在扫描延迟:客户端关闭浏览器并不会向服务端发送通知,服务端只能等待会话超时;同时 Tomcat 依赖后台周期线程(ContainerBackgroundProcessor,默认扫描间隔约 10 秒)批量清理过期会话,因此 sessionDestroyed 并非在超时届满的精确毫秒瞬间触发。
  • 活跃会话数不等同于在线登录人数:匿名访客首次访问带会话的页面也会触发 sessionCreated。若需精确统计已认证在线用户数,通常需要结合 HttpSessionAttributeListener 监控登录属性,而非单纯依赖会话创建计数。
  • 高并发线程安全:会话创建运行在 HTTP 工作线程中,超时销毁运行在容器后台清理线程中,二者可能并发触发。监听器内部状态必须使用 AtomicInteger、LongAdder 或 ConcurrentHashMap 等并发安全结构。

示例: 在线会话数统计 ​

以下示例使用 AtomicInteger 记录容器内实时活跃的会话总数,并在每次会话创建或销毁时同步刷新至 ServletContext 供页面或监控接口读取:

java
package com.example.listener;

import java.util.concurrent.atomic.AtomicInteger;
import javax.servlet.ServletContext;
import javax.servlet.annotation.WebListener;
import javax.servlet.http.HttpSessionEvent;
import javax.servlet.http.HttpSessionListener;

// 1. 使用原子类统计当前活跃会话数,保证高并发场景下的计数准确
@WebListener
public class OnlineSessionCounter implements HttpSessionListener {

  private final AtomicInteger activeSessions = new AtomicInteger(0);

  // 2. 新会话创建时原子递增,并同步更新至全局应用域
  @Override
  public void sessionCreated(HttpSessionEvent se) {
    int current = activeSessions.incrementAndGet();
    ServletContext context = se.getSession().getServletContext();

    context.setAttribute("onlineSessionCount", current);
  }

  // 3. 会话失效或超时销毁前原子递减,避免计数出现负值
  @Override
  public void sessionDestroyed(HttpSessionEvent se) {
    int current = activeSessions.updateAndGet(val -> val > 0 ? val - 1 : 0);
    ServletContext context = se.getSession().getServletContext();

    context.setAttribute("onlineSessionCount", current);
  }
}

HttpSessionIdListener ​

HttpSessionIdListener 是 Servlet 3.1 新增的监听器接口,专门用于监听现有 HttpSession 对象的唯一标识(JSESSIONID)发生变更的事件。

触发时机与安全背景 ​

在 Web 安全实践中,为了防范会话固定攻击(Session Fixation),系统在用户登录认证通过后通常需要调用 HttpServletRequest.changeSessionId() 更换会话标识,部分容器内置认证机制也会在提权时自动执行该操作。

与先注销旧会话再创建新会话的方式不同,changeSessionId() 仅替换底层会话对象的 ID 字符串并下发新的 Set-Cookie 响应头,原有的 HttpSession 实例及其内部属性全部保持不变。因此该操作不会触发 HttpSessionListener 的创建或销毁回调,而是专门触发 HttpSessionIdListener.sessionIdChanged,并将事件对象与变更前的旧标识 oldSessionId 一并传入。

如果应用在全局内存中维护了以 sessionId 为键的自定义映射表(如用于后台强制下线的 Map<String, HttpSession> 索引)或外部缓存映射,就必须通过该监听器及时移除旧键并重新关联新键,否则登录换 ID 后会导致索引悬空或踢人功能失效。

示例: 会话标识变更同步索引 ​

以下示例演示当会话标识发生变化时,将 ServletContext 中维护的自定义会话注册表键名从旧标识原子迁移至新标识:

java
package com.example.listener;

import java.util.Map;
import javax.servlet.ServletContext;
import javax.servlet.annotation.WebListener;
import javax.servlet.http.HttpSession;
import javax.servlet.http.HttpSessionEvent;
import javax.servlet.http.HttpSessionIdListener;

// 1. 监听会话标识变更事件,维护服务端自定义会话索引表的一致性
@WebListener
public class SessionIdSyncListener implements HttpSessionIdListener {

  // 2. 调用 request.changeSessionId() 后由容器触发,传入旧标识与当前会话事件
  @Override
  @SuppressWarnings("unchecked")
  public void sessionIdChanged(HttpSessionEvent se, String oldSessionId) {
    HttpSession session = se.getSession();
    String newSessionId = session.getId();
    ServletContext context = session.getServletContext();

    // 3. 从全局映射表中移除旧键并重新绑定新键,防止索引失效
    Map<String, HttpSession> registry =
        (Map<String, HttpSession>) context.getAttribute("sessionRegistry");
    if (registry != null) {
      registry.remove(oldSessionId);
      registry.put(newSessionId, session);
    }
  }
}

ServletRequestListener ​

ServletRequestListener 负责监听每一次客户端请求进入和离开 Web 应用作用域的完整生命周期。在三大域对象中,请求对象的创建频率最高、存活时间最短。

触发时机与边界特征 ​

  1. 请求初始化:当客户端发起的请求即将进入 Web 应用中的第一个 Filter 或 Servlet 之前,容器触发 requestInitialized。

  2. 请求销毁:当目标 Servlet 以及外层 Filter 链全部执行完毕、请求即将离开 Web 应用作用域时,容器触发 requestDestroyed。即便业务代码内部抛出未捕获异常,容器依然会保证触发销毁回调。

理解请求生命周期的适用范围时,需注意以下三点边界行为:

  • 覆盖范围广:只要请求命中了当前 Web 应用的上下文路径,无论是访问动态 Servlet、JSP 还是静态资源(CSS、JS、图片等,由容器默认 Servlet 处理),都会触发该监听器。
  • 内部转发与包含不重复触发:在单次 HTTP 请求处理期间,通过 RequestDispatcher.forward 或 RequestDispatcher.include 进行的站内资源跳转仍处于同一个请求生命周期内,不会再次触发 requestInitialized 或 requestDestroyed。
  • 异步 Servlet 延迟销毁:在 Servlet 3.0+ 异步处理模式(调用 request.startAsync())下,初始容器工作线程归还线程池时不会立刻销毁请求,直到调用 AsyncContext.complete()、异步超时或发生未处理异常后,容器才最终触发 requestDestroyed。

典型场景与注意事项 ​

由于单次请求的高频特性,ServletRequestListener 适合承担极轻量的请求级基础设施工作,例如记录全链路请求耗时、为日志系统绑定与清理 ThreadLocal 追踪上下文,以及统计接口访问频次。需要避免在其中执行数据库查询、远程网络调用或复杂对象序列化等重逻辑,防止放大每次请求的响应延迟。

示例: 请求耗时统计与上下文清理 ​

以下示例在请求进入时生成链路标识存入 ThreadLocal 并记录纳秒级起始时间,在请求销毁前计算总耗时,并在 finally 块中强制移除 ThreadLocal 绑定以防止线程池复用导致的数据串号与内存泄漏:

java
package com.example.listener;

import java.util.UUID;
import javax.servlet.ServletRequest;
import javax.servlet.ServletRequestEvent;
import javax.servlet.ServletRequestListener;
import javax.servlet.annotation.WebListener;
import javax.servlet.http.HttpServletRequest;

// 1. 监听请求生命周期,完成链路标识初始化、耗时统计与线程上下文清理
@WebListener
public class RequestMetricsListener implements ServletRequestListener {

  private static final ThreadLocal<String> TRACE_ID = new ThreadLocal<>();

  // 2. 请求进入应用时生成链路标识并记录纳秒级起始时间戳
  @Override
  public void requestInitialized(ServletRequestEvent sre) {
    ServletRequest request = sre.getServletRequest();
    String traceId = UUID.randomUUID().toString();

    TRACE_ID.set(traceId);
    request.setAttribute("requestStartNanos", System.nanoTime());
  }

  // 3. 请求离开应用前计算总耗时,并在 finally 语义中强制清理 ThreadLocal
  @Override
  public void requestDestroyed(ServletRequestEvent sre) {
    ServletRequest request = sre.getServletRequest();
    Long startNanos = (Long) request.getAttribute("requestStartNanos");

    try {
      if (startNanos != null && request instanceof HttpServletRequest) {
        HttpServletRequest httpReq = (HttpServletRequest) request;
        long costMs = (System.nanoTime() - startNanos) / 1_000_000L;
        System.out.println("[" + TRACE_ID.get() + "] " + httpReq.getRequestURI() + " 耗时: " + costMs + " ms");
      }
    } finally {
      // 4. 释放当前工作线程绑定的上下文,避免容器线程池复用引发串号与内存泄漏
      TRACE_ID.remove();
    }
  }
}

生命周期对比 ​

四个域生命周期监听器在触发频率、并发模型与适用边界上各有侧重,下表汇总了它们的核心差异:

监听器接口监听域对象触发时机并发特征核心注意事项
ServletContextListenerServletContext应用启动前 / 卸载后主线程单次执行销毁时必须清理后台线程;强制停机不触发
HttpSessionListenerHttpSession会话首次创建 / 失效或超时多线程高并发超时销毁受后台线程周期影响存在延迟
HttpSessionIdListenerHttpSession调用 changeSessionId() 更换标识多线程并发不触发会话创建与销毁,专用于同步会话索引
ServletRequestListenerServletRequest请求进入首节点 / 离开应用域多线程极高频包含静态资源;forward/include 不重复触发

image-20261120221809412

API: ServletContextListener【待补充】 ​

API: ServletContextEvent【待补充】 ​

API: HttpSessionListener【待补充】 ​

API: HttpSessionEvent【待补充】 ​

API: HttpSessionIdListener【待补充】 ​

API: ServletRequestListener【待补充】 ​

API: ServletRequestEvent【待补充】 ​

域属性变更监听 ​

域属性变更监听用于监控 ServletContext、HttpSession 和 ServletRequest 三大作用域对象中键值对属性的动态变化。当业务代码或容器内部向作用域执行属性写入、覆盖或移除操作时,Web 容器会自动捕获变更并向已注册的全局监听器派发事件。

与域生命周期监听相同,三个域属性变更监听器均属于容器级全局组件,必须通过 web.xml、@WebListener 或编程式 addListener 注册后才能接收事件通知。

属性操作与事件分发 ​

三大作用域的属性变更监听器遵循完全一致的事件触发模型,每个接口均定义了新增、移除和替换三类回调,由作用域上的 setAttribute 与 removeAttribute 操作驱动。

  1. 属性新增:调用 setAttribute(name, value) 且 value 非 null、当前作用域中原本不存在同名键时,容器先将属性写入作用域,随后触发 attributeAdded 回调。

  2. 属性替换:调用 setAttribute(name, value) 且 value 非 null、当前作用域中已存在同名键时,容器先用新值覆盖旧值,随后触发 attributeReplaced 回调。

  3. 属性移除:调用 removeAttribute(name) 且当前作用域中确实存在该属性时,容器先将属性从作用域移除,随后触发 attributeRemoved 回调;若目标键原本不存在,则不会触发任何回调。

实际开发中最容易踩坑的三个边界行为需要重点留意:

  • null 值写入等价于移除:按照 Servlet 规范,调用 setAttribute(name, null) 的语义等同于 removeAttribute(name)。如果该键原先存在,容器会删除属性并触发 attributeRemoved;如果该键原本就不存在,则不会触发任何事件。
  • 替换事件的旧值语义:三类属性事件对象都提供了获取属性名与属性值的方法,但在不同事件中的返回值含义存在关键差异。在新增回调中,事件对象携带的是刚刚写入的新值;在移除回调中,携带的是刚刚被删除的值;而在替换回调中,事件对象携带的是被覆盖之前的旧值。如果需要同时获取替换后的新值,必须通过事件对象拿到对应域对象后再重新查询。
  • 防止回调递归死循环:由于属性监听器会在 setAttribute 和 removeAttribute 执行期间同步回调,如果在监听器内部无条件对同一作用域再次写入或删除属性,极易引发无限递归并抛出 StackOverflowError。如确需联动更新其他属性,必须基于属性名白名单或前缀严格过滤。

image-20261120221842953

ServletContextAttributeListener ​

ServletContextAttributeListener 负责监听全局应用域中共享属性的增删改操作,对应的事件对象为 ServletContextAttributeEvent。由于 ServletContext 在整个 Web 应用内唯一且全局可见,该监听器的触发频率相对较低,但影响范围覆盖所有在线用户与业务线程。

典型场景与注意事项 ​

该监听器通常用于全局共享状态治理,例如审计运行时动态刷新的系统配置、感知全局字典缓存更新后联动清理本地派生缓存,或在测试与运维阶段监测关键全局属性是否被业务代码意外覆盖。

使用应用域属性监听时需注意以下两点:

  • 过滤容器与框架内部属性:Web 容器在启动和运行期间会向 ServletContext 写入大量内部属性(例如 Tomcat 存放临时目录的 javax.servlet.context.tempdir、JSP 引擎实例以及 Spring 根容器上下文等)。监听器必须通过明确的属性名或固定前缀进行过滤,避免对未知属性执行类型强转而抛出 ClassCastException。
  • 并发可见性与轻量回调:多个请求线程可能并发修改应用域属性,回调内部若操作共享集合或缓存结构需保证线程安全,同时避免在回调中执行耗时的远程同步调用。

示例: 全局配置属性变更审计 ​

以下示例通过前缀过滤机制,仅对 app.config. 开头的全局配置属性进行增删改审计,并演示在替换回调中同时获取旧值与新值的标准写法:

java
package com.example.listener;

import javax.servlet.ServletContext;
import javax.servlet.ServletContextAttributeEvent;
import javax.servlet.ServletContextAttributeListener;
import javax.servlet.annotation.WebListener;

// 1. 监听应用域全局属性变更,按前缀过滤并审计关键配置变动
@WebListener
public class GlobalConfigAuditListener implements ServletContextAttributeListener {

  private static final String CONFIG_PREFIX = "app.config.";

  // 2. 新增目标前缀配置时记录写入审计日志
  @Override
  public void attributeAdded(ServletContextAttributeEvent scae) {
    String name = scae.getName();
    if (!name.startsWith(CONFIG_PREFIX)) {
      return;
    }

    System.out.println("[新增配置] " + name + " = " + scae.getValue());
  }

  // 3. 覆盖配置时,event.getValue() 返回的是旧值,新值需从应用域重新读取
  @Override
  public void attributeReplaced(ServletContextAttributeEvent scae) {
    String name = scae.getName();
    if (!name.startsWith(CONFIG_PREFIX)) {
      return;
    }

    ServletContext context = scae.getServletContext();
    Object oldValue = scae.getValue();
    Object newValue = context.getAttribute(name);

    System.out.println("[变更配置] " + name + " : " + oldValue + " -> " + newValue);
  }

  // 4. 移除配置时,event.getValue() 返回刚刚被删除的属性值
  @Override
  public void attributeRemoved(ServletContextAttributeEvent scae) {
    String name = scae.getName();
    if (!name.startsWith(CONFIG_PREFIX)) {
      return;
    }

    System.out.println("[移除配置] " + name + " (原值: " + scae.getValue() + ")");
  }
}

HttpSessionAttributeListener ​

HttpSessionAttributeListener 负责监听任意客户端会话中属性的增删改操作。与另外两个作用域不同,它的回调参数并非命名为 HttpSessionAttributeEvent,而是复用了 HttpSessionBindingEvent(该事件类同时服务于感知型监听器 HttpSessionBindingListener)。

触发边界与会话失效联动 ​

相较于 HttpSessionListener 只能感知会话整体的创建与销毁(包含未登录的匿名访客),HttpSessionAttributeListener 能够精准捕获登录凭证、权限集合、购物车对象等特定业务属性的写入与变更,是在线登录用户清单维护与单点登录互踢的核心实现机制。

在会话销毁场景下,该监听器具备一项重要的自动联动特性:

  • 会话失效自动触发属性移除:当业务代码调用 session.invalidate() 主动注销,或会话空闲超时被容器后台线程清理时,容器会逐一解绑该会话中尚存的所有属性,并依次触发 attributeRemoved 回调。因此即使客户端直接关闭浏览器未调用登出接口,监听器依然能在会话超时后自动完成在线用户表的清理。
  • 互踢场景下的竞态保护:在实现同账号异地登录互踢时,当新会话踢掉旧会话(调用旧会话的 invalidate()),旧会话会随之触发 attributeRemoved。若清理在线映射表时仅按用户名直接删除,可能会误删刚刚存入的新会话映射;正确做法是使用 ConcurrentHashMap 的双参数条件移除方法,仅当映射中当前值等于被销毁的会话实例时才执行删除。

示例: 登录态追踪与单点互踢 ​

以下示例监听会话中的 loginUser 属性变化,在用户重复登录时自动使先前会话失效,并通过双参数条件移除规避旧会话失效回调误删新会话的竞态问题:

java
package com.example.listener;

import java.util.concurrent.ConcurrentHashMap;
import javax.servlet.annotation.WebListener;
import javax.servlet.http.HttpSession;
import javax.servlet.http.HttpSessionAttributeListener;
import javax.servlet.http.HttpSessionBindingEvent;

// 1. 监听会话登录属性变更,维护在线用户映射并实现单点互踢
@WebListener
public class SingleLoginSessionListener implements HttpSessionAttributeListener {

  private static final String LOGIN_USER_KEY = "loginUser";
  private static final ConcurrentHashMap<String, HttpSession> ONLINE_USERS =
      new ConcurrentHashMap<>();

  // 2. 用户登录写入凭证时登记新会话,若存在旧会话则强制使其失效
  @Override
  public void attributeAdded(HttpSessionBindingEvent event) {
    if (!LOGIN_USER_KEY.equals(event.getName())) {
      return;
    }

    String username = String.valueOf(event.getValue());
    HttpSession currentSession = event.getSession();
    HttpSession previousSession = ONLINE_USERS.put(username, currentSession);

    if (previousSession != null && !previousSession.getId().equals(currentSession.getId())) {
      previousSession.invalidate();
    }
  }

  // 3. 同一会话内切换登录账号时,清理旧账号映射并为新账号执行互踢检查
  @Override
  public void attributeReplaced(HttpSessionBindingEvent event) {
    if (!LOGIN_USER_KEY.equals(event.getName())) {
      return;
    }

    HttpSession currentSession = event.getSession();
    String oldUsername = String.valueOf(event.getValue());
    String newUsername = String.valueOf(currentSession.getAttribute(LOGIN_USER_KEY));

    ONLINE_USERS.remove(oldUsername, currentSession);
    HttpSession previousSession = ONLINE_USERS.put(newUsername, currentSession);
    if (previousSession != null && !previousSession.getId().equals(currentSession.getId())) {
      previousSession.invalidate();
    }
  }

  // 4. 主动注销、移除属性或会话超时失效时,按会话实例精确清理在线记录
  @Override
  public void attributeRemoved(HttpSessionBindingEvent event) {
    if (!LOGIN_USER_KEY.equals(event.getName())) {
      return;
    }

    String username = String.valueOf(event.getValue());
    ONLINE_USERS.remove(username, event.getSession());
  }
}

ServletRequestAttributeListener ​

ServletRequestAttributeListener 负责监听单次 HTTP 请求处理期间请求域属性的增删改操作,对应的事件对象为 ServletRequestAttributeEvent。

典型场景与性能边界 ​

在三大属性变更监听器中,请求域属性监听器的触发频率最高。它主要用于研发调试阶段追踪数据在 Filter、控制器 Servlet、RequestDispatcher.forward 转发链路以及 JSP 视图渲染之间的流转轨迹,排查请求属性在多层转发中被意外覆盖或丢失的问题。

生产环境启用该监听器时需严格把控性能边界:

  • 极高频的内部属性写入:除了业务代码显式调用 request.setAttribute 外,容器转发机制(如写入 javax.servlet.forward.request_uri 等标准转发属性)、JSP 标签库以及 Web MVC 框架都会在单次请求中高频读写大量请求域属性。
  • 避免无过滤全量输出:监听器内部严禁不加过滤地打印所有请求属性或执行 I/O 操作,必须精确匹配目标属性名,且调试类监听器通常建议通过配置开关按编程方式动态注册,仅在排查环境开启。

示例: 请求域敏感属性追踪 ​

以下示例仅追踪请求域中名为 orderContext 的业务上下文对象,在请求转发与多阶段处理过程中记录其初始写入与后续覆盖情况:

java
package com.example.listener;

import javax.servlet.ServletRequestAttributeEvent;
import javax.servlet.ServletRequestAttributeListener;
import javax.servlet.annotation.WebListener;

// 1. 追踪单次请求转发链路上特定业务属性的写入与覆盖过程
@WebListener
public class RequestAttributeTraceListener implements ServletRequestAttributeListener {

  private static final String TRACE_KEY = "orderContext";

  // 2. 仅追踪目标业务属性,过滤容器与视图引擎写入的内部属性
  @Override
  public void attributeAdded(ServletRequestAttributeEvent srae) {
    if (!TRACE_KEY.equals(srae.getName())) {
      return;
    }

    System.out.println("[请求属性新增] " + TRACE_KEY + " = " + srae.getValue());
  }

  // 3. 捕获转发链条中的属性覆盖,同时输出旧值与覆盖后的新值
  @Override
  public void attributeReplaced(ServletRequestAttributeEvent srae) {
    if (!TRACE_KEY.equals(srae.getName())) {
      return;
    }

    Object oldValue = srae.getValue();
    Object newValue = srae.getServletRequest().getAttribute(TRACE_KEY);

    System.out.println("[请求属性覆盖] " + oldValue + " -> " + newValue);
  }
}

属性监听对比 ​

三个域属性变更监听器在事件对象命名、触发频次与典型用途上的核心差异如下表所示:

监听器接口监听域对象对应事件对象触发频次典型应用场景
ServletContextAttributeListenerServletContextServletContextAttributeEvent低全局配置变更审计、应用级缓存同步刷新
HttpSessionAttributeListenerHttpSessionHttpSessionBindingEvent中已登录用户追踪、单点登录互踢、会话状态审计
ServletRequestAttributeListenerServletRequestServletRequestAttributeEvent极高转发链路数据流追踪、请求域属性覆盖排查

image-20261120221908813

API: ServletContextAttributeListener【待补充】 ​

API: ServletContextAttributeEvent【待补充】 ​

API: HttpSessionAttributeListener【待补充】 ​

API: HttpSessionBindingEvent【待补充】 ​

API: ServletRequestAttributeListener【待补充】 ​

API: ServletRequestAttributeEvent【待补充】 ​

感知型监听 ​

感知型监听是 Servlet 规范中一类特殊的事件监听模型,专门服务于存放在 HttpSession 中的普通 JavaBean 对象。与前两章介绍的七个全局监听器不同,感知型监听器并非站在容器视角监控整个应用或所有会话,而是直接由业务对象自身实现接口,从而使对象能够主动感知自己在会话中的生命周期与存储状态变化。

感知型监听包含 HttpSessionBindingListener 和 HttpSessionActivationListener 两个接口,它们具有一个共同的显著特征:严禁向 Web 容器显式注册。开发者无需也不应在实现类上标注 @WebListener 或在 web.xml 中配置 <listener>;若尝试通过 ServletContext.addListener 动态注册,容器会直接抛出 IllegalArgumentException。每当业务代码操作会话属性或容器执行会话持久化时,容器会自动通过 instanceof 检测目标对象类型并直接触发对应回调。

HttpSessionBindingListener ​

HttpSessionBindingListener 用于让业务对象感知自身被绑定至 HttpSession 以及从 HttpSession 解绑的完整过程,对应的事件对象为 HttpSessionBindingEvent。

触发时机与解绑场景 ​

容器在执行会话属性变更操作时,会对属性对象进行类型检查并同步触发绑定或解绑回调:

  1. 绑定触发:当业务代码调用 session.setAttribute(name, obj) 且 obj 实现了 HttpSessionBindingListener 时,容器在将该对象绑定到会话的过程中触发 valueBound 回调。

  2. 解绑触发:以下四种场景会自动触发目标对象的 valueUnbound 回调:

    • 业务代码调用 session.removeAttribute(name) 或 session.setAttribute(name, null) 显式移除该属性。
    • 业务代码调用 session.setAttribute(name, newObj) 使用另一个对象覆盖同名键(被覆盖的旧对象触发 valueUnbound,若新对象也实现该接口则同步触发其 valueBound)。
    • 业务代码调用 session.invalidate() 主动销毁当前会话。
    • 会话空闲超过有效时间被容器后台线程清理销毁。

需要注意一种边界情况:如果对同一个键重复传入完全相同的对象引用(即 oldObj == newObj),在 Tomcat 等主流容器实现中仍会先判定属性替换并按规范触发回调,或在特定实现中避免重复绑定,因此业务代码中应避免无意义地将同一对象反复以相同键名写入会话。

与 HttpSessionAttributeListener 对比 ​

HttpSessionBindingListener 与 HttpSessionAttributeListener 均能响应会话属性的新增与移除,且共用同一个事件类 HttpSessionBindingEvent,但二者在职责边界、注册方式和回调顺序上存在明确区别:

对比维度HttpSessionBindingListenerHttpSessionAttributeListener
实现载体存入 HttpSession 的普通业务对象独立的容器级全局监听器类
是否需要注册否,放入会话即自动生效是,须通过注解、XML 或 API 注册
监听粒度仅感知当前对象自身的绑定与解绑全局监控所有会话中任意属性的增删改
替换事件处理拆分为新对象绑定与旧对象解绑触发一次 attributeReplaced 回调
典型用途对象自管理的资源绑定、登录实体自维护在线状态跨业务对象的统一审计、集中式单点互踢

当应用中同时存在全局 HttpSessionAttributeListener 与实现了 HttpSessionBindingListener 的属性对象时,容器遵循以下回调先后顺序:

  1. 新增属性:先回调属性对象自身的 valueBound,将属性写入会话内部映射表后,再回调全局监听器的 attributeAdded。

  2. 移除属性:先从会话内部映射表中移除该属性,接着回调属性对象自身的 valueUnbound,最后回调全局监听器的 attributeRemoved。

  3. 覆盖替换:先回调新对象的 valueBound(若新对象实现接口),随后更新映射表,再回调旧对象的 valueUnbound(若旧对象实现接口),最后回调全局监听器的 attributeReplaced。

image-20261120221937144

示例: 登录对象自感知在线状态 ​

以下示例让登录用户实体直接实现 HttpSessionBindingListener。当登录控制器将用户对象存入 HttpSession 时,对象自动将自身登记到 ServletContext 的在线用户集合;当用户注销、属性被覆盖或会话超时失效时,对象自动完成自我清理:

java
package com.example.model;

import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import javax.servlet.ServletContext;
import javax.servlet.http.HttpSessionBindingEvent;
import javax.servlet.http.HttpSessionBindingListener;

// 1. 由会话中存放的业务对象自身实现接口,无需在容器中进行任何注册
public class LoginUserBean implements HttpSessionBindingListener {

  private final String username;

  public LoginUserBean(String username) {
    this.username = username;
  }

  public String getUsername() {
    return username;
  }

  // 2. 对象通过 setAttribute 绑定到会话时触发,自动登记至全局在线名单
  @Override
  public void valueBound(HttpSessionBindingEvent event) {
    ServletContext context = event.getSession().getServletContext();
    Set<String> onlineUsers = getOrCreateOnlineSet(context);

    onlineUsers.add(username);
  }

  // 3. 对象被移除、覆盖或会话失效超时时触发,自动从在线名单中清理
  @Override
  public void valueUnbound(HttpSessionBindingEvent event) {
    ServletContext context = event.getSession().getServletContext();
    Set<String> onlineUsers = getOrCreateOnlineSet(context);

    onlineUsers.remove(username);
  }

  @SuppressWarnings("unchecked")
  private Set<String> getOrCreateOnlineSet(ServletContext context) {
    synchronized (context) {
      Set<String> set = (Set<String>) context.getAttribute("onlineUsers");
      if (set == null) {
        set = ConcurrentHashMap.newKeySet();
        context.setAttribute("onlineUsers", set);
      }
      return set;
    }
  }
}

HttpSessionActivationListener ​

HttpSessionActivationListener 用于让存放在 HttpSession 中的对象感知会话的钝化(Passivation)与活化(Activation)过程,对应的事件对象为 HttpSessionEvent。

钝化与活化流程 ​

在并发用户量较大或部署了多节点集群的 Web 应用中,将所有活跃会话长期滞留在 JVM 堆内存中会造成显著的内存压力,同时服务器正常重启也可能导致用户登录态丢失。为此,Servlet 容器提供了会话持久化与迁移机制:

  1. 钝化:当会话长时间处于空闲状态、容器正常关闭或集群需要将当前会话迁移至其他 JVM 节点时,容器先调用会话内所有实现 HttpSessionActivationListener 对象的 sessionWillPassivate 回调,随后将会话及其属性序列化写入本地磁盘文件或传输至远端节点,并释放其占用的内存空间。

  2. 活化:当客户端再次携带对应 JSESSIONID 发起请求、容器重新启动加载持久化文件,或集群目标节点接收会话数据时,容器先执行反序列化将对象恢复至 JVM 堆内存,紧接着调用对象的 sessionDidActivate 回调通知对象完成状态恢复。

image-20261120221959042

序列化约束与 Tomcat 配置 ​

实现 HttpSessionActivationListener 时,必须满足严格的序列化与资源管理规范:

  • **必须实现 Serializable**:钝化与活化的底层依赖 Java 对象序列化机制,因此目标 JavaBean 必须同时实现 java.io.Serializable接口,并显式声明稳定的serialVersionUID。如果对象未实现 Serializable,Tomcat 在钝化时会跳过该属性并记录序列化警告,导致对象在活化后丢失,且不会触发活化回调。
  • 使用 transient 隔离非序列化资源:如果对象内部持有无法序列化或序列化代价极高的成员(例如临时计算缓存、数据库连接、文件句柄或外部服务客户端引用),必须使用 transient 关键字修饰。在 sessionWillPassivate 中主动释放或清空这类资源,并在 sessionDidActivate 中按需重新构建。

在 Tomcat 9 中,会话钝化有两种常见触发途径:

  • 容器正常停启持久化:Tomcat 默认的 StandardManager 在执行正常关闭脚本(如 shutdown.sh)时,会将当前活跃会话自动钝化至 work 目录下的 SESSIONS.ser 文件中,下次启动时自动活化加载。
  • 空闲自动换出配置:若希望在运行期间将空闲超过指定秒数的会话自动钝化到磁盘,可在项目的 META-INF/context.xml 中配置 PersistentManager 与 FileStore:
xml
<?xml version="1.0" encoding="UTF-8"?>
<Context>
  <!-- 1. 配置持久化会话管理器,空闲超过 60 秒后自动将会话钝化至磁盘 -->
  <Manager className="org.apache.catalina.session.PersistentManager" maxIdleSwap="60">
    <!-- 2. 指定文件存储实现及相对工作目录的钝化文件存放路径 -->
    <Store className="org.apache.catalina.session.FileStore" directory="session-store"/>
  </Manager>
</Context>

示例: 钝化释放与活化重建瞬态资源 ​

以下示例演示一个会话工作区对象如何同时实现 HttpSessionActivationListener 与 Serializable,在钝化前释放 transient 修饰的本地缓存,并在活化后自动重建缓存容器:

java
package com.example.model;

import java.io.Serializable;
import java.util.HashMap;
import java.util.Map;
import javax.servlet.http.HttpSessionActivationListener;
import javax.servlet.http.HttpSessionEvent;

// 1. 必须同时实现 Serializable 接口,对象才能随会话完成序列化钝化与反序列化活化
public class SessionWorkspace implements HttpSessionActivationListener, Serializable {

  private static final long serialVersionUID = 1L;
  private final String userId;

  // 2. 不可序列化或占用大量内存的临时缓存使用 transient 修饰,避免参与持久化
  private transient Map<String, Object> localCache;

  public SessionWorkspace(String userId) {
    this.userId = userId;
    this.localCache = new HashMap<>();
  }

  // 3. 会话即将钝化到磁盘前回调,主动释放瞬态资源
  @Override
  public void sessionWillPassivate(HttpSessionEvent se) {
    if (localCache != null) {
      localCache.clear();
    }
    System.out.println("工作区即将钝化,用户: " + userId);
  }

  // 4. 会话重新活化至内存后回调,重建被 transient 忽略的瞬态缓存
  @Override
  public void sessionDidActivate(HttpSessionEvent se) {
    this.localCache = new HashMap<>();
    System.out.println("工作区已活化恢复,用户: " + userId);
  }
}

感知型监听对比 ​

两个感知型监听器均由会话内 JavaBean 自身实现,且均无需向容器注册,但在触发条件与前置约束上各有侧重:

监听器接口监听事件对应事件对象是否必须实现 Serializable典型应用场景
HttpSessionBindingListener对象绑定至会话 / 从会话解绑HttpSessionBindingEvent否登录对象自维护在线状态、绑定对象的专属资源清理
HttpSessionActivationListener会话钝化前 / 活化后HttpSessionEvent是持久化或集群迁移前释放瞬态资源、恢复后重建本地缓存

API: HttpSessionBindingListener【待补充】 ​

API: HttpSessionActivationListener【待补充】 ​

API: HttpSessionBindingEvent【待补充】 ​

API: HttpSessionEvent【待补充】 ​