RequestFilterValve (Apache Tomcat 7.0.109 API Documentation)

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()

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

Class RequestFilterValve

Nested Class Summary

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

Field Summary

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

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

Fields inherited from interface org.apache.catalina.Lifecycle

Constructor Summary

Method Summary

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

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

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

Methods inherited from class java.lang.Object

Field Detail

allow

allowValue

allowValid

deny

denyValue

denyValid

denyStatus

Constructor Detail

RequestFilterValve

Method Detail

getAllow

setAllow

getDeny

setDeny

isAllowValid

isDenyValid

getDenyStatus

setDenyStatus

getInfo

getInvalidAuthenticationWhenDeny

setInvalidAuthenticationWhenDeny

getAddConnectorPort

setAddConnectorPort

invoke

initInternal

startInternal

process

getLog

denyRequest

isAllowed