Package 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`, `RemoteCIDRValve`, `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
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 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
Description
`RequestFilterValve()`

## Method Summary

Modifier and Type
Method
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()`
`boolean`
`getInvalidAuthenticationWhenDeny()`
`protected abstract Log`
`getLog()`
`boolean`
`getUsePeerAddress()`
Get the flag deciding whether we use the connection peer address or the remote address.
`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.
`final boolean`
`isAllowValid()`
Returns `false` if the last change to the `allow` pattern did not apply successfully.
`final 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.
`void`
`setUsePeerAddress(boolean usePeerAddress)`
Set the flag deciding whether we use the connection peer address or the remote address.
`protected void`
`startInternal()`
Start this component and implement the requirements of `LifecycleBase.startInternal()`.

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

`backgroundProcess, 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, 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 Details

### 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 Details

### RequestFilterValve

public RequestFilterValve()

## Method Details

### getAllow

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

Returns:
  the regular expression

### 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`.

Returns:
  the regular expression

### 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.

Returns:
  `false` if the current pattern is 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.

Returns:
  `false` if the current pattern is invalid

### getDenyStatus

public int getDenyStatus()

Returns:
  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.

Parameters:
  `denyStatus` - The status code

### getInvalidAuthenticationWhenDeny

public boolean getInvalidAuthenticationWhenDeny()

Returns:
  `true` if a deny is handled by setting an invalid auth header.

### setInvalidAuthenticationWhenDeny

public void setInvalidAuthenticationWhenDeny(boolean value)
Set invalidAuthenticationWhenDeny property.

Parameters:
  `value` - `true` to handle a deny by setting an invalid auth header

### 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

### getUsePeerAddress

public boolean getUsePeerAddress()
Get the flag deciding whether we use the connection peer address or the remote address. This makes a dfifference when using AJP or the RemoteIpValve.

Returns:
  `true` if we use the connection peer address

### setUsePeerAddress

public void setUsePeerAddress(boolean usePeerAddress)
Set the flag deciding whether we use the connection peer address or the remote address. This makes a dfifference when using AJP or the RemoteIpValve.

Parameters:
  `usePeerAddress` - 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.

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
Returns:
  `true` if the request is allowed