issues/375 add arg(primitiveType) methods in LoggingEventBuilder inte…

…rface

Signed-off-by: Ceki Gulcu <[email protected]>

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

@@ -116,9 +116,9 @@ default public LoggingEventBuilder makeLoggingEventBuilder(Level level) {
     }
 
     /**
-     * Make a new {@link LoggingEventBuilder} instance as appropriate for this logger and the
+     * <p>Make a new {@link LoggingEventBuilder} 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.
+     * a {@link  NOPLoggingEventBuilder} is returned.  This is the main optimization in the fluent API.</p>
      *
      *
      * @param level desired level for the event builder
@@ -243,8 +243,11 @@ default public boolean isEnabledForLevel(Level level) {
     public boolean isTraceEnabled(Marker marker);
 
     /**
-     * Entry point for fluent-logging for {@link org.slf4j.event.Level#TRACE} level. 
-     *  
+     * Entry point for fluent-logging for {@link org.slf4j.event.Level#TRACE} level.
+     *
+     * <p>If this logger is disabled for the TRACE level, then a {@link NOPLoggingEventBuilder} instance is returned.
+     * As the name indicates, this builder does not perform any operations. This is the main optimization in the fluent API.</p>
+     *
      * @return LoggingEventBuilder instance as appropriate for level TRACE
      * @since 2.0
      */
