Deprecate Message#getFormat()

Author: vy

log4j-api-test/src/test/java/org/apache/logging/log4j/AbstractLoggerTest.java

@@ -1446,11 +1446,6 @@ public String getFormattedMessage() {
             return null;
         }
 
-        @Override
-        public String getFormat() {
-            return null;
-        }
-
         @Override
         public Object[] getParameters() {
             return Constants.EMPTY_OBJECT_ARRAY;

log4j-api/src/main/java/org/apache/logging/log4j/message/Message.java

@@ -69,17 +69,15 @@ public interface Message extends Serializable {
     String getFormattedMessage();
 
     /**
-     * Gets the format portion of the Message.
+     * This method has unclear semantics and inconsistent implementations – its usage is strongly discouraged.
      *
-     * @return The message format. Some implementations, such as ParameterizedMessage, will use this as
-     * the message "pattern". Other Messages may simply return an empty String.
-     * TODO Do all messages have a format?  What syntax?  Using a Formatter object could be cleaner.
-     * (RG) In SimpleMessage the format is identical to the formatted message. In ParameterizedMessage and
-     * StructuredDataMessage it is not. It is up to the Message implementer to determine what this
-     * method will return. A Formatter is inappropriate as this is very specific to the Message
-     * implementation so it isn't clear to me how having a Formatter separate from the Message would be cleaner.
+     * @deprecated Deprecated since version {@code 2.24.0}.
+     * Use {@link MultiformatMessage} instead to implement messages that can format themselves in one or more encodings.
      */
-    String getFormat();
+    @Deprecated
+    default String getFormat() {
+        return null;
+    }
 
     /**
      * Gets parameter values, if any.

log4j-core-test/src/test/java/org/apache/logging/log4j/core/async/AsyncLoggerArgumentFreedOnErrorTest.java

@@ -83,11 +83,6 @@ public String getFormattedMessage() {
             throw new Error("Expected");
         }
 
-        @Override
-        public String getFormat() {
-            return Strings.EMPTY;
-        }
-
         @Override
         public Object[] getParameters() {
             return org.apache.logging.log4j.util.Constants.EMPTY_OBJECT_ARRAY;

log4j-core-test/src/test/java/org/apache/logging/log4j/core/async/AsyncLoggerConfigErrorOnFormat.java

@@ -83,11 +83,6 @@ public String getFormattedMessage() {
                     "getFormattedMessage invoked on " + Thread.currentThread().getName());
         }
 
-        @Override
-        public String getFormat() {
-            return null;
-        }
-
         @Override
         public Object[] getParameters() {
             return null;

log4j-core-test/src/test/java/org/apache/logging/log4j/core/async/QueueFullAsyncLogger3Test.java

@@ -93,11 +93,6 @@ public String getFormattedMessage() {
             return "formatted";
         }
 
-        @Override
-        public String getFormat() {
-            return null;
-        }
-
         @Override
         public Object[] getParameters() {
             return org.apache.logging.log4j.util.Constants.EMPTY_OBJECT_ARRAY;

log4j-core-test/src/test/java/org/apache/logging/log4j/core/lookup/JndiRestrictedLookupTest.java

@@ -25,7 +25,6 @@
 import javax.naming.Referenceable;
 import javax.naming.StringRefAddr;
 import org.apache.logging.log4j.message.Message;
-import org.apache.logging.log4j.util.Strings;
 import org.junit.BeforeClass;
 import org.junit.Rule;
 import org.junit.Test;
@@ -151,11 +150,6 @@ public String getFormattedMessage() {
             return message;
         }
 
-        @Override
-        public String getFormat() {
-            return Strings.EMPTY;
-        }
-
         @Override
         public Object[] getParameters() {
             return null;

log4j-layout-template-json-test/src/test/java/org/apache/logging/log4j/layout/template/json/resolver/MessageResolverTest.java

@@ -37,6 +37,7 @@
 import org.apache.logging.log4j.layout.template.json.JsonTemplateLayout;
 import org.apache.logging.log4j.layout.template.json.util.JsonReader;
 import org.apache.logging.log4j.message.Message;
+import org.apache.logging.log4j.message.MultiformatMessage;
 import org.apache.logging.log4j.message.ObjectMessage;
 import org.apache.logging.log4j.message.SimpleMessage;
 import org.apache.logging.log4j.message.StringMapMessage;
@@ -203,7 +204,7 @@ void test_MapMessage() {
     }
 
     @Test
-    void test_custom_Message() {
+    void test_MultiformatMessage() {
 
         // Create the event template
         final String eventTemplate = writeJson(asMap("$resolver", "message"));
@@ -216,7 +217,7 @@ void test_custom_Message() {
 
         // Create the log event with a `TestMessage`
         final LogEvent logEvent = Log4jLogEvent.newBuilder()
-                .setMessage(new TestMessage())
+                .setMessage(new TestMultiformatMessage())
                 .setTimeMillis(System.currentTimeMillis())
                 .build();
 
@@ -225,16 +226,24 @@ void test_custom_Message() {
                 .isEqualTo("bar"));
     }
 
-    private static final class TestMessage implements Message {
+    private static final class TestMultiformatMessage implements MultiformatMessage {
 
         @Override
         public String getFormattedMessage() {
             return "{\"foo\": \"bar\"}";
         }
 
         @Override
-        public String getFormat() {
-            return "JSON";
+        public String[] getFormats() {
+            return new String[] {"JSON"};
+        }
+
+        @Override
+        public String getFormattedMessage(final String[] formats) {
+            if (formats.length != 1 || !"JSON".equals(formats[0])) {
+                throw new UnsupportedOperationException();
+            }
+            return getFormattedMessage();
         }
 
         @Override

log4j-layout-template-json/src/main/java/org/apache/logging/log4j/layout/template/json/resolver/MessageResolver.java

@@ -137,22 +137,17 @@ private static void resolveString(final String fallbackKey, final Message messag
     private static EventResolver createObjectResolver(final String fallbackKey) {
         return (final LogEvent logEvent, final JsonWriter jsonWriter) -> {
 
-            // Skip custom serializers for `SimpleMessage`
+            // Skip custom serializers for SimpleMessage.
             final Message message = logEvent.getMessage();
             final boolean simple = message instanceof SimpleMessage;
             if (!simple) {
 
-                // Try `Message` serializer
-                if (writeMessage(jsonWriter, message)) {
-                    return;
-                }
-
-                // Try `MultiformatMessage` serializer
+                // Try MultiformatMessage serializer.
                 if (writeMultiformatMessage(jsonWriter, message)) {
                     return;
                 }
 
-                // Try `ObjectMessage` serializer
+                // Try ObjectMessage serializer.
                 if (writeObjectMessage(jsonWriter, message)) {
                     return;
                 }
@@ -163,20 +158,6 @@ private static EventResolver createObjectResolver(final String fallbackKey) {
         };
     }
 
-    private static boolean writeMessage(final JsonWriter jsonWriter, final Message message) {
-
-        // Check the format
-        final String format = message.getFormat();
-        if (!FORMATS[0].equalsIgnoreCase(format)) {
-            return false;
-        }
-
-        // Write the formatted message
-        final String messageJson = message.getFormattedMessage();
-        jsonWriter.writeRawString(messageJson);
-        return true;
-    }
-
     private static boolean writeMultiformatMessage(final JsonWriter jsonWriter, final Message message) {
 
         // Check type.

log4j-perf-test/src/main/java/org/apache/logging/log4j/perf/nogc/NoGcMessage.java

@@ -87,11 +87,6 @@ public String getFormattedMessage() {
         return getState().buffer.toString(); // not called by NoGcLayout
     }
 
-    @Override
-    public String getFormat() {
-        return null;
-    }
-
     @Override
     public Object[] getParameters() {
         return getState().getParamsCopy();

src/changelog/.2.x.x/fix-MessageResolver-getFormat-handling.xml renamed to src/changelog/.2.x.x/deprecate-Message-getFormat.xml

@@ -2,6 +2,6 @@
 <entry xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="https://logging.apache.org/xml/ns"
        xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-changelog-0.xsd"
-       type="fixed">
-  <description format="asciidoc">Fix handling of `Message#getFormat()` in `MessageResolver` of `JsonTemplateLayout`</description>
+       type="deprecated">
+  <description format="asciidoc">Deprecate `Message#getFormat()` due to unclear semantics and inconsistent implementations</description>
 </entry>