From f3fedc2e69e202a4e4d6387ca8402a992816a731 Mon Sep 17 00:00:00 2001 From: Ceki Gulcu Date: Fri, 22 Dec 2023 16:22:56 +0100 Subject: [PATCH] add kv() methods as synonyms for addKeyValue(), add kv() catering for primitives Signed-off-by: Ceki Gulcu --- .../org/slf4j/spi/LoggingEventBuilder.java | 232 ++++++++++++-- .../org/slf4j/spi/NOPLoggingEventBuilder.java | 302 +++++++++++++++--- 2 files changed, 471 insertions(+), 63 deletions(-) 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 cd48e4422..e3af848f5 100755 --- a/slf4j-api/src/main/java/org/slf4j/spi/LoggingEventBuilder.java +++ b/slf4j-api/src/main/java/org/slf4j/spi/LoggingEventBuilder.java @@ -43,7 +43,7 @@ public interface LoggingEventBuilder { /** * Set the cause for the logging event being built. * @param cause a throwable - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. */ @CheckReturnValue LoggingEventBuilder setCause(Throwable cause); @@ -52,27 +52,27 @@ public interface LoggingEventBuilder { * A {@link Marker marker} to the event being built. * * @param marker a Marker instance to add. - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. */ @CheckReturnValue LoggingEventBuilder addMarker(Marker marker); /** * Add an argument to the event being built. - * Synonymous with {@link #arg(Object)}. + * Synonymous with {@link #arg(Object)} method. * * @param p an Object to add. - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. */ @CheckReturnValue LoggingEventBuilder addArgument(Object p); /** * Add an argument to the event being built. - * Synonymous with {@link #addArgument(Object)}. + * Synonymous with {@link #addArgument(Object)} method. * * @param p an Object to add. - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. * @since 2.1.0 */ @CheckReturnValue @@ -81,10 +81,11 @@ default LoggingEventBuilder arg(Object p) { } /** - *

Add an argument supplier to the event being built. Synonymous with {@link #arg(Supplier)}. + *

Add an argument supplier to the event being built. + * Synonymous with {@link #arg(Supplier)} method. *

* @param objectSupplier an Object supplier to add. - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. */ @CheckReturnValue LoggingEventBuilder addArgument(Supplier objectSupplier); @@ -92,11 +93,11 @@ default LoggingEventBuilder arg(Object p) { /** *

Add an argument supplier to the event being built. - * Synonymous with {@link #addArgument(Supplier)}. + * Synonymous with {@link #addArgument(Supplier)} method. *

* * @param objectSupplier an Object supplier to add. - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. * @since 2.1.0 */ @CheckReturnValue @@ -111,7 +112,7 @@ default LoggingEventBuilder arg(Supplier objectSupplier) { * {@link NOPLoggingEventBuilder}, skips the cast.

* * @param b a value of type boolean value to add. - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. * @since 2.1.0 */ default public LoggingEventBuilder arg(boolean b) { @@ -125,7 +126,7 @@ default public LoggingEventBuilder arg(boolean b) { * {@link NOPLoggingEventBuilder}, skips the cast.

* * @param c a value of type char value to add. - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. * @since 2.1.0 */ default public LoggingEventBuilder arg(char c) { @@ -139,7 +140,7 @@ default public LoggingEventBuilder arg(char c) { * {@link NOPLoggingEventBuilder}, skips the cast.

* * @param b a value of type byte value to add. - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. * @since 2.1.0 */ default public LoggingEventBuilder arg(byte b) { @@ -153,7 +154,7 @@ default public LoggingEventBuilder arg(byte b) { * {@link NOPLoggingEventBuilder}, skips the cast.

* * @param s a value of type short value to add. - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. * @since 2.1.0 */ default public LoggingEventBuilder arg(short s) { @@ -167,7 +168,7 @@ default public LoggingEventBuilder arg(short s) { * {@link NOPLoggingEventBuilder}, skips the cast.

* * @param i a value of type int value to add. - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. * @since 2.1.0 */ default public LoggingEventBuilder arg(int i) { @@ -181,7 +182,7 @@ default public LoggingEventBuilder arg(int i) { * {@link NOPLoggingEventBuilder}, skips the cast.

* * @param l a value of type long value to add. - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. * @since 2.1.0 */ default public LoggingEventBuilder arg(long l) { @@ -195,7 +196,7 @@ default public LoggingEventBuilder arg(long l) { * {@link NOPLoggingEventBuilder}, skips the cast.

* * @param f a value of type float value to add. - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. * @since 2.1.0 */ default public LoggingEventBuilder arg(float f) { @@ -208,7 +209,7 @@ default public LoggingEventBuilder arg(float f) { *

The default implementation simply casts to Double. However, the NOP implementation skips the cast.

* * @param d a value of type double value to add. - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. * @since 2.1.0 */ default LoggingEventBuilder arg(double d) { @@ -221,25 +222,213 @@ default LoggingEventBuilder arg(double d) { * * @param key the key of the key value pair. * @param value the value of the key value pair. - * @return a LoggingEventBuilder, usually this. + * @return a LoggingEventBuilder instance, usually this. */ @CheckReturnValue LoggingEventBuilder addKeyValue(String key, Object value); + /** + * Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built. + * Synonymous with {@link #addKeyValue(String, Object)} method. + * + * @param key the key of the key value pair. + * @param value the value of the key value pair. + * @return a LoggingEventBuilder instance, usually this. + * + * @since 2.1.0 + */ + @CheckReturnValue + default LoggingEventBuilder kv(String key, Object value) { + return addKeyValue(key,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 this. + * @return a LoggingEventBuilder instance, usually this. */ @CheckReturnValue LoggingEventBuilder addKeyValue(String key, Supplier valueSupplier); + /** + * Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built. + * Synonymous with {@link #addKeyValue(String, Supplier)} method. + * + * @param key the key of the key value pair. + * @param valueSupplier a supplier of a value for the key value pair. + * @return a LoggingEventBuilder instance, usually this. + * + * @since 2.1.0 + */ + @CheckReturnValue + default LoggingEventBuilder kv(String key, Supplier valueSupplier) { + return addKeyValue(key, valueSupplier); + } + + + /** + *

Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being + * of type boolean. + *

+ *

+ *

The default implementation simply casts to value part to Boolean before calling + * {@link #addKeyValue(String, Object)}. However, the + * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.

+ * + * @param key the key of the key value pair. + * @param b the value of type boolean of the key value pair. + * @return a LoggingEventBuilder instance, usually this. + * + * @since 2.1.0 + */ + default public LoggingEventBuilder kv(String key, boolean b) { + return addKeyValue(key, (Boolean) b); + } + + /** + *

Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being + * of type char. + *

+ *

+ *

The default implementation simply casts to value part to Character before calling + * {@link #addKeyValue(String, Object)}. However, the + * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.

+ * + * @param key the key of the key value pair. + * @param c the value of type char of the key value pair. + * @return a LoggingEventBuilder instance, usually this. + * + * @since 2.1.0 + */ + default public LoggingEventBuilder kv(String key, char c) { + return addKeyValue(key, (Character) c); + } + + /** + *

Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being + * of type byte. + *

+ *

+ *

The default implementation simply casts to value part to Byte before calling + * {@link #addKeyValue(String, Object)}. However, the + * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.

+ * + * @param key the key of the key value pair. + * @param b the value of type byte of the key value pair. + * @return a LoggingEventBuilder instance, usually this. + * + * @since 2.1.0 + */ + default public LoggingEventBuilder kv(String key, byte b) { + return addKeyValue(key, (Byte) b); + } + + /** + *

Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being + * of type short. + *

+ *

+ *

The default implementation simply casts to value part to Short before calling + * {@link #addKeyValue(String, Object)}. However, the + * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.

+ * + * @param key the key of the key value pair. + * @param s the value of type short of the key value pair. + * @return a LoggingEventBuilder instance, usually this. + * + * @since 2.1.0 + */ + default public LoggingEventBuilder kv(String key, short s) { + return addKeyValue(key, (Short) s); + } + + + + /** + *

Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being + * of type int. + *

+ *

+ *

The default implementation simply casts to value part to Integer before calling + * {@link #addKeyValue(String, Object)}. However, the + * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.

+ * + * @param key the key of the key value pair. + * @param i the value of type int of the key value pair. + * @return a LoggingEventBuilder instance, usually this. + * + * @since 2.1.0 + */ + default public LoggingEventBuilder kv(String key, int i) { + return addKeyValue(key, (Integer) i); + } + + /** + *

Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being + * of type long. + *

+ *

+ *

The default implementation simply casts to value part to Integer before calling + * {@link #addKeyValue(String, Object)}. However, the + * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.

+ * + * @param key the key of the key value pair. + * @param l the value of type long of the key value pair. + * @return a LoggingEventBuilder instance, usually this. + * + * @since 2.1.0 + */ + default public LoggingEventBuilder kv(String key, long l) { + return addKeyValue(key, (Long) l); + } + + /** + *

Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being + * of type float. + *

+ *

+ *

The default implementation simply casts to value part to Float before calling + * {@link #addKeyValue(String, Object)}. However, the + * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.

+ * + * @param key the key of the key value pair. + * @param f the value of type float of the key value pair. + * @return a LoggingEventBuilder instance, usually this. + * + * @since 2.1.0 + */ + default public LoggingEventBuilder kv(String key, float f) { + return addKeyValue(key, (Float) f); + } + + /** + *

Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being + * of type double. + *

+ *

+ *

The default implementation simply casts to value part to Double before calling + * {@link #addKeyValue(String, Object)}. However, the + * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.

+ * + * @param key the key of the key value pair. + * @param f the value of type double of the key value pair. + * @return a LoggingEventBuilder instance, usually this. + * + * @since 2.1.0 + */ + default public LoggingEventBuilder kv(String key, double f) { + return addKeyValue(key, (Double) f); + } + /** * Sets the message of the logging event. * - * @since 2.0.0-beta0 + * @param message the message of the event + * @return a LoggingEventBuilder instance, usually this. + * @since 2.0.0 */ @CheckReturnValue LoggingEventBuilder setMessage(String message); @@ -248,6 +437,7 @@ default LoggingEventBuilder arg(double d) { * Sets the message of the event via a message supplier. * * @param messageSupplier supplies a String to be used as the message for the event + * @return a LoggingEventBuilder instance, usually this. * @since 2.0.0-beta0 */ @CheckReturnValue 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 2561f4772..6c9df405a 100755 --- a/slf4j-api/src/main/java/org/slf4j/spi/NOPLoggingEventBuilder.java +++ b/slf4j-api/src/main/java/org/slf4j/spi/NOPLoggingEventBuilder.java @@ -8,15 +8,14 @@ /** *

A no-operation implementation of {@link LoggingEventBuilder}.

- * - *

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. + *

+ *

As the name indicates, the methods in this class do nothing. In case a return value is expected, a singleton, + * i.e. the unique instance of this class, is returned. *

The default implementations of {@link Logger#atTrace()}, {@link Logger#atDebug()} , {@link Logger#atInfo()}, + *

+ *

Note that 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.

- * + * when the relevant level is disabled for current logger. This is the core optimization in the SLF4J fluent API.

* * @author Ceki Gülcü * @since 2.0.0 @@ -39,160 +38,379 @@ public static LoggingEventBuilder singleton() { return SINGLETON; } + /** + *

NOP implementation that does nothing.

+ * + * @param marker a Marker instance to add. + * @return + */ @Override public LoggingEventBuilder addMarker(Marker marker) { - return singleton(); + return this; } + /** + *

NOP implementation that does nothing.

+ * + * @param p + * @return a LoggingEventBuilder, usually this. + * @since 2.1.0 + */ @Override public LoggingEventBuilder addArgument(Object p) { - return singleton(); + return this; } + /** + *

NOP implementation that does nothing and thus skips calling get() call on the object supplier.

+ * + * @param objectSupplier + * @return a LoggingEventBuilder, usually this. + * @since 2.1.0 + */ @Override public LoggingEventBuilder addArgument(Supplier objectSupplier) { - return singleton(); + return this; } /** - * Add a value of type boolean to the event being built. + *

NOP implementation that does nothing and thus skips calling get() call on the object supplier.

* - *

The default implementation simply casts to Boolean. However, the NOP implementation skips the cast.

+ * @param objectSupplier + * @return a LoggingEventBuilder, usually this. + * @since 2.1.0 + */ + @Override + public LoggingEventBuilder arg(Supplier objectSupplier) { + return this; + } + + + /** + *

NOP implementation that does nothing and thus skips the type cast.

* * @param b a value of type boolean value to add. * @return a LoggingEventBuilder, usually this. * @since 2.1.0 */ public LoggingEventBuilder arg(boolean b) { - return singleton(); + return this; } /** - * Add a value of type char to the event being built. - * - *

The default implementation simply casts to Character. However, the NOP implementation skips the cast.

+ *

NOP implementation that does nothing and thus skips the type cast.

* * @param c a value of type char value to add. * @return a LoggingEventBuilder, usually this. * @since 2.1.0 */ + @Override public LoggingEventBuilder arg(char c) { - return singleton(); + return this; } /** - * Add a value of type byte to the event being built. - * - *

The default implementation simply casts to Byte. However, the NOP implementation skips the cast.

+ *

NOP implementation that does nothing and thus skips the type cast.

* * @param b a value of type byte value to add. * @return a LoggingEventBuilder, usually this. * @since 2.1.0 */ + @Override public LoggingEventBuilder arg(byte b) { - return singleton(); + return this; } /** - * Add a value of type short to the event being built. - * - *

The default implementation simply casts to Short. However, the NOP implementation skips the cast.

+ *

NOP implementation that does nothing and thus skips the type cast.

* * @param s a value of type short value to add. * @return a LoggingEventBuilder, usually this. * @since 2.1.0 */ public LoggingEventBuilder arg(short s) { - return singleton(); + return this; } /** - * Add a value of type int to the event being built. - * - *

The default implementation simply casts to Integer. However, the NOP implementation skips the cast.

+ *

NOP implementation that does nothing and thus skips the type cast.

* * @param i a value of type int value to add. * @return a LoggingEventBuilder, usually this. * @since 2.1.0 */ + @Override public LoggingEventBuilder arg(int i) { - return singleton(); + return this; } /** - * Add a value of type long to the event being built. - * - *

The default implementation simply casts to Long. However, the NOP implementation skips the cast.

+ *

NOP implementation that does nothing and thus skips the type cast.

* * @param l a value of type long value to add. * @return a LoggingEventBuilder, usually this. * @since 2.1.0 */ + @Override public LoggingEventBuilder arg(long l) { - return singleton(); + return this; } /** - * Add a value of type float to the event being built. - * - *

The default implementation simply casts to Float. However, the NOP implementation skips the cast.

+ *

NOP implementation that does nothing and thus skips the type cast.

* * @param f a value of type float value to add. * @return a LoggingEventBuilder, usually this. * @since 2.1.0 */ + @Override public LoggingEventBuilder arg(float f) { - return singleton(); + return this; } + /** + *

NOP implementation that does nothing and thus skips the type cast.

+ * + * @param d a value of type float value to add. + * @return a LoggingEventBuilder, usually this. + * @since 2.1.0 + */ + @Override + public LoggingEventBuilder arg(double d) { + return this; + } + /** + * NOP implementation that does nothing. + * + * @param key the key of the key value pair. + * @param value the value of the key value pair. + * @return a LoggingEventBuilder, usually this. + */ @Override public LoggingEventBuilder addKeyValue(String key, Object value) { - return singleton(); + return this; + } + + /** + * NOP implementation that doesnothing. + * + * @param key the key of the key value pair. + * @param value the value of the key value pair. + * @return a LoggingEventBuilder, usually this. + */ + @Override + public LoggingEventBuilder kv(String key, Object value) { + return this; } + /** + * NOP implementation that doesnothing. + * + * @param key the key of the key value pair. + * @param value a supplier of a value for the key value pair. + * @return a LoggingEventBuilder, usually this. + */ @Override public LoggingEventBuilder addKeyValue(String key, Supplier value) { - return singleton(); + return this; } + /** + * NOP implementation that doesnothing. + * + * @param key the key of the key value pair. + * @param value a supplier of a value for the key value pair. + * @return a LoggingEventBuilder, usually this. + */ + @Override + public LoggingEventBuilder kv(String key, Supplier value) { + return this; + } + + /** + * NOP implementation that does nothing. + * + * @param key the key of the key value pair. + * @param b the value of type boolean of the key value pair. + * @return a LoggingEventBuilder, usually this. + */ + @Override + public LoggingEventBuilder kv(String key, boolean b) { + return this; + } + + /** + * NOP implementation that does nothing. + * + * @param key the key of the key value pair. + * @param c the value of type char of the key value pair. + * @return + */ + @Override + public LoggingEventBuilder kv(String key, char c) { + return this; + } + + /** + * NOP implementation that does nothing. + * + * @param key the key of the key value pair. + * @param b the value of type byte of the key value pair. + * @return + */ + @Override + public LoggingEventBuilder kv(String key, byte b) { + return this; + } + + /** + * NOP implementation that does nothing. + * + * @param key the key of the key value pair. + * @param s the value of type short of the key value pair. + * @return + */ + @Override + public LoggingEventBuilder kv(String key, short s) { + return this; + } + + /** + * NOP implementation that does nothing. + * + * @param key the key of the key value pair. + * @param i the value of type int of the key value pair. + * @return + */ + @Override + public LoggingEventBuilder kv(String key, int i) { + return this; + } + + /** + * NOP implementation that does nothing. + * + * @param key the key of the key value pair. + * @param l the value of type long of the key value pair. + * @return + */ + @Override + public LoggingEventBuilder kv(String key, long l) { + return this; + } + + + /** + * NOP implementation that does nothing. + * + * @param key the key of the key value pair. + * @param f the value of type float of the key value pair. + * @return + */ + @Override + public LoggingEventBuilder kv(String key, float f) { + return this; + } + + /** + * NOP implementation that does nothing. + * + * @param key the key of the key value pair. + * @param d the value of type double of the key value pair. + * @return + */ + @Override + public LoggingEventBuilder kv(String key, double d) { + return this; + } + + /** + * NOP implementation that does nothing. + * + * @param cause a throwable + * @return + */ @Override public LoggingEventBuilder setCause(Throwable cause) { - return singleton(); + return this; } + /** + * + */ @Override public void log() { } + /** + * NOP implementation that does nothing. + * + * @param message the message of the event + * @return + */ @Override public LoggingEventBuilder setMessage(String message) { return this; } + + /** + * NOP implementation that does nothing. + * + * @param messageSupplier supplies a String to be used as the message for the event + * @return + */ @Override public LoggingEventBuilder setMessage(Supplier messageSupplier) { return this; } + /** + * NOP implementation that does nothing. + * + * @param message the message to log + */ @Override public void log(String message) { } + /** + * NOP implementation that does nothing. + * + * @param messageSupplier a Supplier returning a message of type String + */ @Override public void log(Supplier messageSupplier) { } + /** + * NOP implementation that does nothing. + * + * @param message the message to log + * @param arg an argument to be used with the message to log + */ @Override public void log(String message, Object arg) { } + /** + * NOP implementation that does nothing. + * + * @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 + */ @Override public void log(String message, Object arg0, Object arg1) { } + /** + * NOP implementation that does nothing. + * + * @param message the message to log + * @param args a list (actually an array) of arguments to be used with the message to log + */ @Override public void log(String message, Object... args) { - } - }