diff --git a/doc/changelog.markdown b/doc/changelog.markdown index e0e3d49aee..a1bbd8ab68 100644 --- a/doc/changelog.markdown +++ b/doc/changelog.markdown @@ -2,7 +2,7 @@ Lombok Changelog ---------------- ### v1.18.9 "Edgy Guinea Pig" -* Nothing yet. +* 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. ### 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/ConfigurationKeys.java b/src/core/lombok/ConfigurationKeys.java index 951b28934b..ecfddb2a59 100644 --- a/src/core/lombok/ConfigurationKeys.java +++ b/src/core/lombok/ConfigurationKeys.java @@ -304,17 +304,16 @@ private ConfigurationKeys() {} // ----- NonNull ----- /** - * lombok configuration: {@code lombok.nonNull.exceptionType} = <String: a java exception type; either [{@code IllegalArgumentException} or: {@code NullPointerException}]. + * lombok configuration: {@code lombok.nonNull.exceptionType} = one of: [{@code IllegalArgumentException}, {@code NullPointerException}, or {@code Assertion}]. * - * Sets the exception to throw if {@code @NonNull} is applied to a method parameter, and a caller passes in {@code null}. + * Sets the exception to throw if {@code @NonNull} is applied to a method parameter, and a caller passes in {@code null}. If the chosen configuration is {@code Assertion}, an assertion is generated instead, + * which would mean your code throws an {@code AssertionError} if assertions are enabled, and does nothing if assertions are not enabled. */ public static final ConfigurationKey NON_NULL_EXCEPTION_TYPE = new ConfigurationKey("lombok.nonNull.exceptionType", "The type of the exception to throw if a passed-in argument is null (Default: NullPointerException).") {}; /** * lombok configuration: {@code lombok.nonNull.flagUsage} = {@code WARNING} | {@code ERROR}. * - * Implementation note: This field is supposed to be lombok.NonNull itself, but jdk6 and 7 have bugs where fields in annotations don't work well. - * * If set, any usage of {@code @NonNull} results in a warning / error. */ public static final ConfigurationKey NON_NULL_FLAG_USAGE = new ConfigurationKey("lombok.nonNull.flagUsage", "Emit a warning or error if @NonNull is used.") {}; @@ -439,7 +438,7 @@ private ConfigurationKeys() {} public static final ConfigurationKey LOG_CUSTOM_FLAG_USAGE = new ConfigurationKey("lombok.log.custom.flagUsage", "Emit a warning or error if @CustomLog is used.") {}; /** - * lombok configuration: {@code lombok.log.custom.declaration} = <String: logDeclaration>. + * lombok configuration: {@code lombok.log.custom.declaration} = <logDeclaration string>. * * The log declaration must follow the pattern: *
@@ -447,15 +446,19 @@ private ConfigurationKeys() {} *
* It consists of: *
    - *
  • Optional fully qualified logger type, e.g. {@code my.cool.Logger}, followed by space. If not specified, it defaults to the logger factory type. + *
  • Optional fully qualified logger type, e.g. {@code my.cool.Logger}, followed by space. If not specified, it defaults to the LoggerFactoryType. *
  • Fully qualified logger factory type, e.g. {@code my.cool.LoggerFactory}, followed by dot. - *
  • Factory method, e.g. {@code createLogger}. The method must be defined on the logger factory type and must be static. - *
  • At least one definition of factory method parameters, e.g. {@code ()} or {@code (TOPIC,TYPE)}. The format is comma-separated list of parameters wrapped in parentheses. - * The allowed parameters are: {@code TYPE} | {@code NAME} | {@code TOPIC} | {@code NULL}. - * There can be at most one parameter definition with {@code TOPIC} and at most one without {@code TOPIC}. + *
  • Factory method, e.g. {@code createLogger}. This must be a {@code public static} method in the LoggerFactoryType. + *
  • At least one definition of factory method parameters, e.g. {@code ()} or {@code (TOPIC,TYPE)}. The format inside the parentheses is a comma-separated list of parameter kinds.
    + * The allowed parameters are: {@code TYPE} | {@code NAME} | {@code TOPIC} | {@code NULL}.
    + * There can be at most one parameter definition with {@code TOPIC} and at most one without {@code TOPIC}. You can specify both. *
