refactor EventBuilder construction

qos-ch · Aug 10, 2021 · 5f45225 · 5f45225
1 parent efeb366
commit 5f45225
Show file tree

Hide file tree

Showing 2 changed files with 35 additions and 12 deletions.
diff --git a/slf4j-api/src/main/java/org/slf4j/Logger.java b/slf4j-api/src/main/java/org/slf4j/Logger.java
@@ -31,6 +31,7 @@
 import static org.slf4j.event.Level.TRACE;
 import static org.slf4j.event.Level.WARN;
 
+import org.slf4j.event.Level;
 import org.slf4j.spi.DefaultLoggingEventBuilder;
 import org.slf4j.spi.LoggingEventBuilder;
 import org.slf4j.spi.NOPLoggingEventBuilder;
@@ -62,7 +63,10 @@
  * }
  * </pre>
  *
- * Be sure to read the FAQ entry relating to <a href="../../../faq.html#logging_performance">parameterized
+ * <p>Note that version 2.0 of the SLF4J API introduces a <a href="../../../manual.html#fluent">fluent api</a>,
+ * the most significant API change to occur in the last 20 years.
+ *
+ * <p>Be sure to read the FAQ entry relating to <a href="../../../faq.html#logging_performance">parameterized
  * logging</a>. Note that logging statements can be parameterized in
  * <a href="../../../faq.html#paramException">presence of an exception/throwable</a>.
  *
@@ -86,6 +90,19 @@ public interface Logger {
      */
     public String getName();
 
+    /**
+     * Make a new {@link LoggingEventBuilder} instance as appropriate for this logger and the 
+     * desired {@link Level} passed as parameter. 
+     * 
+     * @param level desired level for the event builder
+     * @return a new {@link LoggingEventBuilder} instance as appropriate for this logger
+     * @since 2.0
+     */
+    default LoggingEventBuilder makeLoggingEventBuilder(Level level) {
+    	return new DefaultLoggingEventBuilder(this, level);
+    }
+
+
     /**
      * Is the logger instance enabled for the TRACE level?
      *
@@ -172,10 +189,11 @@ public interface Logger {
      * Entry point for fluent-logging for {@link org.slf4j.event.Level#TRACE} level. 
      *  
      * @return LoggingEventBuilder instance as appropriate for level TRACE
+     * @since 2.0
      */
     default public LoggingEventBuilder atTrace() {
     	if(isTraceEnabled()) {
-    		return new DefaultLoggingEventBuilder(this, TRACE);
+       		return makeLoggingEventBuilder(TRACE);
     	} else {
     		return NOPLoggingEventBuilder.singleton();
     	}
@@ -186,7 +204,7 @@ default public LoggingEventBuilder atTrace() {
      *
      * @param marker the marker data specific to this log statement
      * @param msg    the message string to be logged
-     * @since 1.4@
+     * @since 1.4
      */
     public void trace(Marker marker, String msg);
 
@@ -364,14 +382,16 @@ default public LoggingEventBuilder atTrace() {
     public void debug(Marker marker, String msg, Throwable t);
 
 
+
     /**
      * Entry point for fluent-logging for {@link org.slf4j.event.Level#DEBUG} level. 
      *  
      * @return LoggingEventBuilder instance as appropriate for level DEBUG
+     * @since 2.0
      */
     default public LoggingEventBuilder atDebug() {
     	if(isDebugEnabled()) {
-    		return new DefaultLoggingEventBuilder(this, DEBUG);
+    		return makeLoggingEventBuilder(DEBUG);
     	} else {
     		return NOPLoggingEventBuilder.singleton();
     	}
@@ -506,10 +526,11 @@ 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
+     * @since 2.0
      */
     default public LoggingEventBuilder atInfo() {
     	if(isInfoEnabled()) {
-    		return new DefaultLoggingEventBuilder(this, INFO);
+       		return makeLoggingEventBuilder(INFO);
     	} else {
     		return NOPLoggingEventBuilder.singleton();
     	}
@@ -647,10 +668,11 @@ 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
+     * @since 2.0
      */
     default public LoggingEventBuilder atWarn() {
     	if(isWarnEnabled()) {
-    		return new DefaultLoggingEventBuilder(this, WARN);
+       		return makeLoggingEventBuilder(WARN);
     	} else {
     		return NOPLoggingEventBuilder.singleton();
     	}
@@ -790,10 +812,11 @@ 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
+     * @since 2.0
      */
     default public LoggingEventBuilder atError() {
     	if(isErrorEnabled()) {
-    		return new DefaultLoggingEventBuilder(this, ERROR);
+       		return makeLoggingEventBuilder(ERROR);
     	} else {
     		return NOPLoggingEventBuilder.singleton();
     	}

diff --git a/slf4j-site/src/site/pages/manual.html b/slf4j-site/src/site/pages/manual.html
@@ -169,11 +169,11 @@ <h3 class="doAnchor" name="fluent">Fluent Logging API</h3>
       <code>atTrace()</code>, <code>atDebug()</code>,
       <code>atInfo()</code>, <code>atWarn()</code> and
       <code>atError()</code> methods new in the
-      <code>org.slf4j.Logger</code> interface return an instance of <a
-      href="apidocs/org/slf4j/spi/LoggingEventBuilder.html"><code>LoggingEventBuilder</code></a>. For
-      disabled log levels, the returned
-      <code>LoggingEventBuilder</code> instance does nothing, thus
-      preserving the nano-second level performance of the regular
+      <code>org.slf4j.Logger</code> interface return an instance of
+      <a href="apidocs/org/slf4j/spi/LoggingEventBuilder.html"><code>LoggingEventBuilder</code></a>.
+      For disabled log levels, the
+      returned <code>LoggingEventBuilder</code> instance does nothing,
+      thus preserving the nano-second level performance of the traditional
       logging interface.</p>