Class PersistentValve

All Implemented Interfaces:
MBeanRegistration, Contained, JmxEnabled, Lifecycle, Valve

public class PersistentValve extends ValveBase
Valve that implements per-request session persistence. It is intended to be used with non-sticky load-balancers and a PersistentManager. The Valve works by loading the session from the Store at the start of the request, the request then updates the session as required and the Valve saves the session to the Store at the end of the request.

To avoid conflicts and/or errors when updating the session store, each session must only be accessed by no more than one concurrent request. The filter field can be used to define requests (e.g. those for static resources) that do not need access to the session and can Requests for resources that do not need to access the session and can bypass the session load/save functionality provided by this Valve.

The Valve uses a per session Semaphore to ensure that each session is accessed by no more than one request at a time within a single Tomcat instance. The behaviour if multiple requests try to access the session concurrently can be controlled by the semaphoreFairness, semaphoreBlockOnAcquire and semaphoreAcquireUninterruptibly fields. If a request fails to obtain the Semaphore, the response is generated by the onSemaphoreNotAcquired(Request, Response) method which, by default, returns a 429 status code.

The per session Semaphores only provide limited protection against concurrent requests within a single Tomcat instance. If multiple requests access the same session concurrently across different Tomcat instances, update conflicts and/or session data loss and/or errors are very likely.


  • This Valve must only be used with a PersistentManager
  • The client must ensure that no more than one concurrent request accesses a session at any time across all Tomcat instances