Improve getFormat() usage in RegexFilter

Author: vy

log4j-core/src/main/java/org/apache/logging/log4j/core/filter/RegexFilter.java

@@ -32,14 +32,13 @@
 import org.apache.logging.log4j.core.config.plugins.PluginElement;
 import org.apache.logging.log4j.core.config.plugins.PluginFactory;
 import org.apache.logging.log4j.message.Message;
+import org.apache.logging.log4j.message.MessageFormatMessage;
 import org.apache.logging.log4j.message.ParameterizedMessage;
+import org.apache.logging.log4j.message.StringFormattedMessage;
+import org.apache.logging.log4j.message.StructuredDataMessage;
 
 /**
- * This filter returns the onMatch result if the message matches the regular expression.
- *
- * The "useRawMsg" attribute can be used to indicate whether the regular expression should be applied to the result of
- * calling Message.getMessageFormat (true) or Message.getFormattedMessage() (false). The default is false.
- *
+ * A filter that matches the given regular expression pattern against messages.
  */
 @Plugin(name = "RegexFilter", category = Node.CATEGORY, elementType = Filter.ELEMENT_TYPE, printObject = true)
 public final class RegexFilter extends AbstractFilter {
@@ -78,18 +77,29 @@ public Result filter(
         if (msg == null) {
             return onMismatch;
         }
-        final String text = useRawMessage ? msg.getFormat() : msg.getFormattedMessage();
+        final String text = targetMessageTest(msg);
         return filter(text);
     }
 
     @Override
     public Result filter(final LogEvent event) {
-        final String text = useRawMessage
-                ? event.getMessage().getFormat()
-                : event.getMessage().getFormattedMessage();
+        final String text = targetMessageTest(event.getMessage());
         return filter(text);
     }
 
+    // While `Message#getFormat()` is broken in general, it still makes sense for certain types.
+    // Hence, suppress the deprecation warning.
+    @SuppressWarnings("deprecation")
+    private String targetMessageTest(final Message message) {
+        return useRawMessage
+                        && (message instanceof ParameterizedMessage
+                                || message instanceof StringFormattedMessage
+                                || message instanceof MessageFormatMessage
+                                || message instanceof StructuredDataMessage)
+                ? message.getFormat()
+                : message.getFormattedMessage();
+    }
+
     private Result filter(final String msg) {
         if (msg == null) {
             return onMismatch;
@@ -114,7 +124,7 @@ public String toString() {
      * @param patternFlags
      *        An array of Strings where each String is a {@link Pattern#compile(String, int)} compilation flag.
      * @param useRawMsg
-     *        If true, the raw message will be used, otherwise the formatted message will be used.
+     *        If {@code true}, for {@link ParameterizedMessage}, {@link StringFormattedMessage}, and {@link MessageFormatMessage}, the message format pattern; for {@link StructuredDataMessage}, the message field will be used as the match target.
      * @param match
      *        The action to perform when a match occurs.
      * @param mismatch

src/site/antora/modules/ROOT/pages/manual/filters.adoc

@@ -746,19 +746,16 @@ include::partial$manual/log-event.adoc[]
 [#RegexFilter]
 ==== `RegexFilter`
 
-The `RegexFilter` matches a regular expression against either the result of
-link:../javadoc/log4j-api/org/apache/logging/log4j/message/Message.html#getFormat()[`Message.getFormat()`]
-or
-link:../javadoc/log4j-api/org/apache/logging/log4j/message/Message.html#getFormat()[`Message.getFormattedMessage()`].
-It can be used with all kinds of `Message` implementations.
-
-Besides the <<common-configuration-attributes,common configuration attributes>>,
-the `RegexFilter` supports the following parameters:
+The `RegexFilter` matches a regular expression against messages.
+Besides the <<common-configuration-attributes,common configuration attributes>>, the `RegexFilter` supports the following parameters:
 
-.`RegexFilter` -- configuration attributes
-[cols="1m,1,1,4"]
+.`RegexFilter` configuration attributes
+[%header,cols="1m,1,1,4"]
 |===
-|Attribute | Type | Default value | Description
+|Attribute
+| Type
+| Default value
+| Description
 
 | regex
 | https://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/regex/Pattern.html[`Pattern`]
@@ -770,13 +767,7 @@ the `RegexFilter` supports the following parameters:
 | useRawMsg
 | `boolean`
 | `false`
-| If `true` the result of
-link:../javadoc/log4j-api/org/apache/logging/log4j/message/Message.html#getFormat()[`Message.getFormat()`]
-will be used.
-Otherwise,
-link:../javadoc/log4j-api/org/apache/logging/log4j/message/Message.html#getFormat()[`Message.getFormattedMessage()`]
-is used.
-
+| If `true`, for xref:manual/messages.adoc#ParameterizedMessage[`ParameterizedMessage`], xref:manual/messages.adoc#StringFormattedMessage[`StringFormattedMessage`], and xref:manual/messages.adoc#MessageFormatMessage[`MessageFormatMessage`], the message format pattern; for xref:manual/messages.adoc#StructuredDataMessage[`StructuredDataMessage`], the message field will be used as the match target.
 |===
 
 [WARNING]