RequestFilterValve (Apache Tomcat 7.0.104 API Documentation)

org.apache.catalina.valves

## Class RequestFilterValve

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

- All Implemented Interfaces:
    MBeanRegistration, Contained, JmxEnabled, Lifecycle, Valve
  Direct Known Subclasses:
    RemoteAddrValve, RemoteHostValve

      public abstract class RequestFilterValve
      extends ValveBase

  Implementation of a Valve that performs filtering based on comparing the appropriate request property (selected based on which subclass you choose to configure into your Container's pipeline) against the regular expressions configured for this Valve.

  This valve is configured by setting the `allow` and/or `deny` properties to a regular expressions (in the syntax supported by `Pattern`) to which the appropriate request property will be compared. Evaluation proceeds as follows:

  - The subclass extracts the request property to be filtered, and calls the common `process()` method.
  - If there is a deny expression configured, the property will be compared to the expression. If a match is found, this request will be rejected with a "Forbidden" HTTP response.
  - If there is a allow expression configured, the property will be compared to each such expression. If a match is found, this request will be allowed to pass through to the next Valve in the current pipeline.
  - If a deny expression was specified but no allow expression, allow this request to pass through (because none of the deny expressions matched it).
  - The request will be rejected with a "Forbidden" HTTP response.

  As an option the valve can generate an invalid `authenticate` header instead of denying the request. This can be combined with the context attribute `preemptiveAuthentication="true"` and an authenticator to force authentication instead of denial.

  This Valve may be attached to any Container, depending on the granularity of the filtering you wish to perform.

  Author:
    Craig R. McClanahan

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

      `Lifecycle.SingleUse`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Pattern` | `allow` The regular expression used to test for allowed requests.
    `protected boolean` | `allowValid` Helper variable to catch configuration errors.
    `protected String` | `allowValue` The current allow configuration value that may or may not compile into a valid `Pattern`.
    `protected Pattern` | `deny` The regular expression used to test for denied requests.
    `protected int` | `denyStatus` The HTTP response status code that is used when rejecting denied request.
    `protected boolean` | `denyValid` Helper variable to catch configuration errors.
    `protected String` | `denyValue` The current deny configuration value that may or may not compile into a valid `Pattern`.

    - ### Fields inherited from class org.apache.catalina.valves.ValveBase

      `asyncSupported, container, containerLog, next, sm`

    - ### Fields inherited from class org.apache.catalina.util.LifecycleMBeanBase

      `mserver`

    - ### Fields inherited from interface org.apache.catalina.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 and Description
    `RequestFilterValve()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `denyRequest(Request request, Response response)` Reject the request that was denied by this valve.
    `boolean` | `getAddConnectorPort()` Get the flag deciding whether we add the server connector port to the property compared in the filtering method.
    `String` | `getAllow()` Return the regular expression used to test for allowed requests for this Valve, if any; otherwise, return `null`.
    `String` | `getDeny()` Return the regular expression used to test for denied requests for this Valve, if any; otherwise, return `null`.
    `int` | `getDenyStatus()` Return response status code that is used to reject denied request.
    `String` | `getInfo()` Return descriptive information about this Valve implementation.
    `boolean` | `getInvalidAuthenticationWhenDeny()` Return true if a deny is handled by setting an invalid auth header.
    `protected abstract Log` | `getLog()`
    `protected void` | `initInternal()` Sub-classes wishing to perform additional initialization should override this method, ensuring that super.initInternal() is the first call in the overriding method.
    `abstract void` | `invoke(Request request, Response response)` Extract the desired request property, and pass it (along with the specified request and response objects) to the protected `process()` method to perform the actual filtering.
    `boolean` | `isAllowed(String property)` Perform the test implemented by this Valve, matching against the specified request property value.
    `boolean` | `isAllowValid()` Returns `false` if the last change to the `allow` pattern did not apply successfully.
    `boolean` | `isDenyValid()` Returns `false` if the last change to the `deny` pattern did not apply successfully.
    `protected void` | `process(String property, Request request, Response response)` Perform the filtering that has been configured for this Valve, matching against the specified request property.
    `void` | `setAddConnectorPort(boolean addConnectorPort)` Set the flag deciding whether we add the server connector port to the property compared in the filtering method.
    `void` | `setAllow(String allow)` Set the regular expression used to test for allowed requests for this Valve, if any.
    `void` | `setDeny(String deny)` Set the regular expression used to test for denied requests for this Valve, if any.
    `void` | `setDenyStatus(int denyStatus)` Set response status code that is used to reject denied request.
    `void` | `setInvalidAuthenticationWhenDeny(boolean value)` Set invalidAuthenticationWhenDeny property.
    `protected void` | `startInternal()` Start this component and implement the requirements of `LifecycleBase.startInternal()`.

    - ### Methods inherited from class org.apache.catalina.valves.ValveBase

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

    - ### Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase

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

    - ### Methods inherited from class org.apache.catalina.util.LifecycleBase

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

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

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

- - ### Field Detail

    - #### allow

          protected volatile Pattern allow

      The regular expression used to test for allowed requests.

    - #### allowValue

          protected volatile String allowValue

      The current allow configuration value that may or may not compile into a valid `Pattern`.

    - #### allowValid

          protected volatile boolean allowValid

      Helper variable to catch configuration errors. It is `true` by default, but becomes `false` if there was an attempt to assign an invalid value to the `allow` pattern.

    - #### deny

          protected volatile Pattern deny

      The regular expression used to test for denied requests.

    - #### denyValue

          protected volatile String denyValue

      The current deny configuration value that may or may not compile into a valid `Pattern`.

    - #### denyValid

          protected volatile boolean denyValid

      Helper variable to catch configuration errors. It is `true` by default, but becomes `false` if there was an attempt to assign an invalid value to the `deny` pattern.

    - #### denyStatus

          protected int denyStatus

      The HTTP response status code that is used when rejecting denied request. It is 403 by default, but may be changed to be 404.

  - ### Constructor Detail

    - #### RequestFilterValve

          public RequestFilterValve()

  - ### Method Detail

    - #### getAllow

          public String getAllow()

      Return the regular expression used to test for allowed requests for this Valve, if any; otherwise, return `null`.

    - #### setAllow

          public void setAllow(String allow)

      Set the regular expression used to test for allowed requests for this Valve, if any.
      Parameters:
        `allow` - The new allow expression

    - #### getDeny

          public String getDeny()

      Return the regular expression used to test for denied requests for this Valve, if any; otherwise, return `null`.

    - #### setDeny

          public void setDeny(String deny)

      Set the regular expression used to test for denied requests for this Valve, if any.
      Parameters:
        `deny` - The new deny expression

    - #### isAllowValid

          public final boolean isAllowValid()

      Returns `false` if the last change to the `allow` pattern did not apply successfully. E.g. if the pattern is syntactically invalid.

    - #### isDenyValid

          public final boolean isDenyValid()

      Returns `false` if the last change to the `deny` pattern did not apply successfully. E.g. if the pattern is syntactically invalid.

    - #### getDenyStatus

          public int getDenyStatus()

      Return response status code that is used to reject denied request.

    - #### setDenyStatus

          public void setDenyStatus(int denyStatus)

      Set response status code that is used to reject denied request.

    - #### getInfo

          public String getInfo()

      Return descriptive information about this Valve implementation.
      Specified by:
        `getInfo` in interface `Valve`
      Overrides:
        `getInfo` in class `ValveBase`
      Returns:
        descriptive information about this Valve implementation.

    - #### getInvalidAuthenticationWhenDeny

          public boolean getInvalidAuthenticationWhenDeny()

      Return true if a deny is handled by setting an invalid auth header.

    - #### setInvalidAuthenticationWhenDeny

          public void setInvalidAuthenticationWhenDeny(boolean value)

      Set invalidAuthenticationWhenDeny property.

    - #### getAddConnectorPort

          public boolean getAddConnectorPort()

      Get the flag deciding whether we add the server connector port to the property compared in the filtering method. The port will be appended using a ";" as a separator.
      Returns:
        `true` to add the connector port

    - #### setAddConnectorPort

          public void setAddConnectorPort(boolean addConnectorPort)

      Set the flag deciding whether we add the server connector port to the property compared in the filtering method. The port will be appended using a ";" as a separator.
      Parameters:
        `addConnectorPort` - The new flag

    - #### invoke

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

      Extract the desired request property, and pass it (along with the specified request and response objects) to the protected `process()` method to perform the actual filtering. This method must be implemented by a concrete subclass.
      Specified by:
        `invoke` in interface `Valve`
      Specified by:
        `invoke` in class `ValveBase`
      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

    - #### initInternal

          protected void initInternal()
                               throws LifecycleException

      Description copied from class: `LifecycleMBeanBase`
      Sub-classes wishing to perform additional initialization should override this method, ensuring that super.initInternal() is the first call in the overriding method.
      Overrides:
        `initInternal` in class `ValveBase`
      Throws:
        `LifecycleException` - If the initialisation fails

    - #### startInternal

          protected void startInternal()
                                throws LifecycleException

      Description copied from class: `ValveBase`
      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

    - #### process

          protected void process(String property,
                     Request request,
                     Response response)
                          throws IOException,
                                 ServletException

      Perform the filtering that has been configured for this Valve, matching against the specified request property.
      Parameters:
        `property` - The request property on which to filter
        `request` - The servlet request to be processed
        `response` - The servlet response to be processed
      Throws:
        `IOException` - if an input/output error occurs
        `ServletException` - if a servlet error occurs

    - #### getLog

          protected abstract Log getLog()

    - #### denyRequest

          protected void denyRequest(Request request,
                         Response response)
                              throws IOException,
                                     ServletException

      Reject the request that was denied by this valve.

      If `invalidAuthenticationWhenDeny` is true and the context has `preemptiveAuthentication` set, set an invalid authorization header to trigger basic auth.

      Parameters:
        `request` - The servlet request to be processed
        `response` - The servlet response to be processed
      Throws:
        `IOException` - if an input/output error occurs
        `ServletException` - if a servlet error occurs

    - #### isAllowed

          public boolean isAllowed(String property)

      Perform the test implemented by this Valve, matching against the specified request property value. This method is public so that it can be called through JMX, e.g. to test whether certain IP address is allowed or denied by the valve configuration.
      Parameters:
        `property` - The request property value on which to filter

Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.