Merge remote-tracking branch 'origin/master' into 449-map-property-type

Author: ljacqu

.github/workflows/mega-linter.yml

@@ -47,7 +47,7 @@ jobs:
     steps:
       # Git Checkout
       - name: Checkout Code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}
 
@@ -60,7 +60,7 @@ jobs:
 
         # You can override MegaLinter flavor used to have faster performances
         # More info at https://megalinter.io/latest/flavors/
-        uses: oxsecurity/megalinter/flavors/java@v8
+        uses: oxsecurity/megalinter/flavors/java@v9
 
         id: ml
 
@@ -110,7 +110,7 @@ jobs:
       # Create pull request if applicable
       # (for now works only on PR from same repository, not from forks)
       - name: Create Pull Request with applied fixes
-        uses: peter-evans/create-pull-request@v6
+        uses: peter-evans/create-pull-request@v7
         id: cpr
         if: >-
           steps.ml.outputs.has_updated_sources == 1 &&
@@ -166,7 +166,7 @@ jobs:
         run: sudo chown -Rc $UID .git/
 
       - name: Commit and push applied linter fixes
-        uses: stefanzweifel/git-auto-commit-action@v5
+        uses: stefanzweifel/git-auto-commit-action@v6
         if: >-
           steps.ml.outputs.has_updated_sources == 1 &&
           (

CONTRIBUTING.md

@@ -20,6 +20,14 @@ of the AuthMe Discord server.
 
 No sweat if some points aren't met since they can be addressed in pull requests, and PRs can be squashed.
 
+### Glossary
+
+Try to use and write terms consistently. Some spellings:
+
+- ConfigMe
+- Javadoc (always capitalized)
+- _no-arg constructor_ (not "zero-arg(s)")
+
 ## Code style
 
 Please try to match the current code style. A few pointers:

README.md

@@ -1,8 +1,8 @@
 # ConfigMe
 [![Build Status](https://github.com/AuthMe/ConfigMe/actions/workflows/maven_jdk8.yml/badge.svg)](https://github.com/AuthMe/ConfigMe/actions?query=branch%3Amaster)
 [![Coverage Status](https://coveralls.io/repos/github/AuthMe/ConfigMe/badge.svg?branch=master)](https://coveralls.io/github/AuthMe/ConfigMe?branch=master)
-[![Javadocs](https://www.javadoc.io/badge/ch.jalu/configme.svg)](https://www.javadoc.io/doc/ch.jalu/configme)
-[![MegaLinter](https://github.com/AuthMe/ConfigMe/workflows/MegaLinter/badge.svg?branch=master)](https://github.com/AuthMe/ConfigMe/actions?query=workflow%3AMegaLinter+branch%3Amaster)
+[![Javadoc](https://www.javadoc.io/badge/ch.jalu/configme.svg)](https://www.javadoc.io/doc/ch.jalu/configme)
+[![MegaLinter](https://github.com/AuthMe/ConfigMe/actions/workflows/mega-linter.yml/badge.svg?branch=master)](https://github.com/AuthMe/ConfigMe/actions?query=workflow%3AMegaLinter+branch%3Amaster)
 
 A simple configuration management library with YAML support out of the box.
 

pom.xml

@@ -40,7 +40,7 @@
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <project.jdkVersion>1.8</project.jdkVersion>
 
-        <version.junit>5.13.1</version.junit>
+        <version.junit>5.13.4</version.junit>
         <version.mockito>4.11.0</version.mockito>
     </properties>
 
@@ -95,7 +95,7 @@
                     <plugin>
                         <groupId>org.apache.maven.plugins</groupId>
                         <artifactId>maven-javadoc-plugin</artifactId>
-                        <version>3.11.2</version>
+                        <version>3.12.0</version>
                         <executions>
                             <execution>
                                 <id>attach-javadocs</id>
@@ -109,7 +109,7 @@
                     <plugin>
                         <groupId>org.apache.maven.plugins</groupId>
                         <artifactId>maven-gpg-plugin</artifactId>
-                        <version>3.2.7</version>
+                        <version>3.2.8</version>
                         <executions>
                             <execution>
                                 <id>sign-artifacts</id>
@@ -146,7 +146,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
-                <version>3.14.0</version>
+                <version>3.14.1</version>
                 <configuration>
                     <source>${project.jdkVersion}</source>
                     <target>${project.jdkVersion}</target>
@@ -157,7 +157,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-surefire-plugin</artifactId>
-                <version>3.5.3</version>
+                <version>3.5.4</version>
                 <configuration>
                     <!-- Force the right file encoding during unit testing -->
                     <argLine>-Dfile.encoding=${project.build.sourceEncoding} @{argLine}</argLine>
@@ -186,7 +186,7 @@
         <dependency>
             <groupId>org.yaml</groupId>
             <artifactId>snakeyaml</artifactId>
-            <version>2.4</version>
+            <version>2.5</version>
         </dependency>
 
         <!-- TypeInfo and other utils -->

src/main/java/ch/jalu/configme/SettingsManagerBuilder.java

@@ -91,7 +91,7 @@ private SettingsManagerBuilder(@NotNull PropertyResource resource) {
      */
     @SafeVarargs
     public final @NotNull SettingsManagerBuilder configurationData(
-                                                                  @NotNull Class<? extends SettingsHolder>... classes) {
+                                                        @NotNull Class<? extends SettingsHolder> @NotNull ... classes) {
         this.configurationData = ConfigurationDataBuilder.createConfiguration(classes);
         return this;
     }

src/main/java/ch/jalu/configme/beanmapper/Mapper.java

@@ -6,7 +6,7 @@
 import org.jetbrains.annotations.Nullable;
 
 /**
- * Maps the values of a property reader to Java classes (referred to as beans). See the JavaDoc on the default
+ * Maps the values of a property reader to Java classes (referred to as beans). See the Javadoc on the default
  * implementation, {@link MapperImpl}, for more details.
  */
 public interface Mapper {

src/main/java/ch/jalu/configme/beanmapper/MapperImpl.java

@@ -66,9 +66,6 @@
  */
 public class MapperImpl implements Mapper {
 
-    /** Marker object to signal that null is meant to be used as value. */
-    public static final Object RETURN_NULL = new Object();
-
     // ---------
     // Fields and general configurable methods
     // ---------
@@ -125,13 +122,13 @@ public MapperImpl(@NotNull BeanDefinitionService beanDefinitionService,
         // Step 1: attempt simple value transformation
         Object exportValue = leafValueHandler.toExportValue(value, exportContext);
         if (exportValue != null || value == null) {
-            return unwrapReturnNull(exportValue);
+            return LeafValueHandler.unwrapReturnNull(exportValue);
         }
 
         // Step 2: handle special cases like Collection
         exportValue = createExportValueForSpecialTypes(value, exportContext);
         if (exportValue != null) {
-            return unwrapReturnNull(exportValue);
+            return LeafValueHandler.unwrapReturnNull(exportValue);
         }
 
         // Step 3: treat as bean
@@ -159,12 +156,12 @@ public MapperImpl(@NotNull BeanDefinitionService beanDefinitionService,
 
     /**
      * Handles values of types which need special handling (such as Optional). Null means the value is not
-     * a special type and that the export value should be built differently. Use {@link #RETURN_NULL} to
+     * a special type and that the export value should be built differently. Use {@link LeafValueHandler#RETURN_NULL} to
      * signal that null should be used as the export value of the provided value.
      *
      * @param value the value to convert
      * @param exportContext export context
-     * @return the export value to use or {@link #RETURN_NULL}, or null if not applicable
+     * @return the export value to use or {@link LeafValueHandler#RETURN_NULL}, or null if not applicable
      */
     protected @Nullable Object createExportValueForSpecialTypes(@Nullable Object value,
                                                                 @NotNull ExportContext exportContext) {
@@ -192,16 +189,12 @@ public MapperImpl(@NotNull BeanDefinitionService beanDefinitionService,
             Optional<?> optional = (Optional<?>) value;
             return optional
                 .map(v -> toExportValue(v, exportContext.createChildContext(OPTIONAL_SPECIFIER)))
-                .orElse(RETURN_NULL);
+                .orElse(LeafValueHandler.RETURN_NULL);
         }
 
         return null;
     }
 
-    protected static @Nullable Object unwrapReturnNull(@Nullable Object o) {
-        return o == RETURN_NULL ? null : o;
-    }
-
     // ---------
     // Bean mapping
     // ---------

src/main/java/ch/jalu/configme/beanmapper/leafvaluehandler/LeafValueHandler.java

@@ -20,6 +20,9 @@
  */
 public interface LeafValueHandler {
 
+    /** Marker object to signal that null is meant to be used as value. */
+    Object RETURN_NULL = new Object();
+
     /**
      * Converts the given value to the target type (as defined by the mapping context), if supported. Otherwise,
      * null is returned. If a value is returned, its type is guaranteed to match the target type.
@@ -33,11 +36,25 @@ public interface LeafValueHandler {
     /**
      * Converts the value of a property to a value suitable for exporting. This method converts the opposite
      * way of {@link #convert}. Null is returned if this leaf value handler does not support the object's type.
+     * If the leaf value handler determines that {@code null} should be used as export value, then {@link #RETURN_NULL}
+     * is returned, which the caller needs to unwrap to {@code null}.
      *
      * @param value the value to convert
      * @param exportContext the export context (usually not needed)
      * @return the value suitable for exporting, or null if not applicable
      */
     @Nullable Object toExportValue(@Nullable Object value, @NotNull ExportContext exportContext);
 
+    /**
+     * Returns null if the object is {@link #RETURN_NULL}, otherwise the given object. Used to process return values
+     * from methods like {@link #toExportValue}, where {@code null} means the instance doesn't support the value,
+     * while {@link #RETURN_NULL} means null should be used as export value.
+     *
+     * @param object the object to potentially unwrap
+     * @param <T> the object type
+     * @return null, or the provided object
+     */
+    static <T> @Nullable T unwrapReturnNull(@Nullable T object) {
+        return object == RETURN_NULL ? null : object;
+    }
 }

src/main/java/ch/jalu/configme/beanmapper/leafvaluehandler/LeafValueHandlerImpl.java

@@ -144,7 +144,7 @@ public static final class Builder {
          * @param typesToAdd the leaf types to add
          * @return this builder
          */
-        public @NotNull Builder addTypes(@NotNull MapperLeafType... typesToAdd) {
+        public @NotNull Builder addTypes(@NotNull MapperLeafType @NotNull ... typesToAdd) {
             leafTypes.addAll(Arrays.asList(typesToAdd));
             return this;
         }

src/main/java/ch/jalu/configme/beanmapper/leafvaluehandler/MapperLeafType.java

@@ -30,7 +30,7 @@ public interface MapperLeafType {
      * when {@link ch.jalu.configme.beanmapper.MapperImpl#toExportValue(Object)} is called.
      * Returns null if the leaf value handler cannot handle the value.
      * <p>
-     * Return {@link ch.jalu.configme.beanmapper.MapperImpl#RETURN_NULL} to signal that null should be used
+     * Return {@link LeafValueHandler#RETURN_NULL} to signal that null should be used
      * as the export value (returning {@code null} itself means this leaf value handler cannot handle it).
      *
      * @param value the value to convert to an export value, if possible