RequestFilterValve (Tomcat API Documentation)
Keywords: org.apache.catalina.valves.RequestFilterValve class

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.catalina.valves
Class RequestFilterValve

    java.lang.Object
      org.apache.catalina.valves.ValveBase
          org.apache.catalina.valves.RequestFilterValve

All Implemented Interfaces:
  Contained, Lifecycle, javax.management.MBeanRegistration, Valve

Direct Known Subclasses:
  RemoteAddrValve, RemoteHostValve

public abstract class RequestFilterValve
extends ValveBase
implements Lifecycle

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 a set of regular expressions configured for this Valve.

This valve is configured by setting the `allow` and/or `deny` properties to a comma-delimited list of regular expressions (in the syntax supported by the jakarta-regexp library) 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 are any deny expressions configured, the property will be compared to each such expression. If a match is found, this request will be rejected with a "Forbidden" HTTP response.
- If there are any allow expressions 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 one or more deny expressions was specified but no allow expressions, allow this request to pass through (because none of the deny expressions matched it).
- The request will be rejected with a "Forbidden" HTTP response.

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

Version:
  $Id: RequestFilterValve.java 1221276 2011-12-20 14:25:24Z jim $
Author:
  Craig R. McClanahan

Field Summary
`protected java.lang.String` | `allow` The comma-delimited set of `allow` expressions.
`protected java.util.regex.Pattern[]` | `allows` The set of `allow` regular expressions we will evaluate.
`protected boolean` | `allowValid` Helper variable to catch configuration errors.
`protected java.util.regex.Pattern[]` | `denies` The set of `deny` regular expressions we will evaluate.
`protected java.lang.String` | `deny` The comma-delimited set of `deny` expressions.
`protected boolean` | `denyValid` Helper variable to catch configuration errors.
`protected LifecycleSupport` | `lifecycle` The lifecycle event support for this component.
`protected static StringManager` | `sm` The StringManager for this package.
`protected boolean` | `started` Has this component been started yet?

Fields inherited from class org.apache.catalina.valves.ValveBase
`container, containerLog, controller, domain, mserver, next, oname`

Fields inherited from interface org.apache.catalina.Lifecycle
`AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, DESTROY_EVENT, INIT_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT`

Constructor Summary
`RequestFilterValve()`

Method Summary
`void` | `addLifecycleListener(LifecycleListener listener)` Add a lifecycle event listener to this component.
`LifecycleListener[]` | `findLifecycleListeners()` Get the lifecycle listeners associated with this lifecycle.
`java.lang.String` | `getAllow()` Return a comma-delimited set of the `allow` expressions configured for this Valve, if any; otherwise, return `null`.
`java.lang.String` | `getDeny()` Return a comma-delimited set of the `deny` expressions configured for this Valve, if any; otherwise, return `null`.
`java.lang.String` | `getInfo()` Return descriptive information about this Valve implementation.
`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(java.lang.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 java.util.regex.Pattern[]` | `precalculate(java.lang.String list)` Return an array of regular expression objects initialized from the specified argument, which must be `null` or a comma-delimited list of regular expression patterns.
`protected void` | `process(java.lang.String property, Request request, Response response)` Perform the filtering that has been configured for this Valve, matching against the specified request property.
`void` | `removeLifecycleListener(LifecycleListener listener)` Remove a lifecycle event listener from this component.
`void` | `setAllow(java.lang.String allow)` Set the comma-delimited set of the `allow` expressions configured for this Valve, if any.
`void` | `setDeny(java.lang.String deny)` Set the comma-delimited set of the `deny` expressions configured for this Valve, if any.
`void` | `start()` Prepare for the beginning of active use of the public methods of this component.
`void` | `stop()` Gracefully terminate the active use of the public methods of this component.

Methods inherited from class org.apache.catalina.valves.ValveBase
`backgroundProcess, createObjectName, getContainer, getContainerName, getController, getDomain, getNext, getObjectName, getParentName, postDeregister, postRegister, preDeregister, preRegister, setContainer, setController, setNext, setObjectName, toString`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### sm

    protected static StringManager sm

  The StringManager for this package.

