[groovy] 05/05: add extra @PlatformLog doco

[pa...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

paulk pushed a commit to branch GROOVY_4_0_X
in repository https://gitbox.apache.org/repos/asf/groovy.git

commit 5785bba559214f5a64e63b23e35c80f273935db7
Author: Paul King <pa...@asert.com.au>
AuthorDate: Wed Feb 16 17:58:07 2022 +1000

    add extra @PlatformLog doco
---
 src/spec/doc/core-metaprogramming.adoc | 69 +++++++++++++++++++++++++++++-----
 1 file changed, 59 insertions(+), 10 deletions(-)

diff --git a/src/spec/doc/core-metaprogramming.adoc b/src/spec/doc/core-metaprogramming.adoc
index cb15171..235e7d6 100644
--- a/src/spec/doc/core-metaprogramming.adoc
+++ b/src/spec/doc/core-metaprogramming.adoc
@@ -2116,13 +2116,12 @@ Deprecated. Consider using traits instead.
 
 ==== Logging improvements
 
-Groovy provides AST transformation that helps integrating with the most widely used logging frameworks. It's worth noting
-that annotating a class with one of those annotations doesn't prevent you from adding the appropriate logging framework
-on classpath.
+Groovy provides a family of AST transformations that help with integration of the most widely
+used logging frameworks. There is a transform and associated annotation for each of the common frameworks.
+These transforms provide a streamlined declarative approach to using the logging framework.
+In each case, the transform will:
 
-All transformations work in a similar way:
-
-* add static final `log` field corresponding to the logger
+* add a static final `log` field to the annotated class corresponding to the logger
 * wrap all calls to `log.level()` into the appropriate `log.isLevelEnabled` guard, depending on the underlying framework
 
 Those transformations support two parameters:
@@ -2130,6 +2129,9 @@ Those transformations support two parameters:
 * `value` (default `log`) corresponds to the name of the logger field
 * `category` (defaults to the class name) is the name of the logger category
 
+It's worth noting that annotating a class with one of those annotations doesn't
+prevent you from using the logging framework using the normal long-hand approach.
+
 [[xform-Log]]
 ===== `@groovy.util.logging.Log`
 
@@ -2150,7 +2152,7 @@ include::../test/LogImprovementsASTTransformsTest.groovy[tags=log_equiv,indent=0
 [[xform-Commons]]
 ===== `@groovy.util.logging.Commons`
 
-Groovy supports the http://commons.apache.org/proper/commons-logging/[Apache Commons Logging] framework using to the
+Groovy supports the http://commons.apache.org/proper/commons-logging/[Apache Commons Logging] framework using the
 `@Commons` annotation. Writing:
 
 [source,groovy]
@@ -2165,10 +2167,12 @@ is equivalent to writing:
 include::../test/LogImprovementsASTTransformsTest.groovy[tags=commons_equiv,indent=0]
 ----
 
+You still need to add the appropriate commons-logging jar to your classpath.
+
 [[xform-Log4j]]
 ===== `@groovy.util.logging.Log4j`
 
-Groovy supports the http://logging.apache.org/log4j/1.2/[Apache Log4j 1.x] framework using to the
+Groovy supports the http://logging.apache.org/log4j/1.2/[Apache Log4j 1.x] framework using the
 `@Log4j` annotation. Writing:
 
 [source,groovy]
@@ -2183,10 +2187,14 @@ is equivalent to writing:
 include::../test/LogImprovementsASTTransformsTest.groovy[tags=log4j_equiv,indent=0]
 ----
 
+You still need to add the appropriate log4j jar to your classpath.
+This annotation can also be used with the compatible https://reload4j.qos.ch/[reload4j] log4j
+drop-in replacement, just use the jar from that project instead of a log4j jar.
+
 [[xform-Log4j2]]
 ===== `@groovy.util.logging.Log4j2`
 
-Groovy supports the http://logging.apache.org/log4j/2.x/[Apache Log4j 2.x] framework using to the
+Groovy supports the http://logging.apache.org/log4j/2.x/[Apache Log4j 2.x] framework using the
 `@Log4j2` annotation. Writing:
 
 [source,groovy]
@@ -2201,10 +2209,12 @@ is equivalent to writing:
 include::../test/LogImprovementsASTTransformsTest.groovy[tags=log4j2_equiv,indent=0]
 ----
 
+You still need to add the appropriate log4j2 jar to your classpath.
+
 [[xform-Slf4j]]
 ===== `@groovy.util.logging.Slf4j`
 
-Groovy supports the http://www.slf4j.org/[Simple Logging Facade for Java (SLF4J)] framework using to the
+Groovy supports the http://www.slf4j.org/[Simple Logging Facade for Java (SLF4J)] framework using the
 `@Slf4j` annotation. Writing:
 
 [source,groovy]
@@ -2219,6 +2229,45 @@ is equivalent to writing:
 include::../test/LogImprovementsASTTransformsTest.groovy[tags=slf4j_equiv,indent=0]
 ----
 
+You still need to add the appropriate slf4j jar(s) to your classpath.
+
+[[xform-PlatformLog]]
+===== `@groovy.util.logging.PlatformLog`
+
+Groovy supports the https://openjdk.java.net/jeps/264[Java Platform Logging API and Service]
+framework using the `@PlatformLog` annotation. Writing:
+
+[source,groovy]
+----
+@groovy.util.logging.PlatformLog
+class Greeter {
+    void greet() {
+        log.info 'Called greeter'
+        println 'Hello, world!'
+    }
+}
+----
+
+is equivalent to writing:
+
+[source,groovy]
+----
+import java.lang.System.Logger
+import java.lang.System.LoggerFinder
+import static java.lang.System.Logger.Level.INFO
+
+class Greeter {
+    private static final transient Logger log =
+        LoggerFinder.loggerFinder.getLogger(Greeter.class.name, Greeter.class.module)
+    void greet() {
+        log.log INFO, 'Called greeter'
+        println 'Hello, world!'
+    }
+}
+----
+
+You need to be using JDK 9+ to use this capability.
+
 ==== Declarative concurrency
 
 The Groovy language provides a set of annotations aimed at simplifying common concurrency patterns in a declarative