Restructure configuration mechanism

.circleci/config.yml

@@ -1,5 +1,6 @@
 # Use the latest 2.1 version of CircleCI pipeline process engine.
 # See: https://circleci.com/docs/2.0/configuration-reference
+---
 version: 2.1
 
 # Define a job to be invoked later in a workflow.
@@ -9,7 +10,7 @@ jobs:
     # Specify the execution environment. You can specify an image from Dockerhub or use one of our Convenience Images from CircleCI's Developer Hub.
     # See: https://circleci.com/docs/2.0/configuration-reference/#docker-machine-macos-windows-executor
     docker:
-      - image: amazoncorretto:17
+      - image: eclipse-temurin:21-jdk-alpine
     # Add steps to the job
     # See: https://circleci.com/docs/2.0/configuration-reference/#steps
     steps:

buildSrc/src/main/groovy/penna.publishing.gradle

@@ -1,5 +1,4 @@
 plugins {
-    id 'penna.base-java'
     id 'maven-publish'
     id 'signing'
 }

gradle/libs.versions.toml

@@ -3,20 +3,32 @@ slf4j = "2.0.12"
 jackson = "2.17.0"
 jqwik = "1.8.4"
 junit = "5.10.2"
+junit-pioneer = "2.2.0"
 jmh = "1.37"
 jbrAnn = "24.1.0"
+snakeyaml = "2.2"
+snakeyaml-engine = "2.7"
 
 [libraries]
 slf4j = { module = "org.slf4j:slf4j-api", version.ref = "slf4j" }
+
+# Jackson support
 jackson-core = { module = "com.fasterxml.jackson.core:jackson-core", version.ref = "jackson" }
 jackson-databind = { module = "com.fasterxml.jackson.core:jackson-databind", version.ref = "jackson" }
 jackson-yaml = { module = "com.fasterxml.jackson.dataformat:jackson-dataformat-yaml", version.ref = "jackson" }
+
+# snakeyaml
+snakeyaml-plain = { module = "org.yaml:snakeyaml", version.ref = "snakeyaml" }
+snakeyaml-engine = { module = "org.snakeyaml:snakeyaml-engine", version.ref = "snakeyaml-engine" }
+
+# testing
 jqwik = { module = "net.jqwik:jqwik", version.ref = "jqwik" }
-junit-api = { module ="org.junit.jupiter:junit-jupiter-api", version.ref = "junit" }
-junit-engine = { module ="org.junit.jupiter:junit-jupiter-engine", version.ref = "junit" }
+junit-api = { module = "org.junit.jupiter:junit-jupiter-api", version.ref = "junit" }
+junit-engine = { module = "org.junit.jupiter:junit-jupiter-engine", version.ref = "junit" }
+junit-pioneer = { module = "org.junit-pioneer:junit-pioneer", version.ref = "junit-pioneer" }
 
-commons-math = { module = "org.apache.commons:commons-math3", version.prefer = "3.6.1"}
-commons-lang = { module = "org.apache.commons:commons-lang3", version.prefer = "3.13.0"}
+commons-math = { module = "org.apache.commons:commons-math3", version.prefer = "3.6.1" }
+commons-lang = { module = "org.apache.commons:commons-lang3", version.prefer = "3.13.0" }
 
 jmh-core = { module = "org.openjdk.jmh:jmh-core", version.ref = "jmh" }
 jmh-annotations = { module = "org.openjdk.jmh:jmh-generator-annprocess", version.ref = "jmh" }

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

gradlew

@@ -145,15 +145,15 @@ if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
     case $MAX_FD in #(
       max*)
         # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
-        # shellcheck disable=SC3045
+        # shellcheck disable=SC2039,SC3045
         MAX_FD=$( ulimit -H -n ) ||
             warn "Could not query maximum file descriptor limit"
     esac
     case $MAX_FD in  #(
       '' | soft) :;; #(
       *)
         # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
-        # shellcheck disable=SC3045
+        # shellcheck disable=SC2039,SC3045
         ulimit -n "$MAX_FD" ||
             warn "Could not set maximum file descriptor limit to $MAX_FD"
     esac
@@ -202,11 +202,11 @@ fi
 # Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
 DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
 
-# Collect all arguments for the java command;
-#   * $DEFAULT_JVM_OPTS, $JAVA_OPTS, and $GRADLE_OPTS can contain fragments of
-#     shell script including quotes and variable substitutions, so put them in
-#     double quotes to make sure that they get re-expanded; and
-#   * put everything else in single quotes, so that it's not re-expanded.
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
 
 set -- \
         "-Dorg.gradle.appname=$APP_BASE_NAME" \

penna-api/build.gradle

@@ -1,5 +1,5 @@
 plugins {
-    id 'penna.base-java'
+    id 'java-library'
     id 'penna.publishing'
     id 'pmd'
 }
