com.isomorphic.servlet

## Class URIRegexFilter

- java.lang.Object
- - com.isomorphic.servlet.BaseFilter
  - - com.isomorphic.servlet.URIRegexFilter

-     public class URIRegexFilter
      extends BaseFilter

  Most servlet containers do not allow filter registration based on Regex rules. This filter rectifies the problem. To use, register the filter to intercept /* or whatever slice of the URI space you want and provide a rules file either in web.xml (see the doc for the `rules` init-param) or in a seprate file referenced in web.xml via the `rulesFile` init-param.

  Rules take the following form: :

  Where is one of: `block, ignore, match` and the regular expression is one that is acceptable to the Java Pattern class. Rules are evaluated in the order they appear, and the first match wins. If no rules match, the outcome is determined by the value of `defaultAction`. Once the action is determined, one of the following methods is called:

  - matchedRule() - default imlementation calls through to one of the next three methods. This signature provides access to the RegexRules object.
  - block() - default implementation logs an INFO level message about the URL being blocked, and returns HTTP code 404 to the client - effectively disallowing access.
  - match() - default implementation has empty body - you would typically override this to do whatever your filter needs to do.
  - ignore() - default implementation calls chain.doFilter() - effectively passing through the request to the next filter/servlet in the chain.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `java.lang.String` | `matchURI` Controls the URI string against which matchese are performed.
    `protected java.util.List` | `rules` You can specify the set of rules governing this filter as an init-param in web.xml.
    `java.lang.String` | `rulesFile` If specified, The filter uses the regex rules defined in this file.
    `int` | `uriCacheSize` Specifies the size of the URICache.
    `protected boolean` | `useURICache` This parameter controls whether the URICache is enabled or not.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `matchedRule(RegexRule rule, javax.servlet.ServletRequest req, javax.servlet.ServletResponse res, javax.servlet.FilterChain chain)` End user override point that provides the `RegexRule` object which allows you to inspect the action of the rule and the rule itself.

- - ### Field Detail

    - #### useURICache

          protected boolean useURICache

      This parameter controls whether the URICache is enabled or not.
      If this filter users regular expressions via the `rulesFile`, the URI Cache will cache the result of the application of relevant rules for any given URI. The URI Cache drastically speeds up subsequent rule applications at the cost of memory.

      Note: the cache is automatically disabled if there are no rules to apply (`rulesFile` is unset this typically means the user is managing the mappings through web.xml).

      Performance: The URI cache is an LRU Map. If you're using this filter on a large-scale site with a lot of unique URIs, you may want to tune its size via the `uriCacheSize` parameter to balance between memory usage and performance. Note that the memory usage problem can be exacerbated by crawlers if there are a log of directly-accessible unique URIs. Another thing you can do to help performance is reorder the regex rules in the config file to have the most-used/most-encompassing ones appear first to reduce the total number of regexes required per URI.

      See Also:
        `URIRegexFilter.uriCacheSize`

    - #### uriCacheSize

          public int uriCacheSize

      Specifies the size of the URICache. Note that each filter definition will have its own URICache.

    - #### matchURI

          public java.lang.String matchURI

      Controls the URI string against which matchese are performed. Valid values are "current" for the current requestURI and "initial" for the initial request URI. Default is "current".

    - #### rulesFile

          public java.lang.String rulesFile

      If specified, The filter uses the regex rules defined in this file. Alternatively you can use `rules` to specify the rules in web.xml.

      The format of the rulesFile is a list of regular expressions in a JSON array, like this:

           var rules = [
              "block:/bar/.*",
              "ignore:/foo/.*",
              "match:.*",
           ];

      Note: The rulesFile path is treated as relative to webRoot.
      See Also:
        `URIRegexFilter.rules`

    - #### rules

          protected java.util.List rules

      You can specify the set of rules governing this filter as an init-param in web.xml. The name of the param is `rules` and the value is a newline delimited list of rules. For example:

           <filter>
             <filter-name>CacheFilter</filter-name>
             <filter-class>com.isomorphic.servlet.CacheFilter</filter-class>
             <init-param>
                 <param-name>rules</param-name>
                 <param-value>
                     block:/foo
                     match:zoo/bar
                     ignore:/xxx
                 </param-value>
             </init-param>
           </filter>

      See Also:
        `URIRegexFilter.rulesFile`

  - ### Method Detail

    - #### matchedRule

          public void matchedRule(RegexRule rule,
                                  javax.servlet.ServletRequest req,
                                  javax.servlet.ServletResponse res,
                                  javax.servlet.FilterChain chain)
                           throws javax.servlet.ServletException,
                                  java.io.IOException

      End user override point that provides the `RegexRule` object which allows you to inspect the action of the rule and the rule itself.
      Throws:
        `javax.servlet.ServletException`
        `java.io.IOException`