org.eclipse.jetty.servlets

## Class QoSFilter

- java.lang.Object
- - org.eclipse.jetty.servlets.QoSFilter

- All Implemented Interfaces:
    javax.servlet.Filter

      public class QoSFilter
      extends java.lang.Object
      implements javax.servlet.Filter

  Quality of Service Filter. This filter limits the number of active requests to the number set by the "maxRequests" init parameter (default 10). If more requests are received, they are suspended and placed on priority queues. Priorities are determined by the `getPriority(ServletRequest)` method and are a value between 0 and the value given by the "maxPriority" init parameter (default 10), with higher values having higher priority.

  This filter is ideal to prevent wasting threads waiting for slow/limited resources such as a JDBC connection pool. It avoids the situation where all of a containers thread pool may be consumed blocking on such a slow resource. By limiting the number of active threads, a smaller thread pool may be used as the threads are not wasted waiting. Thus more memory may be available for use by the active threads.

  Furthermore, this filter uses a priority when resuming waiting requests. So that if a container is under load, and there are many requests waiting for resources, the `getPriority(ServletRequest)` method is used, so that more important requests are serviced first. For example, this filter could be deployed with a maxRequest limit slightly smaller than the containers thread pool and a high priority allocated to admin users. Thus regardless of load, admin users would always be able to access the web application.

  The maxRequest limit is policed by a `Semaphore` and the filter will wait a short while attempting to acquire the semaphore. This wait is controlled by the "waitMs" init parameter and allows the expense of a suspend to be avoided if the semaphore is shortly available. If the semaphore cannot be obtained, the request will be suspended for the default suspend period of the container or the valued set as the "suspendMs" init parameter.

  If the "managedAttr" init parameter is set to true, then this servlet is set as a `ServletContext` attribute with the filter name as the attribute name. This allows context external mechanism (eg JMX via `ContextHandler.MANAGED_ATTRIBUTES`) to manage the configuration of the filter.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `_maxRequests`
    `protected long` | `_suspendMs`
    `protected long` | `_waitMs`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `QoSFilter()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()`
    `void` | `doFilter(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, javax.servlet.FilterChain chain)`
    `int` | `getMaxRequests()` Get the maximum number of requests allowed to be processed at the same time.
    `protected int` | `getPriority(javax.servlet.ServletRequest request)` Get the request Priority.
    `long` | `getSuspendMs()` Get the amount of time (in milliseconds) that the filter would suspend a request for while waiting for the semaphore to become available.
    `long` | `getWaitMs()` Get the (short) amount of time (in milliseconds) that the filter would wait for the semaphore to become available before suspending a request.
    `void` | `init(javax.servlet.FilterConfig filterConfig)`
    `void` | `setMaxRequests(int value)` Set the maximum number of requests allowed to be processed at the same time.
    `void` | `setSuspendMs(long value)` Set the amount of time (in milliseconds) that the filter would suspend a request for while waiting for the semaphore to become available.
    `void` | `setWaitMs(long value)` Set the (short) amount of time (in milliseconds) that the filter would wait for the semaphore to become available before suspending a request.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### _waitMs

          protected long _waitMs

    - #### _suspendMs

          protected long _suspendMs

    - #### _maxRequests

          protected int _maxRequests

  - ### Constructor Detail

    - #### QoSFilter

          public QoSFilter()

  - ### Method Detail

    - #### init

          public void init(javax.servlet.FilterConfig filterConfig)

      Specified by:
        `init` in interface `javax.servlet.Filter`
      See Also:
        `Filter.init(javax.servlet.FilterConfig)`

    - #### doFilter

          public void doFilter(javax.servlet.ServletRequest request,
                      javax.servlet.ServletResponse response,
                      javax.servlet.FilterChain chain)
                        throws java.io.IOException,
                               javax.servlet.ServletException

      Specified by:
        `doFilter` in interface `javax.servlet.Filter`
      Throws:
        `java.io.IOException`
        `javax.servlet.ServletException`
      See Also:
        `Filter.doFilter(javax.servlet.ServletRequest, javax.servlet.ServletResponse, javax.servlet.FilterChain)`

    - #### getPriority

          protected int getPriority(javax.servlet.ServletRequest request)

      Get the request Priority.

      The default implementation assigns the following priorities:

      - 2 - for a authenticated request
      - 1 - for a request with valid /non new session
      - 0 - for all other requests.
      This method may be specialised to provide application specific priorities.
      Parameters:
        `request` -
      Returns:
        the request priority

    - #### destroy

          public void destroy()

      Specified by:
        `destroy` in interface `javax.servlet.Filter`
      See Also:
        `Filter.destroy()`

    - #### getWaitMs

          public long getWaitMs()

      Get the (short) amount of time (in milliseconds) that the filter would wait for the semaphore to become available before suspending a request.
      Returns:
        wait time (in milliseconds)

    - #### setWaitMs

          public void setWaitMs(long value)

      Set the (short) amount of time (in milliseconds) that the filter would wait for the semaphore to become available before suspending a request.
      Parameters:
        `value` - wait time (in milliseconds)

    - #### getSuspendMs

          public long getSuspendMs()

      Get the amount of time (in milliseconds) that the filter would suspend a request for while waiting for the semaphore to become available.
      Returns:
        suspend time (in milliseconds)

    - #### setSuspendMs

          public void setSuspendMs(long value)

      Set the amount of time (in milliseconds) that the filter would suspend a request for while waiting for the semaphore to become available.
      Parameters:
        `value` - suspend time (in milliseconds)

    - #### getMaxRequests

          public int getMaxRequests()

      Get the maximum number of requests allowed to be processed at the same time.
      Returns:
        maximum number of requests

    - #### setMaxRequests

          public void setMaxRequests(int value)

      Set the maximum number of requests allowed to be processed at the same time.
      Parameters:
        `value` - the number of requests

Copyright © 2013 FuseSource, Corp.. All Rights Reserved.