@@ -10,6 +10,30 @@ repositories {
     mavenCentral()
 }
 
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(21)
+    }
+}
+
+// Reproducible builds
+tasks.withType(AbstractArchiveTask).configureEach {
+    preserveFileTimestamps = false
+    reproducibleFileOrder = true
+}
+
+// The API is an optional client-facing library and therefore it should not have gaps
+// in the documentation, nor fail on linting, so it is easier for consumers to understand
+// what it is doing under the hood.
+tasks.withType(JavaCompile).configureEach {
+    options.encoding = 'UTF-8'
+    options.compilerArgs += [
+            "-Xlint:all",
+            "-Xdoclint:all/public",
+            "-Werror"
+    ]
+}
+
 dependencies {
     compileOnly libs.slf4j
     compileOnly libs.jetbrains.annotations

penna-api/src/main/java/module-info.java

@@ -1,19 +1,17 @@
+import penna.api.configv2.Provider;
+
 /**
  * Penna API is a thin set of classes and records that are common-ground between the {@code penna.core} project
  * and satellite projects or user customization.
  * <br />
- * For example, in order to customize log level, a user might need to pass in a {@link penna.api.config.Config} through
- * the {@link penna.api.config.ConfigManager} interface.
  * <br /><br />
- * Advanced users might also implement a {@link penna.api.config.ConfigManager} themselves, so they have better runtime
- * control over log level and fields, for example, fine-tuning the amount of logged information based on metrics or usage
- * volume. For that, one can have a monitor thread collecting instrumentation data interacting directly with the
- * {@link penna.api.config.Configurable} instance.
  */
 module penna.api {
+    uses Provider;
     requires transitive org.slf4j;
     requires transitive org.jetbrains.annotations;
 
     exports penna.api.models;
     exports penna.api.config;
+    exports penna.api.configv2;
 }

penna-api/src/main/java/penna/api/config/ExceptionHandling.java

@@ -2,20 +2,22 @@
 
 /**
  * This record holds configuration on how Penna should handle logging exception fields.
- * @param maxDepth How far the stacktrace can go before cutting short
- * @param traverseDepth The amount of levels one can traverse down the exception
+ *
+ * @param maxDepth      How far the stacktrace can go before cutting short
+ * @param traverseDepth The amount of nested exceptions the logger can traverse before aborting
  * @param deduplication When enabled, penna will not print repeated stack frames
  */
 public record ExceptionHandling(
-    int maxDepth,
-    int traverseDepth,
-    boolean deduplication
+        int maxDepth,
+        int traverseDepth,
+        boolean deduplication
 ) {
 
     private static final ExceptionHandling singleton = new ExceptionHandling(64, 2, false);
 
     /**
      * Gets the default instance.
+     *
      * @return The static default instance.
      */
     public static ExceptionHandling getDefault() {
@@ -24,6 +26,7 @@ public static ExceptionHandling getDefault() {
 
     /**
      * Returns a copy of the original object swapping the value for {@link ExceptionHandling#deduplication}
+     *
      * @param deduplication Whether Penna should short-circuit out of writing stacktraces if identifies duplicates or not.
      * @return A copy of the original object with the values replaced
      */
@@ -33,16 +36,28 @@ public ExceptionHandling replaceDeduplication(boolean deduplication) {
 
     /**
      * Returns a copy of the original object swapping the value for {@link ExceptionHandling#maxDepth}
+     *
      * @param maxDepth The maximum number of stacktrace lines that should be shown before short-circuiting out
      * @return A copy of the original object with the values replaced
      */
     public ExceptionHandling replaceMaxDepth(int maxDepth) {
-        return new ExceptionHandling(maxDepth, this.traverseDepth,  this.deduplication);
+        return new ExceptionHandling(maxDepth, this.traverseDepth, this.deduplication);
+    }
+
+    /**
+     * Returns a copy of the original object swapping the value for {@link ExceptionHandling#traverseDepth}
+     *
+     * @param traverseDepth the amount of nested exceptions the logger will traverse
+     * @return A copy of the original object with the values replaced
+     */
+    public ExceptionHandling replaceTraverseDepth(int traverseDepth) {
+        return new ExceptionHandling(this.maxDepth, traverseDepth, this.deduplication);
     }
 
     /**
      * This is a convenience method that returns a copy of the default object with the value for {@link ExceptionHandling#deduplication}
      * replaced by the parameter provided.
+     *
      * @param deduplication Whether Penna should short-circuit out of writing stacktraces if identifies duplicates or not.
      * @return An instance of {@link ExceptionHandling}
      */
@@ -53,6 +68,7 @@ public static ExceptionHandling withDeduplication(boolean deduplication) {
     /**
      * This is a convenience method that returns a copy of the default object with the value for {@link ExceptionHandling#maxDepth}
      * replaced by the parameter provided.
+     *
      * @param maxDepth The maximum number of stacktrace lines that should be shown before short-circuiting out
      * @return An instance of {@link ExceptionHandling}
      */