SLF4J-256: Allow use of lambda to construct build event

- Rename current LoggingEventBuilder to FluentApiStub to better describe its responsibility
- New interface of LoggingEventBuilder to act only as Fluent Builder of LoggingEvent, which is
  used by the lambda

Author: adrianshum

slf4j-api/src/main/java/org/slf4j/Logger.java

@@ -38,9 +38,12 @@
 
 import org.slf4j.event.Level;
 import org.slf4j.spi.DefaultLoggingEventBuilder;
+import org.slf4j.spi.FluentLogApiStub;
 import org.slf4j.spi.LoggingEventBuilder;
 import org.slf4j.spi.NOPLoggingEventBuilder;
 
+import java.util.function.Consumer;
+
 /**
  * The org.slf4j.Logger interface is the main user entry point of SLF4J API.
  * It is expected that logging takes place through concrete implementations
@@ -96,7 +99,7 @@ public interface Logger {
     public String getName();
 
     /**
-     * Make a new {@link LoggingEventBuilder} instance as appropriate for this logger and the 
+     * Make a new {@link FluentLogApiStub} instance as appropriate for this logger and the
      * desired {@link Level} passed as parameter. If this Logger is disabled for the given Level, then 
      * a {@link  NOPLoggingEventBuilder} is returned.
      * 
@@ -105,21 +108,34 @@ public interface Logger {
      * @return a new {@link LoggingEventBuilder} instance as appropriate for this logger
      * @since 2.0
      */
