Merge branch '7-update-example-implementation-of-none-level' into 'main'

Resolve "Multi-level and multi-marker configuration"

Closes #7

See merge request bot-by/slf4j-aws-lambda!7

Author: vitalijr2

changelog.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Support Markers
 - Update dependencies
+- Update javadocs and site
 
 ## 1.1.0 - 2022-06-29
 ### Added

pom.xml

@@ -66,7 +66,7 @@
 
   <properties>
     <!-- version -->
-    <revision>1.1.1</revision>
+    <revision>2.0.0</revision>
     <changelist>-SNAPSHOT</changelist>
     <sha1/>
     <!-- java and maven -->

readme.md

@@ -55,6 +55,7 @@ It looks for the `lambda-logger.properties` resource and read properties:
   Must be one of (_trace_, _debug_, _info_, _warn_, _error_), a value is case-insensitive.
   If not specified, defaults to _info_.
 * **levelInBrackets** - Should the level string be output in brackets? Defaults to `false`.
+* **log.a.b.c** - Logging detail level for a LambdaLogger instance named _a.b.c_.
 * **requestId** - Set the context name of AWS request ID. Defaults to `AWS_REQUEST_ID`.
 * **showDateTime** - Set to `true` if you want the current date and time to be included in output
   messages. Defaults to `false`.

src/main/java/uk/bot_by/aws_lambda/slf4j/LambdaLoggerFactory.java

@@ -15,7 +15,6 @@
  */
 package uk.bot_by.aws_lambda.slf4j;
 
-import static java.util.Arrays.copyOfRange;
 import static java.util.Objects.isNull;
 import static java.util.Objects.nonNull;
 
