From 7fe489686716e72983d2c3586c7e2e1e07200ba7 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Tue, 21 May 2019 22:57:45 +0200 Subject: Code review for `@CustomLog`, and added documentation and a changelog entry. --- website/templates/features/log.html | 45 ++++++++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 11 deletions(-) (limited to 'website') diff --git a/website/templates/features/log.html b/website/templates/features/log.html index 1de26836..2547af14 100644 --- a/website/templates/features/log.html +++ b/website/templates/features/log.html @@ -7,52 +7,67 @@ NEW in lombok 0.10: You can annotate any class with a log annotation to let lombok generate a logger field.
The logger is named log and the field's type depends on which logger you have selected.

- NEW in lombok v1.16.24: Addition of google's FluentLogger (flogger). + NEW in lombok v1.16.24: Addition of google's FluentLogger (via @Flogger). +

+ NEW in lombok v1.18.10: Addition of @CustomLog which lets you add any logger by configuring how to create them with a config key.

<@f.overview>

- You put the variant of @Log on your class (whichever one applies to the logging system you use); you then have a static final log field, initialized to the name of your class, which you can then use to write log statements. + You put the variant of @Log on your class (whichever one applies to the logging system you use); you then have a static final log field, initialized as is the commonly proscribed way for the logging framework you use, which you can then use to write log statements.

There are several choices available:

-
+
@CommonsLog
Creates private static final org.apache.commons.logging.Log log = org.apache.commons.logging.LogFactory.getLog(LogExample.class); -
+
@Flogger
Creates private static final com.google.common.flogger.FluentLogger log = com.google.common.flogger.FluentLogger.forEnclosingClass(); -
+
@JBossLog
Creates private static final org.jboss.logging.Logger log = org.jboss.logging.Logger.getLogger(LogExample.class); -
+
@Log
Creates private static final java.util.logging.Logger log = java.util.logging.Logger.getLogger(LogExample.class.getName()); -
+
@Log4j
Creates private static final org.apache.log4j.Logger log = org.apache.log4j.Logger.getLogger(LogExample.class); -
+
@Log4j2
Creates private static final org.apache.logging.log4j.Logger log = org.apache.logging.log4j.LogManager.getLogger(LogExample.class); -
+
@Slf4j
Creates private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(LogExample.class); -
+
@XSlf4j
Creates private static final org.slf4j.ext.XLogger log = org.slf4j.ext.XLoggerFactory.getXLogger(LogExample.class); +
+ @CustomLog +
+ Creates private static final com.foo.your.Logger log = com.foo.your.LoggerFactory.createYourLogger(LogExample.class); +

+ This option requires that you add a configuration to your lombok.config file to specify what @CustomLog should do. +

