SemaphoreValve (Apache Tomcat 11.0.24 API Documentation)
Description: declaration: package: org.apache.catalina.valves, class: SemaphoreValve

# Class SemaphoreValve

java.lang.Object
org.apache.catalina.util.LifecycleBase
org.apache.catalina.util.LifecycleMBeanBase
org.apache.catalina.valves.ValveBase
org.apache.catalina.valves.SemaphoreValve

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

public class SemaphoreValve extends ValveBase

Implementation of a Valve that limits concurrency.

This Valve may be attached to any Container, depending on the granularity of the concurrency control you wish to perform. Note that internally, some async requests may require multiple serial requests to complete what - to the user - appears as a single request.

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from interface Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected boolean`
  `block`
  Block until a permit is available.
  `protected int`
  `concurrency`
  Concurrency level of the semaphore.
  `protected boolean`
  `fairness`
  Fairness of the semaphore.
  `protected int`
  `highConcurrencyStatus`
  High concurrency status.
  `protected boolean`
  `interruptible`
  Block interruptibly until a permit is available.
  `protected Semaphore`
  `semaphore`
  Semaphore.

  ### Fields inherited from class ValveBase

  `asyncSupported, container, containerLog, next, sm`

  ### Fields inherited from interface Lifecycle

  `AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SemaphoreValve()`
  Construct a new `SemaphoreValve` with async support enabled.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `controlConcurrency(Request request, Response response)`
  Subclass friendly method to add conditions.
  `boolean`
  `getBlock()`
  Return whether the valve blocks until a permit is available.
  `int`
  `getConcurrency()`
  Return the concurrency level of the semaphore.
  `boolean`
  `getFairness()`
  Return the fairness setting of the semaphore.
  `int`
  `getHighConcurrencyStatus()`
  Return the HTTP status code returned when concurrency is too high.
  `boolean`
  `getInterruptible()`
  Return whether the valve blocks interruptibly.
  `void`
  `invoke(Request request, Response response)`
  Do concurrency control on the request using the semaphore.
  `void`
  `permitDenied(Request request, Response response)`
  Subclass friendly method to add error handling when a permit isn't granted.
  `void`
  `setBlock(boolean block)`
  Set whether the valve blocks until a permit is available.
  `void`
  `setConcurrency(int concurrency)`
  Set the concurrency level of the semaphore.
  `void`
  `setFairness(boolean fairness)`
  Set the fairness setting of the semaphore.
  `void`
  `setHighConcurrencyStatus(int highConcurrencyStatus)`
  Set the HTTP status code returned when concurrency is too high.
  `void`
  `setInterruptible(boolean interruptible)`
  Set whether the valve blocks interruptibly.
  `protected void`
  `startInternal()`
  Start this component and implement the requirements of `LifecycleBase.startInternal()`.
  `protected void`
  `stopInternal()`
  Stop this component and implement the requirements of `LifecycleBase.stopInternal()`.

  ### Methods inherited from class ValveBase

  `backgroundProcess, getContainer, getDomainInternal, getNext, getObjectNameKeyProperties, initInternal, isAsyncSupported, setAsyncSupported, setContainer, setNext, toString`

  ### Methods inherited from class LifecycleMBeanBase

  `destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregister`

  ### Methods inherited from class LifecycleBase

  `addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### semaphore

    protected Semaphore semaphore
    Semaphore.

  - ### concurrency

    protected int concurrency
    Concurrency level of the semaphore.

  - ### fairness

    protected boolean fairness
    Fairness of the semaphore.

  - ### block

    protected boolean block
    Block until a permit is available.

  - ### interruptible

    protected boolean interruptible
    Block interruptibly until a permit is available.

  - ### highConcurrencyStatus

    protected int highConcurrencyStatus
    High concurrency status. This status code is returned as an error if concurrency is too high.

- ## Constructor Details

  - ### SemaphoreValve

    public SemaphoreValve()
    Construct a new `SemaphoreValve` with async support enabled.

- ## Method Details

  - ### getConcurrency

    public int getConcurrency()
    Return the concurrency level of the semaphore.
    Returns:
      the concurrency level

  - ### setConcurrency

    public void setConcurrency(int concurrency)
    Set the concurrency level of the semaphore.
    Parameters:
      `concurrency` - the concurrency level

  - ### getFairness

    public boolean getFairness()
    Return the fairness setting of the semaphore.
    Returns:
      `true` if the semaphore uses fair ordering

  - ### setFairness

    public void setFairness(boolean fairness)
    Set the fairness setting of the semaphore.
    Parameters:
      `fairness` - `true` if the semaphore should use fair ordering

  - ### getBlock

    public boolean getBlock()
    Return whether the valve blocks until a permit is available.
    Returns:
      `true` if the valve blocks waiting for a permit

  - ### setBlock

    public void setBlock(boolean block)
    Set whether the valve blocks until a permit is available.
    Parameters:
      `block` - `true` if the valve should block waiting for a permit

  - ### getInterruptible

    public boolean getInterruptible()
    Return whether the valve blocks interruptibly.
    Returns:
      `true` if the valve blocks interruptibly

  - ### setInterruptible

    public void setInterruptible(boolean interruptible)
    Set whether the valve blocks interruptibly.
    Parameters:
      `interruptible` - `true` if the valve should block interruptibly

  - ### getHighConcurrencyStatus

    public int getHighConcurrencyStatus()
    Return the HTTP status code returned when concurrency is too high.
    Returns:
      the status code, or -1 if no error is returned

  - ### setHighConcurrencyStatus

    public void setHighConcurrencyStatus(int highConcurrencyStatus)
    Set the HTTP status code returned when concurrency is too high.
    Parameters:
      `highConcurrencyStatus` - the status code to return

  - ### startInternal

    protected void startInternal() throws LifecycleException
    Start this component and implement the requirements of `LifecycleBase.startInternal()`.
    Overrides:
      `startInternal` in class `ValveBase`
    Throws:
      `LifecycleException` - if this component detects a fatal error that prevents this component from being used

  - ### stopInternal

    protected void stopInternal() throws LifecycleException
    Stop this component and implement the requirements of `LifecycleBase.stopInternal()`.
    Overrides:
      `stopInternal` in class `ValveBase`
    Throws:
      `LifecycleException` - if this component detects a fatal error that prevents this component from being used

  - ### invoke

    public void invoke(Request request, Response response) throws IOException, ServletException
    Do concurrency control on the request using the semaphore.
    Parameters:
      `request` - The servlet request to be processed
      `response` - The servlet response to be created
    Throws:
      `IOException` - if an input/output error occurs
      `ServletException` - if a servlet error occurs

  - ### controlConcurrency

    public boolean controlConcurrency(Request request, Response response)
    Subclass friendly method to add conditions.
    Parameters:
      `request` - The Servlet request
      `response` - The Servlet response
    Returns:
      `true` if the concurrency control should occur on this request

  - ### permitDenied

    public void permitDenied(Request request, Response response) throws IOException, ServletException
    Subclass friendly method to add error handling when a permit isn't granted.
    Parameters:
      `request` - The Servlet request
      `response` - The Servlet response
    Throws:
      `IOException` - Error writing output
      `ServletException` - Other error