From 2314de9dd9f9abbef360f5c6240487c0ac7e5fc3 Mon Sep 17 00:00:00 2001
From: Ceki Gulcu <ceki@qos.ch>
Date: Fri, 5 Aug 2022 22:46:46 +0200
Subject: [PATCH] add setMessage and log method to the fluent API

Signed-off-by: Ceki Gulcu <ceki@qos.ch>
---
 .../slf4j/spi/DefaultLoggingEventBuilder.java |  18 ++-
 .../org/slf4j/spi/LoggingEventBuilder.java    | 103 +++++++++++++++++-
 .../org/slf4j/spi/NOPLoggingEventBuilder.java |  34 ++++--
 3 files changed, 144 insertions(+), 11 deletions(-)

diff --git a/slf4j-api/src/main/java/org/slf4j/spi/DefaultLoggingEventBuilder.java b/slf4j-api/src/main/java/org/slf4j/spi/DefaultLoggingEventBuilder.java
index 884a73881..66652b070 100755
--- a/slf4j-api/src/main/java/org/slf4j/spi/DefaultLoggingEventBuilder.java
+++ b/slf4j-api/src/main/java/org/slf4j/spi/DefaultLoggingEventBuilder.java
@@ -86,7 +86,23 @@ public LoggingEventBuilder addArgument(Supplier<?> objectSupplier) {
     public void setCallerBoundary(String fqcn) {
         loggingEvent.setCallerBoundary(fqcn);
     }
-    
+
+    @Override
+    public void log() {
+        log(loggingEvent);
+    }
+
+    @Override
+    public LoggingEventBuilder setMessage(String message) {
+        loggingEvent.setMessage(message);
+        return this;
+    }
+    @Override
+    public LoggingEventBuilder setMessage(Supplier<String> messageSupplier) {
+        loggingEvent.setMessage(messageSupplier.get());
+        return this;
+    }
+
     @Override
     public void log(String message) {
         loggingEvent.setMessage(message);
diff --git a/slf4j-api/src/main/java/org/slf4j/spi/LoggingEventBuilder.java b/slf4j-api/src/main/java/org/slf4j/spi/LoggingEventBuilder.java
index fc42c1c1b..599dfcb48 100755
--- a/slf4j-api/src/main/java/org/slf4j/spi/LoggingEventBuilder.java
+++ b/slf4j-api/src/main/java/org/slf4j/spi/LoggingEventBuilder.java
@@ -29,34 +29,131 @@
 import org.slf4j.Marker;
 
 /**
- * This is main interface in slf4j's fluent API for creating logging events.
+ * This is the main interface in slf4j's fluent API for creating
+ * {@link org.slf4j.event.LoggingEvent logging events}.
  * 
  * @author Ceki G&uuml;lc&uuml;
  * @since 2.0.0
- *
  */
 public interface LoggingEventBuilder {
 
+    /**
+     * Set the cause for the logging event being built.
+     * @param cause a throwable
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     */
     LoggingEventBuilder setCause(Throwable cause);
 
+    /**
+     * A {@link Marker marker} to the event being built.
+     *
+     * @param marker a Marker instance to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     */
     LoggingEventBuilder addMarker(Marker marker);
 
+    /**
+     * Add an argument to the event being built.
+     *
+     * @param p an Object to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     */
     LoggingEventBuilder addArgument(Object p);
 
+    /**
+     * Add an argument supplier to the event being built.
+     *
+     * @param objectSupplier an Object supplier to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     */
     LoggingEventBuilder addArgument(Supplier<?> objectSupplier);
 
+
+    /**
+     * Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built.
+     *
+     * @param key the key of the key value pair.
+     * @param value the value of the key value pair.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     */
     LoggingEventBuilder addKeyValue(String key, Object value);
 
-    LoggingEventBuilder addKeyValue(String key, Supplier<Object> value);
+    /**
+     * Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built.
+     *
+     * @param key the key of the key value pair.
+     * @param valueSupplier a supplier of a value for the key value pair.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     */
+    LoggingEventBuilder addKeyValue(String key, Supplier<Object> valueSupplier);
+
+    /**
+     *  Sets the message of the logging event.
+     *
+     *  @since 2.0.0-beta0
+     */
+    LoggingEventBuilder setMessage(String message);
 
+    /**
+     * Sets the message of the event via a message supplier.
+     *
+     * @param messageSupplier supplies a String to be used as the message for the event
+     * @since 2.0.0-beta0
+     */
+    LoggingEventBuilder setMessage(Supplier<String> messageSupplier);
+
+    /**
+     * After the logging event is built, performs actual logging. This method must be called
+     * for logging to occur.
+     *
+     * If the call to {@link #log()}  is omitted, a {@link org.slf4j.event.LoggingEvent LoggingEvent}
+     * will be built but no logging will occur.
+     *
+     * @since 2.0.0-beta0
+     */
+    void log();
+
+    /**
+     * Equivalent to calling {@link #setMessage(String)} followed by {@link #log()};
+     *
+     * @param message the message to log
+     */
     void log(String message);
 
+    /**
+     * Equivalent to calling {@link #setMessage(String)} followed by {@link #addArgument(Object)}}
+     * and then {@link #log()}
+     *
+     * @param message the message to log
+     * @param arg an argument to be used with the message to log
+     */
     void log(String message, Object arg);
 
+    /**
+     * Equivalent to calling {@link #setMessage(String)} followed by two calls to
+     * {@link #addArgument(Object)} and then {@link #log()}
+     *
+     * @param message the message to log
+     * @param arg0 first argument to be used with the message to log
+     * @param arg1 second argument to be used with the message to log
+     */
     void log(String message, Object arg0, Object arg1);
 
+
+    /**
+     * Equivalent to calling {@link #setMessage(String)} followed by zero or more calls to
+     * {@link #addArgument(Object)} (depending on the size of args array) and then {@link #log()}
+     *
+     * @param message the message to log
+     * @param args a list (actually an array) of arguments to be used with the message to log
+     */
     void log(String message, Object... args);
 
+    /**
+     * Equivalent to calling {@link #setMessage(Supplier)} followed by {@link #log()}
+     *
+     * @param messageSupplier a Supplier returning a message of type String
+     */
     void log(Supplier<String> messageSupplier);
 
 }
diff --git a/slf4j-api/src/main/java/org/slf4j/spi/NOPLoggingEventBuilder.java b/slf4j-api/src/main/java/org/slf4j/spi/NOPLoggingEventBuilder.java
index 487f47ce4..e356b47fc 100755
--- a/slf4j-api/src/main/java/org/slf4j/spi/NOPLoggingEventBuilder.java
+++ b/slf4j-api/src/main/java/org/slf4j/spi/NOPLoggingEventBuilder.java
@@ -3,12 +3,15 @@
 import java.util.function.Supplier;
 
 import org.slf4j.Marker;
+import org.slf4j.event.Level;
 
 /**
- * A no-operation implementation of {@link LoggingEventBuilder}. 
- * As the name indicates, this implementation does nothing or alternatively returns
- * a singleton, i.e. the unique instance of this class.
- * 
+ * <p>A no-operation implementation of {@link LoggingEventBuilder}.</p>
+ *
+ * <p>As the name indicates, the method in this class do nothing, except when a return value is expected
+ * in which case a singleton, i.e. the unique instance of this class is returned.
+ * </p
+ *
  * @author Ceki G&uuml;lc&uuml;
  * @since 2.0.0
  *
@@ -17,10 +20,15 @@ public class NOPLoggingEventBuilder implements LoggingEventBuilder {
 
     static final NOPLoggingEventBuilder SINGLETON = new NOPLoggingEventBuilder();
 
-    
     private NOPLoggingEventBuilder() {
     }
-    
+
+    /**
+     * <p>Returns the singleton instance of this class.
+     * Used by {@link org.slf4j.Logger#makeLoggingEventBuilder(Level) makeLoggingEventBuilder(Level)}.</p>
+     *
+     * @return the singleton instance of this class
+     */
     public static LoggingEventBuilder singleton() {
         return SINGLETON;
     }
@@ -56,8 +64,20 @@ public LoggingEventBuilder setCause(Throwable cause) {
     }
 
     @Override
-    public void log(String message) {
+    public void log() {
+    }
+
+    @Override
+    public LoggingEventBuilder setMessage(String message) {
+        return this;
+    }
+    @Override
+    public LoggingEventBuilder setMessage(Supplier<String> messageSupplier) {
+        return this;
+    }
 
+    @Override
+    public void log(String message) {
     }
 
     @Override