@@ -441,7 +444,10 @@ default public LoggingEventBuilder atTrace() {
 
     /**
      * Entry point for fluent-logging for {@link org.slf4j.event.Level#DEBUG} level. 
-     *  
+     *
+     * <p>If this logger is disabled for the DEBUG level, then a {@link NOPLoggingEventBuilder} instance is returned.
+     * As the name indicates, this builder does not perform any operations. This is the main optimization in the fluent API.</p>
+     *
      * @return LoggingEventBuilder instance as appropriate for level DEBUG
      * @since 2.0
      */
@@ -582,7 +588,10 @@ default public LoggingEventBuilder atDebug() {
 
     /**
      * Entry point for fluent-logging for {@link org.slf4j.event.Level#INFO} level. 
-     *  
+     *
+     * <p>If this logger is disabled for the INFO level, then a {@link NOPLoggingEventBuilder} instance is returned.
+     * As the name indicates, this builder does not perform any operations.  This is the main optimization in the fluent API.</p>
+
      * @return LoggingEventBuilder instance as appropriate for level INFO
      * @since 2.0
      */
@@ -723,7 +732,10 @@ default public LoggingEventBuilder atInfo() {
 
     /**
      * Entry point for fluent-logging for {@link org.slf4j.event.Level#WARN} level. 
-     *  
+     *
+     * <p>If this logger is disabled for the WARN level, then a {@link NOPLoggingEventBuilder} instance is returned.
+     * As the name indicates, this builder does not perform any operations.  This is the main optimization in the fluent API.</p>
+     *
      * @return LoggingEventBuilder instance as appropriate for level WARN
      * @since 2.0
      */
@@ -865,7 +877,10 @@ default public LoggingEventBuilder atWarn() {
 
     /**
      * Entry point for fluent-logging for {@link org.slf4j.event.Level#ERROR} level. 
-     *  
+     *
+     * <p>If this logger is disabled for the ERROR level, then a {@link NOPLoggingEventBuilder} instance is returned.
+     * As the name indicates, this builder does not perform any operations.</p>
+     *
      * @return LoggingEventBuilder instance as appropriate for level ERROR
      * @since 2.0
      */

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

@@ -34,7 +34,11 @@
 import org.slf4j.event.LoggingEvent;
 
 /**
- * Default implementation of {@link LoggingEventBuilder}
+ * Default implementation of {@link LoggingEventBuilder}.
+ *
+ * <p>It is assumed that when </p>
+ *
+ * @since 2.0.0
  */
 public class DefaultLoggingEventBuilder implements LoggingEventBuilder, CallerBoundaryAware {
 
@@ -76,6 +80,7 @@ public LoggingEventBuilder addArgument(Object p) {
         return this;
     }
 
+
     @Override
     public LoggingEventBuilder addArgument(Supplier<?> objectSupplier) {
         loggingEvent.addArgument(objectSupplier.get());

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

@@ -58,6 +58,7 @@ public interface LoggingEventBuilder {
 
     /**
      * Add an argument to the event being built.
+     * Synonymous with {@link #arg(Object)}.
      *
      * @param p an Object to add.
      * @return a LoggingEventBuilder, usually <b>this</b>.
@@ -66,15 +67,153 @@ public interface LoggingEventBuilder {
     LoggingEventBuilder addArgument(Object p);
 
     /**
-     * Add an argument supplier to the event being built.
+     * Add an argument to the event being built.
+     * Synonymous with {@link #addArgument(Object)}.
      *
+     * @param p an Object to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    @CheckReturnValue
+    default LoggingEventBuilder arg(Object p) {
+        return addArgument(p);
+    }
+
+    /**
+     * <p>Add an argument supplier to the event being built. Synonymous with {@link #arg(Supplier)}.
+     *  </p>
      * @param objectSupplier an Object supplier to add.
      * @return a LoggingEventBuilder, usually <b>this</b>.
      */
     @CheckReturnValue
     LoggingEventBuilder addArgument(Supplier<?> objectSupplier);
 
 
+    /**
+     * <p>Add an argument supplier to the event being built. Synonymous with {@link #addArgument(Supplier)}.
+     * </p>
+     *
+     * @param objectSupplier an Object supplier to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since 2.1.0
+     */
+    @CheckReturnValue
+    default LoggingEventBuilder arg(Supplier<?> objectSupplier) {
+        return addArgument(objectSupplier);
+    }
+
+    /**
+     * Add a value of type <code>boolean</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Boolean</code>. However, However, the NOP implementation, i.e.
+     *  {@link NOPLoggingEventBuilder}, skips the cast.</p>
+     *
+     * @param b a value of type <code>boolean</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    default public LoggingEventBuilder arg(boolean b) {
+        return addArgument((Boolean) b);
+    }
+
+    /**
+     * Add a value of type <code>char</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Character</code>. However, the NOP implementation, i.e.
+     * {@link NOPLoggingEventBuilder}, skips the cast.</p>
+     *
+     * @param c a value of type <code>char</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    default public LoggingEventBuilder arg(char c) {
+        return addArgument((Character) c);
+    }
+
+    /**
+     * Add a value of type <code>byte</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Byte</code>. However, the NOP implementation, i.e.
+     *  {@link NOPLoggingEventBuilder}, skips the cast.</p>
+     *
+     * @param b a value of type <code>byte</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    default public LoggingEventBuilder arg(byte b) {
+        return addArgument((Byte) b);
+    }
+
+    /**
+     * Add a value of type <code>short</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Short</code>. However, the NOP implementation, i.e.
+     *  {@link NOPLoggingEventBuilder}, skips the cast.</p>
+     *
+     * @param s a value of type <code>short</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    default public LoggingEventBuilder arg(short s) {
+        return addArgument((Short) s);
+    }
+
+    /**
+     * Add a value of type <code>int</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Integer</code>. However, the NOP implementation, i.e.
+     * {@link NOPLoggingEventBuilder}, skips the cast.</p>
+     *
+     * @param i a value of type <code>int</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    default public LoggingEventBuilder arg(int i) {
+        return addArgument((Integer) i);
+    }
+
+    /**
+     * Add a value of type <code>long</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Long</code>. However, the NOP implementation, i.e.
+     *  {@link NOPLoggingEventBuilder}, skips the cast.</p>
+     *
+     * @param l a value of type <code>long</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    default public LoggingEventBuilder arg(long l) {
+        return addArgument((Long) l);
+    }
+
+    /**
+     * Add a value of type <code>float</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Float</code>. However, the NOP implementation, i.e.
+     * {@link NOPLoggingEventBuilder}, skips the cast.</p>
+     *
+     * @param f a value of type <code>float</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    default public LoggingEventBuilder arg(float f) {
+        return addArgument((Float) f);
+    }
+
+    /**
+     * Add a value of type <code>double</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Double</code>. However, the NOP implementation skips the cast.</p>
+     *
+     * @param d a value of type  <code>double</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    default LoggingEventBuilder arg(double d) {
+        return arg((Double) d);
+    }
+
+
     /**
      * Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built.
      *

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

@@ -2,16 +2,22 @@
 
 import java.util.function.Supplier;
 
+import org.slf4j.Logger;
 import org.slf4j.Marker;
 import org.slf4j.event.Level;
 
 /**
  * <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
+ * <p>As the name indicates, the methods 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
  *
+ * <p>The default implementations of {@link Logger#atTrace()}, {@link Logger#atDebug()} , {@link Logger#atInfo()},
+ * {@link Logger#atWarn()}  and {@link Logger#atError()}, return an instance of {@link NOPLoggingEventBuilder}
+ * when the relevant level is disabled for current logger. This is the core optimization in the fluent API.</p>
+ *
+ *
  * @author Ceki G&uuml;lc&uuml;
  * @since 2.0.0
  *
@@ -48,6 +54,98 @@ public LoggingEventBuilder addArgument(Supplier<?> objectSupplier) {
         return singleton();
     }
 
+    /**
+     * Add a value of type <code>boolean</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Boolean</code>. However, the NOP implementation skips the cast.</p>
+     *
+     * @param b a value of type <code>boolean</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    public LoggingEventBuilder arg(boolean b) {
+        return singleton();
+    }
+
+    /**
+     * Add a value of type <code>char</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Character</code>. However, the NOP implementation skips the cast.</p>
+     *
+     * @param c a value of type <code>char</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    public LoggingEventBuilder arg(char c) {
+        return singleton();
+    }
+
+    /**
+     * Add a value of type <code>byte</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Byte</code>. However, the NOP implementation skips the cast.</p>
+     *
+     * @param b a value of type <code>byte</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    public LoggingEventBuilder arg(byte b) {
+        return singleton();
+    }
+
+    /**
+     * Add a value of type <code>short</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Short</code>. However, the NOP implementation skips the cast.</p>
+     *
+     * @param s a value of type <code>short</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    public LoggingEventBuilder arg(short s) {
+        return singleton();
+    }
+
+    /**
+     * Add a value of type <code>int</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Integer</code>. However, the NOP implementation skips the cast.</p>
+     *
+     * @param i a value of type <code>int</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    public LoggingEventBuilder arg(int i) {
+        return singleton();
+    }
+
+    /**
+     * Add a value of type <code>long</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Long</code>. However, the NOP implementation skips the cast.</p>
+     *
+     * @param l a value of type <code>long</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    public LoggingEventBuilder arg(long l) {
+        return singleton();
+    }
+
+    /**
+     * Add a value of type <code>float</code> to the event being built.
+     *
+     * <p>The default implementation simply casts to <code>Float</code>. However, the NOP implementation skips the cast.</p>
+     *
+     * @param f a value of type <code>float</code> value to add.
+     * @return a LoggingEventBuilder, usually <b>this</b>.
+     * @since  2.1.0
+     */
+    public LoggingEventBuilder arg(float f) {
+        return singleton();
+    }
+
+
     @Override
     public LoggingEventBuilder addKeyValue(String key, Object value) {
         return singleton();