+ For example:lombok.log.custom.declaration = com.foo.your.Logger com.foo.your.LoggerFactory.createYourLog(TYPE)(TOPIC) which would produce the above statement. First comes a type which is the type of your logger, then a space, then the type of your logger factory, then a dot, then the name of the logger factory method, and then 1 or 2 parameter definitions; at most one definition with TOPIC and at most one without TOPIC. Each parameter definition is specified as a parenthesised comma-separated list of parameter kinds. The options are: TYPE (passes this @Log decorated type, as a class), NAME (passes this @Log decorated type's fully qualified name), TOPIC (passes the explicitly chosen topic string set on the @CustomLog annotation), and NULL (passes null). +

+ The logger type is optional; if it is omitted, the logger factory type is used. (So, if your logger class has a static method that creates loggers, you can shorten your logger definition). +

+ Please contact us if there is a public, open source, somewhat commonly used logging framework that we don't yet have an explicit annotation for. The primary purpose of @CustomLog is to support your in-house, private logging frameworks. +

- By default, the topic (or name) of the logger will be the class name of the class annotated with the @Log annotation. This can be customised by specifying the topic parameter. For example: @XSlf4j(topic="reporting"). + By default, the topic (or name) of the logger will be the (name of) the class annotated with the @Log annotation. This can be customised by specifying the topic parameter. For example: @XSlf4j(topic="reporting").

@@ -67,10 +82,18 @@ lombok.log.fieldIsStatic = [true | false] (default: true)
Normally the generated logger is a static field. By setting this key to false, the generated field will be an instance field instead. +
+ lombok.log.custom.declaration = LoggerType LoggerFactoryType.loggerFactoryMethod(loggerFactoryMethodParams)(loggerFactoryMethodParams) +
+ Configures what to generate when @CustomLog is used. (The italicized parts are optional). loggerFactoryMethodParams is a comma-separated list of zero to any number of parameter kinds to pass. Valid kinds: TYPE, NAME, TOPIC, and NULL. You can include a parameter definition for the case where no explicit topic is set (do not include the TOPIC in the parameter list), and for when an explicit topic is set (do include the TOPIC parameter in the list).
lombok.log.flagUsage = [warning | error] (default: not set)
Lombok will flag any usage of any of the various log annotations as a warning or error if configured. +
+ lombok.log.custom.flagUsage = [warning | error] (default: not set) +
+ Lombok will flag any usage of @lombok.CustomLog as a warning or error if configured.
lombok.log.apacheCommons.flagUsage = [warning | error] (default: not set)
-- cgit From 06004b933b6afaa58ca753c4c33e8a977f91e294 Mon Sep 17 00:00:00 2001 From: Adam Juraszek Date: Wed, 22 May 2019 18:36:42 +0200 Subject: Fixes for CustomLog, AUTHORS entry, extended changlog --- AUTHORS | 1 + doc/changelog.markdown | 1 + src/core/lombok/core/configuration/TypeName.java | 2 +- src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java | 2 +- src/core/lombok/eclipse/handlers/HandleFieldNameConstants.java | 2 +- src/core/lombok/javac/handlers/JavacHandlerUtil.java | 4 ++-- website/templates/features/log.html | 2 +- 7 files changed, 8 insertions(+), 6 deletions(-) (limited to 'website') diff --git a/AUTHORS b/AUTHORS index e77bc462..f5d4f434 100755 --- a/AUTHORS +++ b/AUTHORS @@ -1,5 +1,6 @@ Lombok contributors in alphabetical order: +Adam Juraszek Bulgakov Alexander Christian Nüssgens Christian Sterzl diff --git a/doc/changelog.markdown b/doc/changelog.markdown index a1bbd8ab..9163b305 100644 --- a/doc/changelog.markdown +++ b/doc/changelog.markdown @@ -3,6 +3,7 @@ Lombok Changelog ### v1.18.9 "Edgy Guinea Pig" * FEATURE: You can now configure a custom logger framework using the new `@CustomLog` annotation in combination with the `lombok.log.custom.declaration` configuration key. See the [log documentation](https://projectlombok.org/features/Log) for more information. [Pullrequest #2086](https://github.com/rzwitserloot/lombok/pull/2086) with thanks to Adam Juraszek. +* IMPROBABLE BREAKING CHANGE: Stricter validation of configuration keys dealing with identifiers and types (`lombok.log.fieldName`, `lombok.fieldNameConstants.innerTypeName`, `lombok.copyableAnnotations`). ### v1.18.8 (May 7th, 2019) * FEATURE: You can now configure `@FieldNameConstants` to `CONSTANT_CASE` the generated constants, using a `lombok.config` option. See the [FieldNameConstants documentation](https://projectlombok.org/features/experimental/FieldNameConstants). [Issue #2092](https://github.com/rzwitserloot/lombok/issues/2092). diff --git a/src/core/lombok/core/configuration/TypeName.java b/src/core/lombok/core/configuration/TypeName.java index 4ac072dc..a1eac7bd 100644 --- a/src/core/lombok/core/configuration/TypeName.java +++ b/src/core/lombok/core/configuration/TypeName.java @@ -34,7 +34,7 @@ public final class TypeName implements ConfigurationValueType { if (name == null || name.trim().isEmpty()) return null; String trimmedName = name.trim(); - for (String identifier : trimmedName.split(".")) { + for (String identifier : trimmedName.split("\\.")) { if (!JavaIdentifiers.isValidJavaIdentifier(identifier)) throw new IllegalArgumentException("Invalid type name " + trimmedName + " (part " + identifier + ")"); } return new TypeName(trimmedName); diff --git a/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java b/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java index c8e7b60a..f04c541f 100644 --- a/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java +++ b/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java @@ -760,7 +760,7 @@ public class EclipseHandlerUtil { TypeReference typeRef = annotation.type; boolean match = false; if (typeRef != null && typeRef.getTypeName() != null) { - for (TypeName cn : configuredCopyable) if (typeMatches(cn.toString(), node, typeRef)) { + for (TypeName cn : configuredCopyable) if (cn != null && typeMatches(cn.toString(), node, typeRef)) { result.add(annotation); match = true; break; diff --git a/src/core/lombok/eclipse/handlers/HandleFieldNameConstants.java b/src/core/lombok/eclipse/handlers/HandleFieldNameConstants.java index 710a26f8..2db7591c 100644 --- a/src/core/lombok/eclipse/handlers/HandleFieldNameConstants.java +++ b/src/core/lombok/eclipse/handlers/HandleFieldNameConstants.java @@ -135,7 +135,7 @@ public class HandleFieldNameConstants extends EclipseAnnotationHandler configuredCopyable = node.getAst().readConfiguration(ConfigurationKeys.COPYABLE_ANNOTATIONS); if (!annoName.isEmpty()) { - for (TypeName cn : configuredCopyable) if (typeMatches(cn.toString(), node, anno.annotationType)) return List.of(anno); + for (TypeName cn : configuredCopyable) if (cn != null && typeMatches(cn.toString(), node, anno.annotationType)) return List.of(anno); for (String bn : BASE_COPYABLE_ANNOTATIONS) if (typeMatches(bn, node, anno.annotationType)) return List.of(anno); } @@ -1459,7 +1459,7 @@ public class JavacHandlerUtil { if (child.getKind() == Kind.ANNOTATION) { JCAnnotation annotation = (JCAnnotation) child.get(); boolean match = false; - for (TypeName cn : configuredCopyable) if (typeMatches(cn.toString(), node, annotation.annotationType)) { + for (TypeName cn : configuredCopyable) if (cn != null && typeMatches(cn.toString(), node, annotation.annotationType)) { result.append(annotation); match = true; break; diff --git a/website/templates/features/log.html b/website/templates/features/log.html index 2547af14..9436d338 100644 --- a/website/templates/features/log.html +++ b/website/templates/features/log.html @@ -15,7 +15,7 @@ <@f.overview>

- You put the variant of @Log on your class (whichever one applies to the logging system you use); you then have a static final log field, initialized as is the commonly proscribed way for the logging framework you use, which you can then use to write log statements. + You put the variant of @Log on your class (whichever one applies to the logging system you use); you then have a static final log field, initialized as is the commonly prescribed way for the logging framework you use, which you can then use to write log statements.

There are several choices available:

-- cgit