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.

USAGE CONSTRAINTS:

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

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	PersistentValve.UsageCountingSemaphore

Field Summary

Modifier and Type	Field and Description
private volatile boolean	clBindRequired
protected Pattern	filter
private static final ClassLoader	MY_CLASSLOADER
private boolean	semaphoreAcquireUninterruptibly
private boolean	semaphoreBlockOnAcquire
private boolean	semaphoreFairness
private ConcurrentMap<String, PersistentValve.UsageCountingSemaphore>	sessionToSemaphoreMap

Inherited from org.apache.catalina.valves.ValveBase:: asyncSupported container containerLog next sm

Constructor Summary

Access	Constructor and Description
public	PersistentValve()

Method Summary

Modifier and Type	Method and Description
private void	bind(Context context)
public String	getFilter()
public void	invoke(Request Request to be processed request, Response Response to be produced response) Implements org.apache.catalina.Valve.invoke. Select the appropriate child Context to process this request, based on the specified request URI.
protected boolean	isRequestWithoutSession(String uri)
public boolean	Returns: `true` if the thread can not be interrupted, otherwise `false`. isSemaphoreAcquireUninterruptibly() If a thread is blocking to acquire a per session Semaphore, can that thread be interrupted?
public boolean	Returns: `true` if the thread should block, otherwise `false` to reject the concurrent request isSemaphoreBlockOnAcquire() If a thread attempts to acquire the per session Semaphore while it is being used by another request, should the thread block to wait for the Semaphore or should the request be rejected?
public boolean	Returns: `true` if fairness is enabled, otherwise `false` isSemaphoreFairness() If multiple threads attempt to acquire the same per session Semaphore, will permits be granted in the same order they were requested?
protected boolean	Returns: `true` if the session is past its expiration isSessionStale(Session The session to check session, long The current time to check for timeNow) Indicate whether the session has been idle for longer than its expiration date as of the supplied time.
protected void	onSemaphoreNotAcquired(Request The request that will not be processed request, Response The response that will be used for this request response) Handle the case where a semaphore cannot be obtained.
public void	setContainer(Container The Container instance with which this instance is to be associated, or `null` to disassociate this instance from any Container container) Overrides org.apache.catalina.valves.ValveBase.setContainer. Implements org.apache.catalina.Contained.setContainer. Set the `Container` with which this instance is associated.
public void	setFilter(String filter)
public void	setSemaphoreAcquireUninterruptibly(boolean `true` if the thread can not be interrupted, otherwise `false`. semaphoreAcquireUninterruptibly) Configure whether a thread blocking to acquire a per session Semaphore can be interrupted.
public void	setSemaphoreBlockOnAcquire(boolean `true` to block, otherwise `false` semaphoreBlockOnAcquire) Configure whether a thread should block and wait for the per session Semaphore or reject the request if the Semaphore is being used by another request.
public void	setSemaphoreFairness(boolean `true` if permits should be granted in the same order they are requested, otherwise `false` semaphoreFairness) Configure whether the per session Semaphores will handle granting of permits in the same order they were requested if multiple threads attempt to acquire the same Semaphore.
private void	unbind(Context context)

Inherited from org.apache.catalina.valves.ValveBase:: backgroundProcess getContainer getDomainInternal getNext getObjectNameKeyProperties initInternal isAsyncSupported setAsyncSupported setNext startInternal stopInternal toString

Field Detail

clBindRequired	back to summary
private volatile boolean clBindRequired

filter	back to summary
protected Pattern filter

MY_CLASSLOADER	back to summary
private static final ClassLoader MY_CLASSLOADER

semaphoreAcquireUninterruptibly	back to summary
private boolean semaphoreAcquireUninterruptibly

semaphoreBlockOnAcquire	back to summary
private boolean semaphoreBlockOnAcquire

semaphoreFairness	back to summary
private boolean semaphoreFairness

sessionToSemaphoreMap	back to summary
private ConcurrentMap<String, PersistentValve.UsageCountingSemaphore> sessionToSemaphoreMap

Constructor Detail

PersistentValve	back to summary
public PersistentValve()

Method Detail

bind	back to summary
private void bind(Context context)

getFilter	back to summary
public String getFilter()