@@ -38,19 +37,66 @@
 
 /**
  * Responsible for building {@link Logger} using the {@link LambdaLogger} implementation.
+ * <p>
+ * The configuration is similar to <a
+ * href="https://www.slf4j.org/api/org/slf4j/simple/SimpleLogger.html">SLF4J Simple</a>.
+ * <p>
+ * It looks for the {@code lambda-logger.properties} resource and read properties:
+ * <ul>
+ * <li><strong>dateTimeFormat</strong> - The date and time format to be used in the output messages.
+ * The pattern describing the date and time format is defined by {@link java.text.SimpleDateFormat}.
+ * If the format is not specified or is invalid, the number of milliseconds since start up
+ * will be output.</li>
+ * <li><strong>defaultLogLevel</strong> - Default log level for all instances of LambdaLogger.
+ * Must be one of (<em>trace</em>, <em>debug</em>, <em>info</em>, <em>warn</em>, <em>error</em>),
+ * a value is case-insensitive. If not specified, defaults to <em>info</em>.</li>
+ * <li><strong>levelInBrackets</strong> - Should the level string be output in brackets?
+ * Defaults to {@code false}.</li>
+ * <li><strong>log.a.b.c</strong> - Logging detail level for a LambdaLogger instance named <em>a.b.c</em></li>
+ * <li><strong>requestId</strong> - Set the context name of <strong>AWS request ID</strong>.
+ * Defaults to {@code AWS_REQUEST_ID}.</li>
+ * <li><strong>showDateTime</strong> - Set to {@code true} if you want the current date and time
+ * to be included in output messages. Defaults to {@code false}.</li>
+ * <li><strong>showLogName</strong> - Set to {@code true} if you want the Logger instance name
+ * to be included in output messages. Defaults to {@code true}.</li>
+ * <li><strong>showShortLogName</strong> - Set to {@code true} if you want the last component of the name
+ * to be included in output messages. Defaults to {@code false}.</li>
+ * <li><strong>showThreadId</strong> - If you would like to output the current thread id,
+ * then set to {@code true}. Defaults to {@code false}.</li>
+ * <li><strong>showThreadName</strong> - Set to {@code true} if you want to output
+ * the current thread name. Defaults to {@code false}.</li>
+ * </ul>
+ * <p>
+ * The environment variables overrides the properties: <strong>LOG_AWS_REQUEST_ID</strong>,
+ * <strong>LOG_DATE_TIME_FORMAT</strong>, <strong>LOG_DEFAULT_LEVEL</strong>,
+ * <strong>LOG_LEVEL_IN_BRACKETS</strong>, <strong>LOG_SHOW_DATE_TIME</strong>,
+ * <strong>LOG_SHOW_NAME</strong>, <strong>LOG_SHOW_SHORT_NAME</strong>,
+ * <strong>LOG_SHOW_THREAD_ID</strong>, <strong>LOG_SHOW_THREAD_NAME</strong>.
  *
- * @see LoggerConfiguration LambdaLogger's configuration
+ * <h4>Fine-grained configuration with markers</h4>
+ * <p>
+ * The AWS Lambda Logger supports markers since <em>v2.0.0</em>.
+ * The log level (default or detail) can have some log level and each level can have some markers.
+ * <p>
+ * Example:
+ * <pre><code class="language-properties">
+ * log.org.test.Class=warn,info@iAmMarker,trace@important:notify-admin
+ * </pre>
+ * The logger for {@code org.test.Class} has the common <em>warn</em> log level.
+ * Also, it has additional levels <em>info</em> with the marker <em>iAmMarker</em>
+ * and <em>trace</em> with markers <em>important</em> and <em>notify-admin</em>.
  */
 public class LambdaLoggerFactory implements ILoggerFactory {
 
+  private static final String AT = "@";
+  private static final String COLON = ":";
+  private static final String COMMA = ",";
   private static final String CONFIGURATION_FILE = "lambda-logger.properties";
   private static final char DOT = '.';
   private static final String DOTS = "\\.+";
   private static final String NONE = "";
   private static final String UNDERSCORE = "_";
   private static final String SPACES = "\\s+";
-  private static final String COMMA = ",";
-  private static final String AT = "@";
 
   private final ConcurrentMap<String, Logger> loggers;
   private final DateFormat dateTimeFormat;
@@ -65,8 +111,13 @@ public class LambdaLoggerFactory implements ILoggerFactory {
   private final boolean showThreadName;
 
   public LambdaLoggerFactory() {
+    this(CONFIGURATION_FILE);
+  }
+
+  @VisibleForTesting
+  LambdaLoggerFactory(String configurationFile) {
     loggers = new ConcurrentHashMap<>();
-    properties = loadProperties();
+    properties = loadProperties(configurationFile);
     dateTimeFormat = getDateTimeFormat(ConfigurationProperty.DateTimeFormat);
     defaultLoggerLevel = getLoggerLevelProperty(ConfigurationProperty.DefaultLogLevel);
     levelInBrackets = getBooleanProperty(ConfigurationProperty.LevelInBrackets);
@@ -204,11 +255,11 @@ private Properties getProperties() {
     return properties;
   }
 
-  private Properties loadProperties() {
+  private Properties loadProperties(String configurationFile) {
     var properties = new Properties();
 
     try (InputStream configurationInputStream = Thread.currentThread().getContextClassLoader()
-        .getResourceAsStream(CONFIGURATION_FILE)) {
+        .getResourceAsStream(configurationFile)) {
       properties.load(configurationInputStream);
     } catch (IOException e) {
       // ignored
@@ -227,8 +278,7 @@ private List<LoggerLevel> parseLoggerLevelString(String loggerLevelString)
 
       loggerLevelBuilder.level(Level.valueOf(loggerLevelWithMarkers[0].toUpperCase()));
       if (loggerLevelWithMarkers.length > 1) {
-        for (String markerName : copyOfRange(loggerLevelWithMarkers, 1,
-            loggerLevelWithMarkers.length)) {
+        for (String markerName : loggerLevelWithMarkers[1].split(COLON)) {
           loggerLevelBuilder.marker(markerName);
         }
       }

src/main/java/uk/bot_by/aws_lambda/slf4j/LoggerConfiguration.java

@@ -29,43 +29,6 @@
 import org.slf4j.Marker;
 import org.slf4j.event.Level;
 
-/**
- * {@link LambdaLogger}'s configuration.
- * <p>
- * The configuration is similar to <a
- * href="https://www.slf4j.org/api/org/slf4j/simple/SimpleLogger.html">SLF4J Simple</a>.
- * <p>
- * It looks for the {@code lambda-logger.properties} resource and read properties:
- * <ul>
- * <li><strong>dateTimeFormat</strong> - The date and time format to be used in the output messages.
- * The pattern describing the date and time format is defined by {@link java.text.SimpleDateFormat}.
- * If the format is not specified or is invalid, the number of milliseconds since start up
- * will be output.</li>
- * <li><strong>defaultLogLevel</strong> - Default log level for all instances of LambdaLogger.
- * Must be one of (<em>trace</em>, <em>debug</em>, <em>info</em>, <em>warn</em>, <em>error</em>),
- * a value is case-insensitive. If not specified, defaults to <em>info</em>.</li>
- * <li><strong>levelInBrackets</strong> - Should the level string be output in brackets?
- * Defaults to {@code false}.</li>
- * <li><strong>requestId</strong> - Set the context name of <strong>AWS request ID</strong>.
- * Defaults to {@code AWS_REQUEST_ID}.</li>
- * <li><strong>showDateTime</strong> - Set to {@code true} if you want the current date and time
- * to be included in output messages. Defaults to {@code false}.</li>
- * <li><strong>showLogName</strong> - Set to {@code true} if you want the Logger instance name
- * to be included in output messages. Defaults to {@code true}.</li>
- * <li><strong>showShortLogName</strong> - Set to {@code true} if you want the last component of the name
- * to be included in output messages. Defaults to {@code false}.</li>
- * <li><strong>showThreadId</strong> - If you would like to output the current thread id,
- * then set to {@code true}. Defaults to {@code false}.</li>
- * <li><strong>showThreadName</strong> - Set to {@code true} if you want to output
- * the current thread name. Defaults to {@code false}.</li>
- * </ul>
- * <p>
- * The environment variables overrides the properties: <strong>LOG_AWS_REQUEST_ID</strong>,
- * <strong>LOG_DATE_TIME_FORMAT</strong>, <strong>LOG_DEFAULT_LEVEL</strong>,
- * <strong>LOG_LEVEL_IN_BRACKETS</strong>, <strong>LOG_SHOW_DATE_TIME</strong>,
- * <strong>LOG_SHOW_NAME</strong>, <strong>LOG_SHOW_SHORT_NAME</strong>,
- * <strong>LOG_SHOW_THREAD_ID</strong>, <strong>LOG_SHOW_THREAD_NAME</strong>.
- */
 class LoggerConfiguration {
 
   private static final String DOT = ".";
@@ -143,9 +106,6 @@ boolean showThreadName() {
     return showThreadName;
   }
 
-  /**
-   * {@link LambdaLogger} configuration's builder.
-   */
   static class Builder {
 
     private DateFormat dateTimeFormat;
@@ -162,58 +122,23 @@ static class Builder {
     private Builder() {
     }
 
-    /**
-     * Build a LambdaLoggerConfiguration instance.
-     *
-     * @return a configuration instance
-     */
     LoggerConfiguration build() {
       requireNonNull(loggerPredicates, "Logger level is null");
       requireNonNull(name, "Logger name is null");
       requireNonNull(requestId, "AWS request ID is null");
       return new LoggerConfiguration(this);
     }
 
-    /**
-     * The date and time format to be used in the output messages.
-     * <p>
-     * The pattern describing the date and time format is defined by
-     * {@link java.text.SimpleDateFormat}. If the format is not specified or is invalid, the number
-     * of milliseconds since start up will be output.
-     *
-     * @param dateTimeFormat date and time format
-     * @return a builder
-     */
     Builder dateTimeFormat(@Nullable DateFormat dateTimeFormat) {
       this.dateTimeFormat = dateTimeFormat;
       return this;
     }
 
-    /**
-     * Should the level string be output in brackets?
-     * <p>
-     * Defaults to {@code false}.
-     *
-     * @param levelInBrackets use brackets
-     * @return a builder
-     */
     Builder levelInBrackets(boolean levelInBrackets) {
       this.levelInBrackets = levelInBrackets;
       return this;
     }
 
-    /**
-     * The log level of the Logger instance.
-     * <p>
-     * Must be one of (<em>trace</em>, <em>debug</em>, <em>info</em>, <em>warn</em>,
-     * <em>error</em>), a value is case-insensitive. If not specified, defaults to <em>info</em>.
-     * <p>
-     * You can add some different log levels: it does not overwrite previous levels but add new one
-     * to a list. There has to be at least one log level.
-     *
-     * @param loggerLevel log level
-     * @return a builder
-     */
     Builder loggerLevel(@NotNull Level loggerLevel) {
       if (isNull(loggerPredicates)) {
         loggerPredicates = new ArrayList<>();
@@ -222,19 +147,6 @@ Builder loggerLevel(@NotNull Level loggerLevel) {
       return this;
     }
 
-    /**
-     * The marked log level of the Logger instance.
-     * <p>
-     * Must be one of (<em>trace</em>, <em>debug</em>, <em>info</em>, <em>warn</em>,
-     * <em>error</em>), a value is case-insensitive. If not specified, defaults to <em>info</em>.
-     * <p>
-     * You can add some different log levels: it does not overwrite previous levels but add new one
-     * to a list. There has to be at least one log level.
-     *
-     * @param loggerLevel   default log level
-     * @param loggerMarkers markers
-     * @return a builder
-     */
     Builder loggerLevel(@NotNull Level loggerLevel, @NotNull Marker... loggerMarkers) {
       if (isNull(loggerPredicates)) {
         loggerPredicates = new ArrayList<>();
@@ -253,89 +165,36 @@ Builder loggerLevel(@NotNull Level loggerLevel, @NotNull Marker... loggerMarkers
       return this;
     }
 
-    /**
-     * Name of the Logger instance.
-     *
-     * @param name logger name
-     * @return a builder
-     */
     Builder name(@NotNull String name) {
       this.name = name;
       return this;
     }
 
-    /**
-     * Context name of AWS request ID.
-     *
-     * @param requestId context name of AWS request ID
-     * @return a builder
-     */
     Builder requestId(@NotNull String requestId) {
       this.requestId = requestId;
       return this;
     }
 
-    /**
-     * Set to {@code true} if you want the current date and time to be included in output messages.
-     * <p>
-     * Defaults to {@code false}.
-     *
-     * @param showDateTime show date and time
-     * @return a builder
-     */
     Builder showDateTime(boolean showDateTime) {
       this.showDateTime = showDateTime;
       return this;
     }
 
-    /**
-     * Set to {@code true} if you want the Logger instance name to be included in output messages.
-     * <p>
-     * Defaults to {@code true}.
-     *
-     * @param showLogName show log name
-     * @return a builder
-     */
     Builder showLogName(boolean showLogName) {
       this.showLogName = showLogName;
       return this;
     }
 
-    /**
-     * Set to {@code true} if you want the last component of the name to be included in output
-     * messages.
-     * <p>
-     * Defaults to {@code false}.
-     *
-     * @param showShortLogName show short log name
-     * @return a builder
-     */
     Builder showShortLogName(boolean showShortLogName) {
       this.showShortLogName = showShortLogName;
       return this;
     }
 
-    /**
-     * If you would like to output the current thread id, then set to {@code true}.
-     * <p>
-     * Defaults to {@code false}.
-     *
-     * @param showThreadId show the current thread ID
-     * @return a builder
-     */
     Builder showThreadId(boolean showThreadId) {
       this.showThreadId = showThreadId;
       return this;
     }
 
-    /**
-     * Set to {@code true} if you want to output the current thread name.
-     * <p>
-     * Defaults to {@code false}.
-     *
-     * @param showThreadName show the current thread name
-     * @return a builder
-     */
     Builder showThreadName(boolean showThreadName) {
       this.showThreadName = showThreadName;
       return this;

src/main/java/uk/bot_by/aws_lambda/slf4j/LoggerLevel.java

@@ -23,7 +23,7 @@
 import org.slf4j.event.Level;
 import org.slf4j.helpers.BasicMarkerFactory;
 
-public class LoggerLevel {
+class LoggerLevel {
 
   private final Level level;
   private final Marker[] markers;