+ * If this configuration key is not set, any usage of {@code @CustomLog} will result in an error.
*/
public static final ConfigurationKey
* Complete documentation is found at the project lombok features page for lombok log annotations.
*
@@ -50,7 +50,7 @@
* }
*
*
- * Configuration must be provided in lombok.config, otherwise any usage will lead to errors.
+ * Configuration must be provided in lombok.config, otherwise any usage of this annotation will result in a compile-time error.
*
* This annotation is valid for classes and enumerations.
- NEW in lombok v1.16.24: Addition of google's FluentLogger (flogger).
+ NEW in lombok v1.16.24: Addition of google's FluentLogger (via
+ NEW in lombok v1.18.10: Addition of
- You put the variant of
There are several choices available:
+ This option requires that you add a configuration to your
+ For example:
+ 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
* @see lombok.extern.java.Log @Log
@@ -65,6 +65,11 @@
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
public @interface CustomLog {
- /** @return The category of the constructed Logger. By default, it will use the type where the annotation is placed. */
+ /**
+ *
+ * Sets a custom topic/category. Note that this requires you to specify a parameter configuration for your custom logger that includes {@code TOPIC}.
+ *
+ * @return The topic/category of the constructed Logger. By default (or for the empty string as topic), the parameter configuration without {@code TOPIC} is invoked.
+ */
String topic() default "";
}
diff --git a/src/core/lombok/core/configuration/ConfigurationDataType.java b/src/core/lombok/core/configuration/ConfigurationDataType.java
index 7dc7730197..50b47a2eb1 100644
--- a/src/core/lombok/core/configuration/ConfigurationDataType.java
+++ b/src/core/lombok/core/configuration/ConfigurationDataType.java
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2013-2014 The Project Lombok Authors.
+ * Copyright (C) 2013-2019 The Project Lombok Authors.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -143,16 +143,16 @@ private static ConfigurationValueParser valueTypeParser(Type argumentType) {
@Override public Object parse(String value) {
return invokeStaticMethod(valueOfMethod, value);
}
-
+
@Override public String description() {
return invokeStaticMethod(descriptionMethod);
}
-
+
@Override public String exampleValue() {
return invokeStaticMethod(exampleValueMethod);
}
- @SuppressWarnings("unchecked")
+ @SuppressWarnings("unchecked")
private public static String description()
* public static String exampleValue()
*
+ * None of them should throw checked exceptions.
* Based on these methods, an instance of {@link ConfigurationValueParser} is created
* and used by the configuration system.
*/
diff --git a/src/core/lombok/core/configuration/IdentifierName.java b/src/core/lombok/core/configuration/IdentifierName.java
index 52e51bd74c..db83c2cc7f 100644
--- a/src/core/lombok/core/configuration/IdentifierName.java
+++ b/src/core/lombok/core/configuration/IdentifierName.java
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2013 The Project Lombok Authors.
+ * Copyright (C) 2019 The Project Lombok Authors.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -31,13 +31,10 @@ private IdentifierName(String name) {
}
public static IdentifierName valueOf(String name) {
- if (name == null || name.trim().isEmpty()) {
- return null;
- }
+ if (name == null || name.trim().isEmpty()) return null;
+
String trimmedName = name.trim();
- if (!JavaIdentifiers.isValidJavaIdentifier(trimmedName)) {
- throw new IllegalArgumentException("Invalid identifier " + trimmedName);
- }
+ if (!JavaIdentifiers.isValidJavaIdentifier(trimmedName)) throw new IllegalArgumentException("Invalid identifier " + trimmedName);
return new IdentifierName(trimmedName);
}
diff --git a/src/core/lombok/core/configuration/LogDeclaration.java b/src/core/lombok/core/configuration/LogDeclaration.java
index 36f280e2b1..ad4102d4b8 100644
--- a/src/core/lombok/core/configuration/LogDeclaration.java
+++ b/src/core/lombok/core/configuration/LogDeclaration.java
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2013 The Project Lombok Authors.
+ * Copyright (C) 2019 The Project Lombok Authors.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -49,14 +49,11 @@ private LogDeclaration(TypeName loggerType, TypeName loggerFactoryType, Identifi
}
public static LogDeclaration valueOf(String declaration) {
- if (declaration == null) {
- return null;
- }
+ if (declaration == null) return null;
Matcher matcher = DECLARATION_PATTERN.matcher(declaration);
- if (!matcher.matches()) {
- throw new IllegalArgumentException("The declaration must follow the pattern: [LoggerType ]LoggerFactoryType.loggerFactoryMethod(loggerFactoryMethodParams)[(loggerFactoryMethodParams)]");
- }
+ if (!matcher.matches()) throw new IllegalArgumentException("The declaration must follow the pattern: [LoggerType ]LoggerFactoryType.loggerFactoryMethod(loggerFactoryMethodParams)[(loggerFactoryMethodParams)]");
+
TypeName loggerFactoryType = TypeName.valueOf(matcher.group(2));
TypeName loggerType = TypeName.valueOf(matcher.group(1));
if (loggerType == null) loggerType = loggerFactoryType;
@@ -67,21 +64,16 @@ public static LogDeclaration valueOf(String declaration) {
List> parseParameters(String parameters
}
public static String description() {
- return "custom-log-declartation";
+ return "custom-log-declaration";
}
public static String exampleValue() {
diff --git a/src/core/lombok/core/configuration/TypeName.java b/src/core/lombok/core/configuration/TypeName.java
index a3128527cf..4ac072dcbc 100644
--- a/src/core/lombok/core/configuration/TypeName.java
+++ b/src/core/lombok/core/configuration/TypeName.java
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2013 The Project Lombok Authors.
+ * Copyright (C) 2013-2019 The Project Lombok Authors.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -31,14 +31,11 @@ private TypeName(String name) {
}
public static TypeName valueOf(String name) {
- if (name == null || name.trim().isEmpty()) {
- return null;
- }
+ if (name == null || name.trim().isEmpty()) return null;
+
String trimmedName = name.trim();
for (String identifier : trimmedName.split(".")) {
- if (!JavaIdentifiers.isValidJavaIdentifier(identifier)) {
- throw new IllegalArgumentException("Invalid type name " + trimmedName + " (part " + identifier + ")");
- }
+ if (!JavaIdentifiers.isValidJavaIdentifier(identifier)) throw new IllegalArgumentException("Invalid type name " + trimmedName + " (part " + identifier + ")");
}
return new TypeName(trimmedName);
}
diff --git a/src/core/lombok/core/handlers/LoggingFramework.java b/src/core/lombok/core/handlers/LoggingFramework.java
index 38eadd17fe..88c0317b0f 100644
--- a/src/core/lombok/core/handlers/LoggingFramework.java
+++ b/src/core/lombok/core/handlers/LoggingFramework.java
@@ -1,3 +1,24 @@
+/*
+ * Copyright (C) 2019 The Project Lombok Authors.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
package lombok.core.handlers;
import java.lang.annotation.Annotation;
@@ -56,7 +77,7 @@ public class LoggingFramework {
private final Class extends Annotation> annotationClass;
private final String annotationAsString;
private final LogDeclaration declaration;
-
+
public LoggingFramework(Class extends Annotation> annotationClass, LogDeclaration declaration) {
this.annotationClass = annotationClass;
this.annotationAsString = "@" + annotationClass.getSimpleName();
diff --git a/src/core/lombok/eclipse/handlers/HandleLog.java b/src/core/lombok/eclipse/handlers/HandleLog.java
index e445685d29..3dc9536d55 100644
--- a/src/core/lombok/eclipse/handlers/HandleLog.java
+++ b/src/core/lombok/eclipse/handlers/HandleLog.java
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2010-2014 The Project Lombok Authors.
+ * Copyright (C) 2010-2019 The Project Lombok Authors.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -51,7 +51,6 @@
import lombok.core.handlers.LoggingFramework;
import lombok.eclipse.EclipseAnnotationHandler;
import lombok.eclipse.EclipseNode;
-import lombok.eclipse.handlers.EclipseHandlerUtil.MemberExistsResult;
public class HandleLog {
private static final IdentifierName LOG = IdentifierName.valueOf("log");
@@ -74,8 +73,7 @@ public static void processAnnotation(LoggingFramework framework, AnnotationValue
if (owner.get() instanceof TypeDeclaration) typeDecl = (TypeDeclaration) owner.get();
int modifiers = typeDecl == null ? 0 : typeDecl.modifiers;
- boolean notAClass = (modifiers &
- (ClassFileConstants.AccInterface | ClassFileConstants.AccAnnotation)) != 0;
+ boolean notAClass = (modifiers & (ClassFileConstants.AccInterface | ClassFileConstants.AccAnnotation)) != 0;
if (typeDecl == null || notAClass) {
annotationNode.addError(framework.getAnnotationAsString() + " is legal only on classes and enums.");
@@ -89,13 +87,13 @@ public static void processAnnotation(LoggingFramework framework, AnnotationValue
if (loggerTopic != null && loggerTopic.trim().isEmpty()) loggerTopic = null;
if (framework.getDeclaration().getParametersWithTopic() == null && loggerTopic != null) {
- annotationNode.addError(framework.getAnnotationAsString() + " does not allow to set a topic.");
+ annotationNode.addError(framework.getAnnotationAsString() + " does not allow a topic.");
}
ClassLiteralAccess loggingType = selfType(owner, source);
FieldDeclaration fieldDeclaration = createField(framework, source, loggingType, logFieldName.getName(), useStatic, loggerTopic);
fieldDeclaration.traverse(new SetGeneratedByVisitor(source), typeDecl.staticInitializerScope);
- // TODO temporary workaround for issue 217. http://code.google.com/p/projectlombok/issues/detail?id=217
+ // TODO temporary workaround for issue 290. https://github.com/rzwitserloot/lombok/issues/290
// injectFieldSuppressWarnings(owner, fieldDeclaration);
injectField(owner, fieldDeclaration);
owner.rebuild();
@@ -107,12 +105,12 @@ public static void processAnnotation(LoggingFramework framework, AnnotationValue
public static ClassLiteralAccess selfType(EclipseNode type, Annotation source) {
int pS = source.sourceStart, pE = source.sourceEnd;
- long p = (long)pS << 32 | pE;
-
+ long p = (long) pS << 32 | pE;
+
TypeDeclaration typeDeclaration = (TypeDeclaration)type.get();
TypeReference typeReference = new SingleTypeReference(typeDeclaration.name, p);
setGeneratedBy(typeReference, source);
-
+
ClassLiteralAccess result = new ClassLiteralAccess(source.sourceEnd, typeReference);
setGeneratedBy(result, source);
@@ -123,7 +121,7 @@ private static FieldDeclaration createField(LoggingFramework framework, Annotati
int pS = source.sourceStart, pE = source.sourceEnd;
long p = (long) pS << 32 | pE;
- // private static final
The logger is named log
and the field's type depends on which logger you have selected.
@Flogger
).
+ @CustomLog
which lets you add any logger by configuring how to create them with a config key.
@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.
-
@CommonsLog
private static final org.apache.commons.logging.Log log = org.apache.commons.logging.LogFactory.getLog(LogExample.class);
- @Flogger
private static final com.google.common.flogger.FluentLogger log = com.google.common.flogger.FluentLogger.forEnclosingClass();
- @JBossLog
private static final org.jboss.logging.Logger log = org.jboss.logging.Logger.getLogger(LogExample.class);
- @Log
private static final java.util.logging.Logger log = java.util.logging.Logger.getLogger(LogExample.class.getName());
- @Log4j
private static final org.apache.log4j.Logger log = org.apache.log4j.Logger.getLogger(LogExample.class);
- @Log4j2
private static final org.apache.logging.log4j.Logger log = org.apache.logging.log4j.LogManager.getLogger(LogExample.class);
- @Slf4j
private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(LogExample.class);
- @XSlf4j
private static final org.slf4j.ext.XLogger log = org.slf4j.ext.XLoggerFactory.getXLogger(LogExample.class);
+ @CustomLog
+ private static final com.foo.your.Logger log = com.foo.your.LoggerFactory.createYourLogger(LogExample.class);
+ lombok.config
file to specify what @CustomLog
should do.
+ 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
).
+ @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")
.
lombok.log.fieldIsStatic
= [true
| false
] (default: true)
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)
+ @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.log.custom.flagUsage
= [warning
| error
] (default: not set)
+ @lombok.CustomLog
as a warning or error if configured.
lombok.log.apacheCommons.flagUsage
= [warning
| error
] (default: not set)