From 383f008a05ab99cd68544174f9beb0180a53aa17 Mon Sep 17 00:00:00 2001 From: Ceki Gulcu Date: Fri, 14 Jun 2019 12:08:20 +0200 Subject: [PATCH] doc fixes --- pom.xml | 2 +- .../slf4j/jul/FluentApiInvocationTest.java | 27 ++--- slf4j-site/src/site/pages/manual.html | 102 ++++++++++++------ slf4j-site/src/site/pages/news.html | 2 +- 4 files changed, 84 insertions(+), 49 deletions(-) diff --git a/pom.xml b/pom.xml index 3b314df4..8db85ceb 100755 --- a/pom.xml +++ b/pom.xml @@ -45,7 +45,7 @@ 1.6.0 0.8.1 1.2.17 - 1.0.13 + 1.2.3 4.12 3.7.1 3.8.0 diff --git a/slf4j-jdk14/src/test/java/org/slf4j/jul/FluentApiInvocationTest.java b/slf4j-jdk14/src/test/java/org/slf4j/jul/FluentApiInvocationTest.java index b69446f8..cd0f056e 100755 --- a/slf4j-jdk14/src/test/java/org/slf4j/jul/FluentApiInvocationTest.java +++ b/slf4j-jdk14/src/test/java/org/slf4j/jul/FluentApiInvocationTest.java @@ -19,7 +19,7 @@ public class FluentApiInvocationTest { java.util.logging.Logger root = java.util.logging.Logger.getLogger(""); Level oldLevel; Logger logger = LoggerFactory.getLogger(this.getClass()); - + @Before public void setUp() throws Exception { oldLevel = root.getLevel(); @@ -56,24 +56,23 @@ public class FluentApiInvocationTest { assertLogMessage("Hello world.", 0); } - @Test public void messageWithTwoArguments() { int old = 15; int t = 16; - + { String msg = "Temperature set to {}. Old temperature was {}."; logger.atDebug().addArgument(t).addArgument(old).log(msg); assertLogMessage("Temperature set to 16. Old temperature was 15.", 0); } - + { String msg = "Temperature set to {}. Old temperature was {}."; logger.atDebug().log(msg, t, old); assertLogMessage("Temperature set to 16. Old temperature was 15.", 0); } - + { String msg = "Temperature set to {}. Old temperature was {}."; logger.atDebug().addArgument(t).log(msg, old); @@ -86,11 +85,11 @@ public class FluentApiInvocationTest { assertLogMessage("Temperature set to 16. Old temperature was 15.", 0); } } - + public int t16() { return 16; } - + @Test public void messageWithThrowable() { String msg = "Hello world."; @@ -104,7 +103,7 @@ public class FluentApiInvocationTest { public void messageWithArgumentsAndThrowable() { String msg = "Hello {}."; Throwable t = new IllegalStateException(); - + logger.atDebug().setCause(t).addArgument("world").log(msg); assertLogMessage("Hello world.", 0); assertThrowable(t, 0); @@ -113,20 +112,22 @@ public class FluentApiInvocationTest { @Test public void messageWithKeyValuePair() { String msg = "Hello world."; - logger.atDebug().addKeyValue("k", "v").log(msg); assertLogMessage("k=v Hello world.", 0); - + + int oldT = 15; + int newT = 16; + logger.atDebug().addKeyValue("oldT", oldT).addKeyValue("newT", newT).log("Temperature changed."); + assertLogMessage("oldT=15 newT=16 Temperature changed.", 1); + } - - private void assertLogMessage(String expected, int index) { LogRecord logRecord = listHandler.recordList.get(index); Assert.assertNotNull(logRecord); assertEquals(expected, logRecord.getMessage()); } - + private void assertThrowable(Throwable expected, int index) { LogRecord logRecord = listHandler.recordList.get(index); Assert.assertNotNull(logRecord); diff --git a/slf4j-site/src/site/pages/manual.html b/slf4j-site/src/site/pages/manual.html index 849ec198..8a21fa92 100755 --- a/slf4j-site/src/site/pages/manual.html +++ b/slf4j-site/src/site/pages/manual.html @@ -68,7 +68,7 @@ requires Java 8 and introduces a backward-compatible fluent logging API. By backward-compatible, we mean that existing logging frameworks do not have to be changed in order for the user to - benefit from the fluent logging API. + benefit from the fluent logging API.

Hello World

@@ -92,7 +92,7 @@ public class HelloWorld {

To run this example, you first need to download the slf4j distribution, and then to unpack it. Once that is done, add the file - slf4j-api-${project.version}.jar to your class path.

+ slf4j-api-${latest.stable.version}.jar to your class path.

Compiling and running HelloWorld will result in the following output being printed on the console.

@@ -106,12 +106,12 @@ SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further detail

The warning will disappear as soon as you add a binding to your class path. Assuming you add - slf4j-simple-${project.version}.jar so that your class + slf4j-simple-${latest.stable.version}.jar so that your class path contains:

Compiling and running HelloWorld will now result in @@ -157,11 +157,21 @@ SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further detail

As of version 2.0, SLF4J API introduces a fluent API.

-

The idea is to contruct a logging event piece by piece and to - log it once constructed. If a given logger is disabled for a - given level, than the no construction takes place.

+

The idea is to build a logging event piece by piece with a LoggingEventBuilder + and to log once the event is fully built. The + atTrace(), atDebug(), + atInfo(), atWarn() and + atError() methods new in the + org.slf4j.Logger interface return an instance of LoggingEventBuilder. For + disabled log levels, the returned + LoggingEventBuilder instance does nothing, thus + preserving the nano-second level performance of the regular + logging interface.

-

Here are few examples:

+ +

Here are few usage examples:

The statement

logger.atInfo().log("Hello world");
@@ -180,20 +190,44 @@ SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further detail logger.debug("Temperature set to {}. Old temperature was {}.", newT, oldT); // using fluent API, add arguments one by one and then log message - logger.atDebug().addArgument(newT).addArgument(oldT).log("Temperature set to {}. Old temperature was {}."); + logger.atDebug().addArgument(newT).addArgument(oldT).log("Temperature set to {}. Old temperature was {}."); // using fluent API, log message with arguments - logger.atDebug().log("Temperature set to {}. Old temperature was {}.", newT, oldT); + logger.atDebug().log("Temperature set to {}. Old temperature was {}.", newT, oldT); // using fluent API, add one argument and then log message providing one more argument - logger.atDebug().addArgument(newT).log("Temperature set to {}. Old temperature was {}.", oldT); + logger.atDebug().addArgument(newT).log("Temperature set to {}. Old temperature was {}.", oldT); // using fluent API, add one argument with a Supplier and then log message with one more argument. // Assume the method t16() returns 16. - logger.atDebug().addArgument(() -> t16()).log(msg, "Temperature set to {}. Old temperature was {}.", oldT); + logger.atDebug().addArgument(() -> t16()).log(msg, "Temperature set to {}. Old temperature was {}.", oldT); +

The fluent logging API allows the specification of many + different type of data to a org.slf4j.Logger + without a combinatorial explosion in the number of methods in + the Logger interface.

+ +

It is now possible to pass multiple Markers, pass arguments + with a Supplier + or pass multiple key-value pairs. Key-value pairs are + particularly useful in conjuction with log data analysers which + can interpret them automatically.

+ +

The following log statements are equivalent:

+ 
+        int newT = 15;
+        int oldT = 16;
+
+        // using classical API
+        logger.debug("oldT={} newT={} Temperature changed.", newT, oldT);
+
+        // using fluent API
+        logger.atDebug().addKeyValue("oldT", oldT).addKeyValue("newT", newT).log("Temperature changed.");          
+

Binding with a logging framework at deployment time

@@ -205,23 +239,23 @@ SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further detail
-
slf4j-log4j12-${project.version}.jar +
slf4j-log4j12-${latest.stable.version}.jar
Binding for log4j version 1.2, a widely used logging framework. You also need to place log4j.jar on your class path.

-
slf4j-jdk14-${project.version}.jar
+
slf4j-jdk14-${latest.stable.version}.jar
Binding for java.util.logging, also referred to as JDK 1.4 logging

-
slf4j-nop-${project.version}.jar
+
slf4j-nop-${latest.stable.version}.jar
Binding for NOP, silently discarding all logging.

-
slf4j-simple-${project.version}.jar
+
slf4j-simple-${latest.stable.version}.jar
Binding for Simple implementation, which outputs all events to @@ -229,7 +263,7 @@ SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further detail printed. This binding may be useful in the context of small applications.

-
slf4j-jcl-${project.version}.jar
+
slf4j-jcl-${latest.stable.version}.jar
Binding for Jakarta Commons @@ -260,16 +294,16 @@ SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further detail

To switch logging frameworks, just replace slf4j bindings on your class path. For example, to switch from java.util.logging - to log4j, just replace slf4j-jdk14-${project.version}.jar with - slf4j-log4j12-${project.version}.jar. + to log4j, just replace slf4j-jdk14-${latest.stable.version}.jar with + slf4j-log4j12-${latest.stable.version}.jar.

SLF4J does not rely on any special class loader machinery. In fact, each SLF4J binding is hardwired at compile time to use one and only one specific logging framework. For - example, the slf4j-log4j12-${project.version}.jar binding is + example, the slf4j-log4j12-${latest.stable.version}.jar binding is bound at compile time to use log4j. In your code, in addition - to slf4j-api-${project.version}.jar, you simply drop + to slf4j-api-${latest.stable.version}.jar, you simply drop one and only one binding of your choice onto the appropriate class path location. Do not place more than one binding on your class path. Here is a graphical illustration of @@ -355,11 +389,11 @@ SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further detail you need to do is to declare "ch.qos.logback:logback-classic" as a dependency in your pom.xml file as shown below. In addition to logback-classic-${logback.version}.jar, - this will pull slf4j-api-${project.version}.jar as well + this will pull slf4j-api-${latest.stable.version}.jar as well as logback-core-${logback.version}.jar into your project. Note that explicitly declaring a dependency on logback-core-${logback.version} or - slf4j-api-${project.version}.jar is not wrong and may + slf4j-api-${latest.stable.version}.jar is not wrong and may be necessary to impose the correct version of said artifacts by virtue of Maven's "nearest definition" dependency mediation rule. @@ -377,12 +411,12 @@ SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further detail log4j as the underlying logging framework, all you need to do is to declare "org.slf4j:slf4j-log4j12" as a dependency in your pom.xml file as shown below. In addition to - slf4j-log4j12-${project.version}.jar, this will pull - slf4j-api-${project.version}.jar as well as + slf4j-log4j12-${latest.stable.version}.jar, this will pull + slf4j-api-${latest.stable.version}.jar as well as log4j-${log4j.version}.jar into your project. Note that explicitly declaring a dependency on log4j-${log4j.version}.jar or - slf4j-api-${project.version}.jar is not wrong and may + slf4j-api-${latest.stable.version}.jar is not wrong and may be necessary to impose the correct version of said artifacts by virtue of Maven's "nearest definition" dependency mediation rule.

@@ -390,7 +424,7 @@ SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further detail 
<dependency> 
   <groupId>org.slf4j</groupId>
   <artifactId>slf4j-log4j12</artifactId>
-  <version>${project.version}</version>
+  <version>${latest.stable.version}</version>
 </dependency>

@@ -400,10 +434,10 @@ SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further detail framework, all you need to do is to declare "org.slf4j:slf4j-jdk14" as a dependency in your pom.xml file as shown below. In addition to - slf4j-jdk14-${project.version}.jar, this will pull - slf4j-api-${project.version}.jar into your project. + slf4j-jdk14-${latest.stable.version}.jar, this will pull + slf4j-api-${latest.stable.version}.jar into your project. Note that explicitly declaring a dependency on - slf4j-api-${project.version}.jar is not wrong and may + slf4j-api-${latest.stable.version}.jar is not wrong and may be necessary to impose the correct version of said artifact by virtue of Maven's "nearest definition" dependency mediation rule.

@@ -411,7 +445,7 @@ SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further detail 
<dependency> 
   <groupId>org.slf4j</groupId>
   <artifactId>slf4j-jdk14</artifactId>
-  <version>${project.version}</version>
+  <version>${latest.stable.version}</version>
 </dependency>
@@ -436,8 +470,8 @@ SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further detail

Mixing different versions of slf4j-api.jar and SLF4J binding can cause problems. For example, if you are using - slf4j-api-${project.version}.jar, then you should also use - slf4j-simple-${project.version}.jar, using + slf4j-api-${latest.stable.version}.jar, then you should also use + slf4j-simple-${latest.stable.version}.jar, using slf4j-simple-1.5.5.jar will not work.

diff --git a/slf4j-site/src/site/pages/news.html b/slf4j-site/src/site/pages/news.html index 4bc5c802..b8c4ac31 100755 --- a/slf4j-site/src/site/pages/news.html +++ b/slf4j-site/src/site/pages/news.html @@ -48,7 +48,7 @@

SLF4J version 2.0.0 requires Java 8. It builds on the 1.8.x series and adds a backward-compatible fluent-api. By backward-compatible, + href="manual.html#fluent">fluent logging api. By backward-compatible, we mean that existing logging frameworks do not have to be changed for the user to benefit from the fluent logging API.