* - * If not set, any usage of {@code @CustomLog} will result in an error. + * An example: {@code my.cool.Logger my.cool.LoggerFactory.createLogger(TYPE)(TYPE,TOPIC)}
+ * If no topic is provided in the usage of {@code @CustomLog}, the above will invoke {@code LoggerFactory}'s {@code createLogger} method, passing in the type as a {@code java.lang.Class} variable.
+ * If a topic is provided, the overload of that method is invoked with 2 parameters: First the type (as {@code Class}), then the topic (as {@code String}). + *

+ * If this configuration key is not set, any usage of {@code @CustomLog} will result in an error. */ public static final ConfigurationKey LOG_CUSTOM_DECLARATION = new ConfigurationKey("lombok.log.custom.declaration", "Define the generated custom logger field.") {}; diff --git a/src/core/lombok/CustomLog.java b/src/core/lombok/CustomLog.java index 48c9f2ab5f..d1f45f7c64 100644 --- a/src/core/lombok/CustomLog.java +++ b/src/core/lombok/CustomLog.java @@ -27,7 +27,7 @@ import java.lang.annotation.Target; /** - * Causes lombok to generate a logger field. + * Causes lombok to generate a logger field based on a custom logger implementation. *

* 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.
* @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 R invokeStaticMethod(Method method, Object... arguments) { try { return (R) method.invoke(null, arguments); @@ -237,7 +237,7 @@ private static Method getMethod(Class argumentType, String name, Class... try { return argumentType.getMethod(name, parameterTypes); } catch (NoSuchMethodException e) { - throw new IllegalStateException("Method " + name + " with parameters " + Arrays.toString(parameterTypes) + "was not found.", e); + throw new IllegalStateException("Method " + name + " with parameters " + Arrays.toString(parameterTypes) + " was not found.", e); } catch (SecurityException e) { throw new IllegalStateException("Cannot inspect methods of type " + argumentType, e); } diff --git a/src/core/lombok/core/configuration/ConfigurationValueType.java b/src/core/lombok/core/configuration/ConfigurationValueType.java index f287f62a5b..a44a5a834a 100644 --- a/src/core/lombok/core/configuration/ConfigurationValueType.java +++ b/src/core/lombok/core/configuration/ConfigurationValueType.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 @@ -29,6 +29,7 @@ *

  • 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 parametersWithTopic = null; for (List parameters: allParameters) { if (parameters.contains(LogFactoryParameter.TOPIC)) { - if (parametersWithTopic != null) { - throw new IllegalArgumentException("There are too many parameters with TOPIC: " + parametersWithTopic + " and " + parameters); - } + if (parametersWithTopic != null) throw new IllegalArgumentException("There is more than one parameter definition that includes TOPIC: " + parametersWithTopic + " and " + parameters); parametersWithTopic = parameters; } else { - if (parametersWithoutTopic != null) { - throw new IllegalArgumentException("There are too many parameters without TOPIC: " + parametersWithoutTopic + " and " + parameters); - } + if (parametersWithoutTopic != null) throw new IllegalArgumentException("There is more than one parmaeter definition that does not include TOPIC: " + parametersWithoutTopic + " and " + parameters); parametersWithoutTopic = parameters; } } - if (parametersWithoutTopic == null && parametersWithTopic == null) { - // shouldn't happen the pattern does not allow it - throw new IllegalArgumentException("No logger factory method parameters specified."); - } + + // sanity check (the pattern should disallow this situation + if (parametersWithoutTopic == null && parametersWithTopic == null) throw new IllegalArgumentException("No logger factory method parameters specified."); return new LogDeclaration(loggerType, loggerFactoryType, loggerFactoryMethod, parametersWithoutTopic, parametersWithTopic); } @@ -103,7 +95,7 @@ private static 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 annotationClass; private final String annotationAsString; private final LogDeclaration declaration; - + public LoggingFramework(Class 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 log = (); + // private static final log = (); FieldDeclaration fieldDecl = new FieldDeclaration(logFieldName.toCharArray(), 0, -1); setGeneratedBy(fieldDecl, source); fieldDecl.declarationSourceEnd = -1; @@ -134,7 +132,7 @@ private static FieldDeclaration createField(LoggingFramework framework, Annotati MessageSend factoryMethodCall = new MessageSend(); setGeneratedBy(factoryMethodCall, source); - + factoryMethodCall.receiver = createNameReference(logDeclaration.getLoggerFactoryType().getName(), source); factoryMethodCall.selector = logDeclaration.getLoggerFactoryMethod().getCharArray(); @@ -151,7 +149,7 @@ private static FieldDeclaration createField(LoggingFramework framework, Annotati public static TypeReference createTypeReference(String typeName, Annotation source) { int pS = source.sourceStart, pE = source.sourceEnd; - long p = (long)pS << 32 | pE; + long p = (long) pS << 32 | pE; char[][] typeNameTokens = fromQualifiedName(typeName); long[] pos = new long[typeNameTokens.length]; @@ -161,7 +159,7 @@ public static TypeReference createTypeReference(String typeName, Annotation sour setGeneratedBy(typeReference, source); return typeReference; } - + private static final Expression[] createFactoryParameters(ClassLiteralAccess loggingType, Annotation source, List parameters, String loggerTopic) { Expression[] expressions = new Expression[parameters.size()]; int pS = source.sourceStart, pE = source.sourceEnd; @@ -174,7 +172,7 @@ private static final Expression[] createFactoryParameters(ClassLiteralAccess log expressions[i] = createFactoryTypeParameter(loggingType, source); break; case NAME: - long p = (long)pS << 32 | pE; + long p = (long) pS << 32 | pE; MessageSend factoryParameterCall = new MessageSend(); setGeneratedBy(factoryParameterCall, source); @@ -306,7 +304,7 @@ public static class HandleCustomLog extends EclipseAnnotationHandler annotation, Eclipse fieldDecl.type = new QualifiedTypeReference(TypeConstants.JAVA_LANG_OBJECT, new long[] { 0, 0, 0 }); setGeneratedBy(fieldDecl.type, source); fieldDecl.initialization = arrayAlloc; - // 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(annotationNode.up().up(), fieldDecl); injectField(annotationNode.up().up(), fieldDecl); } diff --git a/src/core/lombok/javac/handlers/HandleLog.java b/src/core/lombok/javac/handlers/HandleLog.java index a00cc4961c..5f0f8c90c4 100644 --- a/src/core/lombok/javac/handlers/HandleLog.java +++ b/src/core/lombok/javac/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,14 +51,14 @@ public class HandleLog { private static final IdentifierName LOG = IdentifierName.valueOf("log"); - + private HandleLog() { throw new UnsupportedOperationException(); } - + public static void processAnnotation(LoggingFramework framework, AnnotationValues annotation, JavacNode annotationNode, String loggerTopic) { deleteAnnotationIfNeccessary(annotationNode, framework.getAnnotationClass()); - + JavacNode typeNode = annotationNode.up(); switch (typeNode.getKind()) { case TYPE: @@ -67,7 +67,7 @@ public static void processAnnotation(LoggingFramework framework, AnnotationValue boolean useStatic = !Boolean.FALSE.equals(annotationNode.getAst().readConfiguration(ConfigurationKeys.LOG_ANY_FIELD_IS_STATIC)); - if ((((JCClassDecl)typeNode.get()).mods.flags & Flags.INTERFACE) != 0) { + if ((((JCClassDecl) typeNode.get()).mods.flags & Flags.INTERFACE) != 0) { annotationNode.addError(framework.getAnnotationAsString() + " is legal only on classes and enums."); return; } @@ -78,9 +78,9 @@ 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."); } - + JCFieldAccess loggingType = selfType(typeNode); createField(framework, typeNode, loggingType, annotationNode.get(), logFieldName.getName(), useStatic, loggerTopic); break; @@ -109,8 +109,8 @@ private static boolean createField(LoggingFramework framework, JavacNode typeNod JCMethodInvocation factoryMethodCall = maker.Apply(List.nil(), factoryMethod, List.from(factoryParameters)); JCVariableDecl fieldDecl = recursiveSetGeneratedBy(maker.VarDef( - maker.Modifiers(Flags.PRIVATE | Flags.FINAL | (useStatic ? Flags.STATIC : 0)), - typeNode.toName(logFieldName), loggerType, factoryMethodCall), source, typeNode.getContext()); + maker.Modifiers(Flags.PRIVATE | Flags.FINAL | (useStatic ? Flags.STATIC : 0)), + typeNode.toName(logFieldName), loggerType, factoryMethodCall), source, typeNode.getContext()); injectFieldAndMarkGenerated(typeNode, fieldDecl); return true; diff --git a/website/templates/features/log.html b/website/templates/features/log.html index 1de2683632..2547af14d6 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)