-    default public LoggingEventBuilder makeLoggingEventBuilder(Level level) {
+    default public FluentLogApiStub makeLoggingEventBuilder(Level level) {
         if (isEnabledForLevel(level)) {
             return new DefaultLoggingEventBuilder(this, level);          
         } else {
             return NOPLoggingEventBuilder.singleton();
         }
     }
 
+    default public FluentLogApiStub atLevel(Level level) {
+        return makeLoggingEventBuilder(level);
+    }
+
+
     /**
-     * A convenient alias for {@link #makeLoggingEventBuilder}. 
-     * 
+     * Use provided LoggingEventBuilder consumer to construct the logging event, and log at provided level.
+     *
+     * <code>
+     *     logger.atDebug(log->log.message("Temperature rise from {} to {}")
+     * </code>
+     *
      * @since 2.0
      */
-    default public LoggingEventBuilder atLevel(Level level) {
-        return makeLoggingEventBuilder(level);
+    default public void atLevel(Level level, Consumer<LoggingEventBuilder> eventBuilderConsumer) {
+        if (isEnabledForLevel(level)) {
+            DefaultLoggingEventBuilder eventBuilder= new DefaultLoggingEventBuilder(this, level);
+            eventBuilderConsumer.accept(eventBuilder);
+            eventBuilder.log();
+        }
     }
 
 
@@ -233,16 +249,19 @@ default public boolean isEnabledForLevel(Level level) {
     /**
      * Entry point for fluent-logging for {@link org.slf4j.event.Level#TRACE} level. 
      *  
-     * @return LoggingEventBuilder instance as appropriate for level TRACE
+     * @return FluentLogApiStub instance as appropriate for level TRACE
      * @since 2.0
      */
-    default public LoggingEventBuilder atTrace() {
+    default public FluentLogApiStub atTrace() {
         if (isTraceEnabled()) {
             return makeLoggingEventBuilder(TRACE);
         } else {
             return NOPLoggingEventBuilder.singleton();
         }
     }
+    default public void atTrace(Consumer<LoggingEventBuilder> eventBuilderConsumer) {
+        this.atLevel(TRACE, eventBuilderConsumer);
+    }
 
     /**
      * Log a message with the specific Marker at the TRACE level.
@@ -429,17 +448,21 @@ default public LoggingEventBuilder atTrace() {
     /**
      * Entry point for fluent-logging for {@link org.slf4j.event.Level#DEBUG} level. 
      *  
-     * @return LoggingEventBuilder instance as appropriate for level DEBUG
+     * @return FluentLogApiStub instance as appropriate for level DEBUG
      * @since 2.0
      */
-    default public LoggingEventBuilder atDebug() {
+    default public FluentLogApiStub atDebug() {
         if (isDebugEnabled()) {
             return makeLoggingEventBuilder(DEBUG);
         } else {
             return NOPLoggingEventBuilder.singleton();
         }
     }
 
+    default public void atDebug(Consumer<LoggingEventBuilder> eventBuilderConsumer) {
+        this.atLevel(DEBUG, eventBuilderConsumer);
+    }
+
     /**
      * Is the logger instance enabled for the INFO level?
      *
@@ -568,16 +591,19 @@ default public LoggingEventBuilder atDebug() {
     /**
      * Entry point for fluent-logging for {@link org.slf4j.event.Level#INFO} level. 
      *  
-     * @return LoggingEventBuilder instance as appropriate for level INFO
+     * @return FluentLogApiStub instance as appropriate for level INFO
      * @since 2.0
      */
-    default public LoggingEventBuilder atInfo() {
+    default public FluentLogApiStub atInfo() {
         if (isInfoEnabled()) {
             return makeLoggingEventBuilder(INFO);
         } else {
             return NOPLoggingEventBuilder.singleton();
         }
     }
+    default public void atInfo(Consumer<LoggingEventBuilder> eventBuilderConsumer) {
+        this.atLevel(INFO, eventBuilderConsumer);
+    }
 
     /**
      * Is the logger instance enabled for the WARN level?
@@ -708,16 +734,19 @@ default public LoggingEventBuilder atInfo() {
     /**
      * Entry point for fluent-logging for {@link org.slf4j.event.Level#WARN} level. 
      *  
-     * @return LoggingEventBuilder instance as appropriate for level WARN
+     * @return FluentLogApiStub instance as appropriate for level WARN
      * @since 2.0
      */
-    default public LoggingEventBuilder atWarn() {
+    default public FluentLogApiStub atWarn() {
         if (isWarnEnabled()) {
             return makeLoggingEventBuilder(WARN);
         } else {
             return NOPLoggingEventBuilder.singleton();
         }
     }
+    default public void atWarn(Consumer<LoggingEventBuilder> eventBuilderConsumer) {
+        this.atLevel(WARN, eventBuilderConsumer);
+    }
 
     /**
      * Is the logger instance enabled for the ERROR level?
@@ -849,15 +878,21 @@ default public LoggingEventBuilder atWarn() {
     /**
      * Entry point for fluent-logging for {@link org.slf4j.event.Level#ERROR} level. 
      *  
-     * @return LoggingEventBuilder instance as appropriate for level ERROR
+     * @return FluentLogApiStub instance as appropriate for level ERROR
      * @since 2.0
      */
-    default public LoggingEventBuilder atError() {
+    default public FluentLogApiStub atError() {
         if (isErrorEnabled()) {
             return makeLoggingEventBuilder(ERROR);
         } else {
             return NOPLoggingEventBuilder.singleton();
         }
     }
 
+    default public void atError(Consumer<LoggingEventBuilder> eventBuilderConsumer) {
+        this.atLevel(ERROR, eventBuilderConsumer);
+    }
+
+
+
 }

slf4j-api/src/main/java/org/slf4j/helpers/SubstituteLogger.java

@@ -27,13 +27,15 @@
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 import java.util.Queue;
+import java.util.function.Consumer;
 
 import org.slf4j.Logger;
 import org.slf4j.Marker;
 import org.slf4j.event.EventRecodingLogger;
 import org.slf4j.event.Level;
 import org.slf4j.event.LoggingEvent;
 import org.slf4j.event.SubstituteLoggingEvent;
+import org.slf4j.spi.FluentLogApiStub;
 import org.slf4j.spi.LoggingEventBuilder;
 
 /**
@@ -69,15 +71,21 @@ public String getName() {
     }
 
     @Override
-    public LoggingEventBuilder makeLoggingEventBuilder(Level level) {
+    public FluentLogApiStub makeLoggingEventBuilder(Level level) {
         return delegate().makeLoggingEventBuilder(level);
     }
 
     @Override
-    public LoggingEventBuilder atLevel(Level level) {
+    public FluentLogApiStub atLevel(Level level) {
         return delegate().atLevel(level); 
     }
-    
+
+    @Override
+    public void atLevel(Level level, Consumer<LoggingEventBuilder> eventBuilderConsumer) {
+        delegate().atLevel(level, eventBuilderConsumer);
+    }
+
+
     @Override
     public boolean isEnabledForLevel(Level level) {
         return delegate().isEnabledForLevel(level);
@@ -142,10 +150,15 @@ public void trace(Marker marker, String msg, Throwable t) {
     }
 
     @Override
-    public LoggingEventBuilder atTrace() {
+    public FluentLogApiStub atTrace() {
         return delegate().atTrace();
     }
-    
+
+    @Override
+    public void atTrace(Consumer<LoggingEventBuilder> eventBuilderConsumer) {
+        delegate().atTrace(eventBuilderConsumer);
+    }
+
     @Override
     public boolean isDebugEnabled() {
         return delegate().isDebugEnabled();
@@ -207,10 +220,15 @@ public void debug(Marker marker, String msg, Throwable t) {
     }
 
     @Override
-    public LoggingEventBuilder atDebug() {
+    public FluentLogApiStub atDebug() {
         return delegate().atDebug();
     }
-    
+
+    @Override
+    public void atDebug(Consumer<LoggingEventBuilder> eventBuilderConsumer) {
+        delegate().atDebug(eventBuilderConsumer);
+    }
+
     @Override
     public boolean isInfoEnabled() {
         return delegate().isInfoEnabled();
@@ -273,11 +291,15 @@ public void info(Marker marker, String msg, Throwable t) {
     }
 
     @Override
-    public LoggingEventBuilder atInfo() {
+    public FluentLogApiStub atInfo() {
         return delegate().atInfo();
     }
 
-    
+    @Override
+    public void atInfo(Consumer<LoggingEventBuilder> eventBuilderConsumer) {
+        delegate().atInfo(eventBuilderConsumer);
+    }
+
     @Override
     public boolean isWarnEnabled() {
         return delegate().isWarnEnabled();
@@ -338,11 +360,15 @@ public void warn(Marker marker, String msg, Throwable t) {
     }
 
     @Override
-    public LoggingEventBuilder atWarn() {
+    public FluentLogApiStub atWarn() {
         return delegate().atWarn();
     }
 
-    
+    @Override
+    public void atWarn(Consumer<LoggingEventBuilder> eventBuilderConsumer) {
+        delegate().atWarn(eventBuilderConsumer);
+    }
+
 
     @Override
     public boolean isErrorEnabled() {
@@ -405,10 +431,15 @@ public void error(Marker marker, String msg, Throwable t) {
     }
 
     @Override
-    public LoggingEventBuilder atError() {
+    public FluentLogApiStub atError() {
         return delegate().atError();
     }
-    
+
+    @Override
+    public void atError(Consumer<LoggingEventBuilder> eventBuilderConsumer) {
+        delegate().atError(eventBuilderConsumer);
+    }
+
     @Override
     public boolean equals(Object o) {
         if (this == o)

slf4j-api/src/main/java/org/slf4j/spi/DefaultLoggingEventBuilder.java

@@ -9,7 +9,7 @@
 import org.slf4j.event.Level;
 import org.slf4j.event.LoggingEvent;
 
-public class DefaultLoggingEventBuilder implements LoggingEventBuilder, CallerBoundaryAware {
+public class DefaultLoggingEventBuilder implements FluentLogApiStub, LoggingEventBuilder, CallerBoundaryAware {
 
     protected DefaultLoggingEvent loggingEvent;
     protected Logger logger;
@@ -19,6 +19,12 @@ public DefaultLoggingEventBuilder(Logger logger, Level level) {
         loggingEvent = new DefaultLoggingEvent(level, logger);
     }
 
+    @Override
+    public DefaultLoggingEventBuilder setMessage(String message) {
+        loggingEvent.setMessage(message);
+        return this;
+    }
+
     /**
      * Add a marker to the current logging event being built.
      * 
@@ -27,25 +33,25 @@ public DefaultLoggingEventBuilder(Logger logger, Level level) {
      * @param marker the marker to add
      */
     @Override
-    public LoggingEventBuilder addMarker(Marker marker) {
+    public DefaultLoggingEventBuilder addMarker(Marker marker) {
         loggingEvent.addMarker(marker);
         return this;
     }
 
     @Override
-    public LoggingEventBuilder setCause(Throwable t) {
+    public DefaultLoggingEventBuilder setCause(Throwable t) {
         loggingEvent.setThrowable(t);
         return this;
     }
 
     @Override
-    public LoggingEventBuilder addArgument(Object p) {
+    public DefaultLoggingEventBuilder addArgument(Object p) {
         loggingEvent.addArgument(p);
         return this;
     }
 
     @Override
-    public LoggingEventBuilder addArgument(Supplier<?> objectSupplier) {
+    public DefaultLoggingEventBuilder addArgument(Supplier<?> objectSupplier) {
         loggingEvent.addArgument(objectSupplier.get());
         return this;
     }
@@ -92,7 +98,11 @@ public void log(Supplier<String> messageSupplier) {
             log(messageSupplier.get());
         }
     }
-    
+
+    public void log() {
+        log(loggingEvent);
+    }
+
     protected void log(LoggingEvent aLoggingEvent) {
         if (logger instanceof LoggingEventAware) {
             ((LoggingEventAware) logger).log(aLoggingEvent);
@@ -183,13 +193,13 @@ private String mergeMarkersAndKeyValuePairs(LoggingEvent aLoggingEvent, String m
 
 
     @Override
-    public LoggingEventBuilder addKeyValue(String key, Object value) {
+    public DefaultLoggingEventBuilder addKeyValue(String key, Object value) {
         loggingEvent.addKeyValue(key, value);
         return this;
     }
 
     @Override
-    public LoggingEventBuilder addKeyValue(String key, Supplier<Object> value) {
+    public DefaultLoggingEventBuilder addKeyValue(String key, Supplier<Object> value) {
         loggingEvent.addKeyValue(key, value.get());
         return this;
     }