invoke	back to summary
public void invoke(Request request, Response response) throws IOException, ServletException Implements org.apache.catalina.Valve.invoke. Select the appropriate child Context to process this request, based on the specified request URI. If no matching Context can be found, return an appropriate HTTP error. Parameters request:Request Request to be processed response:Response Response to be produced Annotations @Override Exceptions IOException: if an input/output error occurred ServletException: if a servlet error occurred

invoke

back to summary

public void invoke(Request request, Response response) throws IOException, ServletException

Implements org.apache.catalina.Valve.invoke.

Select the appropriate child Context to process this request, based on the specified request URI. If no matching Context can be found, return an appropriate HTTP error.

Parameters

request:Request: Request to be processed
response:Response: Response to be produced

Annotations

@Override

Exceptions

IOException:: if an input/output error occurred
ServletException:: if a servlet error occurred

isRequestWithoutSession	back to summary
protected boolean isRequestWithoutSession(String uri)

isSemaphoreAcquireUninterruptibly back to summary

isSemaphoreAcquireUninterruptibly	back to summary
public boolean isSemaphoreAcquireUninterruptibly() If a thread is blocking to acquire a per session Semaphore, can that thread be interrupted? Returns:boolean `true` if the thread can not be interrupted, otherwise `false`.

public boolean isSemaphoreAcquireUninterruptibly()

If a thread is blocking to acquire a per session Semaphore, can that thread be interrupted?

Returns:boolean: true if the thread can not be interrupted, otherwise false.

isSemaphoreBlockOnAcquire back to summary

isSemaphoreBlockOnAcquire	back to summary
public boolean isSemaphoreBlockOnAcquire() If a thread attempts to acquire the per session Semaphore while it is being used by another request, should the thread block to wait for the Semaphore or should the request be rejected? Returns:boolean `true` if the thread should block, otherwise `false` to reject the concurrent request

public boolean isSemaphoreBlockOnAcquire()

If a thread attempts to acquire the per session Semaphore while it is being used by another request, should the thread block to wait for the Semaphore or should the request be rejected?

Returns:boolean: true if the thread should block, otherwise false to reject the concurrent request

isSemaphoreFairness back to summary

isSemaphoreFairness	back to summary
public boolean isSemaphoreFairness() If multiple threads attempt to acquire the same per session Semaphore, will permits be granted in the same order they were requested? Returns:boolean `true` if fairness is enabled, otherwise `false`

public boolean isSemaphoreFairness()

If multiple threads attempt to acquire the same per session Semaphore, will permits be granted in the same order they were requested?

Returns:boolean: true if fairness is enabled, otherwise false

isSessionStale back to summary

isSessionStale	back to summary
protected boolean isSessionStale(Session session, long timeNow) Indicate whether the session has been idle for longer than its expiration date as of the supplied time. Parameters session:Session The session to check timeNow:long The current time to check for Returns:boolean `true` if the session is past its expiration

protected boolean isSessionStale(Session session, long timeNow)

Indicate whether the session has been idle for longer than its expiration date as of the supplied time.

Parameters

session:Session: The session to check
timeNow:long: The current time to check for

Returns:boolean

true if the session is past its expiration

onSemaphoreNotAcquired	back to summary
protected void onSemaphoreNotAcquired(Request request, Response response) throws IOException Handle the case where a semaphore cannot be obtained. The default behaviour is to return a 429 (too many requests) status code. Parameters request:Request The request that will not be processed response:Response The response that will be used for this request Exceptions IOException: If an I/O error occurs while working with the request or response

onSemaphoreNotAcquired

back to summary

protected void onSemaphoreNotAcquired(Request request, Response response) throws IOException

Handle the case where a semaphore cannot be obtained. The default behaviour is to return a 429 (too many requests) status code.

Parameters

request:Request: The request that will not be processed
response:Response: The response that will be used for this request

Exceptions

IOException:: If an I/O error occurs while working with the request or response

setContainer back to summary

setContainer	back to summary
public void setContainer(Container container) Overrides org.apache.catalina.valves.ValveBase.setContainer. Implements org.apache.catalina.Contained.setContainer. Doc from org.apache.catalina.Contained.setContainer. Set the `Container` with which this instance is associated. Parameters container:Container The Container instance with which this instance is to be associated, or `null` to disassociate this instance from any Container Annotations @Override