### allow

    protected volatile java.lang.String allow

  The comma-delimited set of `allow` expressions.

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

### allows

    protected volatile java.util.regex.Pattern[] allows

  The set of `allow` regular expressions we will evaluate.

### denies

    protected volatile java.util.regex.Pattern[] denies

  The set of `deny` regular expressions we will evaluate.

### deny

    protected volatile java.lang.String deny

  The comma-delimited set of `deny` expressions.

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

### lifecycle

    protected LifecycleSupport lifecycle

  The lifecycle event support for this component.

### started

    protected boolean started

  Has this component been started yet?

Constructor Detail

### RequestFilterValve

    public RequestFilterValve()

Method Detail

### getAllow

    public java.lang.String getAllow()

  Return a comma-delimited set of the `allow` expressions configured for this Valve, if any; otherwise, return `null`.

### setAllow

    public void setAllow(java.lang.String allow)

  Set the comma-delimited set of the `allow` expressions configured for this Valve, if any.

  Parameters:
    `allow` - The new set of allow expressions

### getDeny

    public java.lang.String getDeny()

  Return a comma-delimited set of the `deny` expressions configured for this Valve, if any; otherwise, return `null`.

### setDeny

    public void setDeny(java.lang.String deny)

  Set the comma-delimited set of the `deny` expressions configured for this Valve, if any.

  Parameters:
    `deny` - The new set of deny expressions

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

### getInfo

    public java.lang.String getInfo()

  Return descriptive information about this Valve implementation.

  Specified by:
    `getInfo` in interface `Valve`
  Overrides:
    `getInfo` in class `ValveBase`

### invoke

    public abstract void invoke(Request request,
                                Response response)
                         throws java.io.IOException,
                                javax.servlet.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:
    `java.io.IOException` - if an input/output error occurs
    `javax.servlet.ServletException` - if a servlet error occurs

### precalculate

    protected java.util.regex.Pattern[] precalculate(java.lang.String list)

  Return an array of regular expression objects initialized from the specified argument, which must be `null` or a comma-delimited list of regular expression patterns.

  Parameters:
    `list` - The comma-separated list of patterns
  Throws:
    `java.lang.IllegalArgumentException` - if one of the patterns has invalid syntax

### process

    protected void process(java.lang.String property,
                           Request request,
                           Response response)
                    throws java.io.IOException,
                           javax.servlet.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:
    `java.io.IOException` - if an input/output error occurs
    `javax.servlet.ServletException` - if a servlet error occurs

### isAllowed

    public boolean isAllowed(java.lang.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

### addLifecycleListener

    public void addLifecycleListener(LifecycleListener listener)

  Add a lifecycle event listener to this component.

  Specified by:
    `addLifecycleListener` in interface `Lifecycle`
  Parameters:
    `listener` - The listener to add

### findLifecycleListeners

    public LifecycleListener[] findLifecycleListeners()

  Get the lifecycle listeners associated with this lifecycle. If this Lifecycle has no listeners registered, a zero-length array is returned.

  Specified by:
    `findLifecycleListeners` in interface `Lifecycle`

### removeLifecycleListener

    public void removeLifecycleListener(LifecycleListener listener)

  Remove a lifecycle event listener from this component.

  Specified by:
    `removeLifecycleListener` in interface `Lifecycle`
  Parameters:
    `listener` - The listener to add

### start

    public void start()
               throws LifecycleException

  Prepare for the beginning of active use of the public methods of this component. This method should be called after `configure()`, and before any of the public methods of the component are utilized.

  Specified by:
    `start` in interface `Lifecycle`
  Throws:
    `LifecycleException` - if this component detects a fatal error that prevents this component from being used

### stop

    public void stop()
              throws LifecycleException

  Gracefully terminate the active use of the public methods of this component. This method should be the last one called on a given instance of this component.

  Specified by:
    `stop` in interface `Lifecycle`
  Throws:
    `LifecycleException` - if this component detects a fatal error that needs to be reported

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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