Fix `RegexFilter` pattern flags

[JWT007]

In the Log4j 2.x documentation for the RegexFilter:

https://logging.apache.org/log4j/2.x/manual/filters.html#RegexFilter

The only two configuration attributes are "regex" and "useRawMsg" (and the common filter attributes onMatch/onMismatch).

In the RegExFilter @pluginfactory there is a nested element for a set of Strings which is not mentioned in the documentation:

@PluginFactory
    public static RegexFilter createFilter(
            // @formatter:off
            @PluginAttribute("regex") final String regex,
            @PluginElement("PatternFlags") final String[] patternFlags,
            @PluginAttribute("useRawMsg") final Boolean useRawMsg,
            @PluginAttribute("onMatch") final Result match,
            @PluginAttribute("onMismatch") final Result mismatch)
            // @formatter:on
            throws IllegalArgumentException, IllegalAccessException {

If I understand correctly one can provide field names from the Pattern class here: (CASE_INSENSITIVE, COMMENTS, etc.).

The example in the Plugin Reference for the RegexFilter shows an example of nested strings but is not very clear with "a-String-implementation":

<RegexFilter onMatch=""
             onMismatch=""
             regex=""
             useRawMsg="">
    <a-String-implementation/><!-- multiple occurrences allowed -->
</RegexFilter>

Is it?:

<RegExFilter ...>
  <PatternFlags>CASE_INSENTIVE</PatternFlags>
  <PatternFlags>COMMENTS</PatternFlags>
</RegExFilter>

A usage example would be helpful.

Maybe this API is not really "public"? In the log4j-core-test RegexFilter test it seems the RegexFilter is never tested with anything but a null value for the patternFlags.

[ppkarwasz]

Hi @JWT007,

Thank you for helping us checking our documentation against the automatically-generated plugin reference. We created the plugin reference exactly for this purpose and we are happy you find it useful.

This is a longstanding LOG4J2-696 bug, old as Log4j 2 itself. The attempted solution has no chance to work, since the @PluginElement annotation only accepts classes annotated with @Plugin and String is final.

Since you can embed pattern flags in the regex (e.g. (?i) instead of CASE_SENSITIVE), I believe that we can just remove the annotation on the parameter.

[JWT007]

@ppkarwasz - added another new PR.

Please review if OK how I deprecated old pluginFactory and created new one.