public void setContainer(Container container)

Overrides org.apache.catalina.valves.ValveBase.setContainer.

Implements org.apache.catalina.Contained.setContainer.

Doc from org.apache.catalina.Contained.setContainer.

Set the Container with which this instance is associated.

Parameters

container:Container: The Container instance with which this instance is to be associated, or null to disassociate this instance from any Container

Annotations

@Override

setFilter	back to summary
public void setFilter(String filter)

setSemaphoreAcquireUninterruptibly back to summary

setSemaphoreAcquireUninterruptibly	back to summary
public void setSemaphoreAcquireUninterruptibly(boolean semaphoreAcquireUninterruptibly) Configure whether a thread blocking to acquire a per session Semaphore can be interrupted. Parameters semaphoreAcquireUninterruptibly:boolean `true` if the thread can not be interrupted, otherwise `false`.

public void setSemaphoreAcquireUninterruptibly(boolean semaphoreAcquireUninterruptibly)

Configure whether a thread blocking to acquire a per session Semaphore can be interrupted.

Parameters

semaphoreAcquireUninterruptibly:boolean: true if the thread can not be interrupted, otherwise false.

setSemaphoreBlockOnAcquire back to summary

setSemaphoreBlockOnAcquire	back to summary
public void setSemaphoreBlockOnAcquire(boolean semaphoreBlockOnAcquire) Configure whether a thread should block and wait for the per session Semaphore or reject the request if the Semaphore is being used by another request. Parameters semaphoreBlockOnAcquire:boolean `true` to block, otherwise `false`

public void setSemaphoreBlockOnAcquire(boolean semaphoreBlockOnAcquire)

Configure whether a thread should block and wait for the per session Semaphore or reject the request if the Semaphore is being used by another request.

Parameters

semaphoreBlockOnAcquire:boolean: true to block, otherwise false

setSemaphoreFairness back to summary

setSemaphoreFairness	back to summary
public void setSemaphoreFairness(boolean semaphoreFairness) Configure whether the per session Semaphores will handle granting of permits in the same order they were requested if multiple threads attempt to acquire the same Semaphore. Parameters semaphoreFairness:boolean `true` if permits should be granted in the same order they are requested, otherwise `false`

public void setSemaphoreFairness(boolean semaphoreFairness)

Configure whether the per session Semaphores will handle granting of permits in the same order they were requested if multiple threads attempt to acquire the same Semaphore.

Parameters

semaphoreFairness:boolean: true if permits should be granted in the same order they are requested, otherwise false

unbind	back to summary
private void unbind(Context context)

org.apache.catalina.valves back to summary

private Class PersistentValve.UsageCountingSemaphore

Class Inheritance

extends Object

java.lang.Object
org.apache.catalina.valves.PersistentValve.UsageCountingSemaphore

Field Summary

Modifier and Type	Field and Description
private final Semaphore	semaphore
private final AtomicLong	usageCount

Constructor Summary

Access	Constructor and Description
private	UsageCountingSemaphore(boolean fairness)

Method Summary

Modifier and Type	Method and Description
private void	acquire()
private void	acquireUninterruptibly()
private long	decrementAndGetUsageCount()
private PersistentValve.UsageCountingSemaphore	incrementUsageCount()
private void	release()
private boolean	tryAcquire()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

semaphore	back to summary
private final Semaphore semaphore

usageCount	back to summary
private final AtomicLong usageCount

Constructor Detail

UsageCountingSemaphore	back to summary
private UsageCountingSemaphore(boolean fairness)

Method Detail

acquire	back to summary
private void acquire() throws InterruptedException

acquireUninterruptibly	back to summary
private void acquireUninterruptibly()

decrementAndGetUsageCount	back to summary
private long decrementAndGetUsageCount()

incrementUsageCount	back to summary
private PersistentValve.UsageCountingSemaphore incrementUsageCount()

release	back to summary
private void release()

tryAcquire	back to summary
private boolean tryAcquire()

public Class PersistentValve

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class PersistentValve.UsageCountingSemaphore

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail