Merge remote-tracking branch 'origin/master' into dependencies

Author: ljacqu

README.md

@@ -2,7 +2,7 @@
 [![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)
 [![Javadoc](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)
+[![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.
 

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/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

src/main/java/ch/jalu/configme/configurationdata/CommentsConfiguration.java

@@ -18,6 +18,8 @@ public class CommentsConfiguration {
 
     private final @NotNull Map<String, List<String>> comments;
 
+    public static final String FOOTER_KEY = "..FOOTER";
+
     /**
      * Constructor.
      */
@@ -41,7 +43,7 @@ public CommentsConfiguration(@NotNull Map<String, List<String>> comments) {
      * @param path the path to register the comment lines for
      * @param commentLines the comment lines to set for the path
      */
-    public void setComment(@NotNull String path, @NotNull String... commentLines) {
+    public void setComment(@NotNull String path, @NotNull String @NotNull ... commentLines) {
         List<String> replaced = comments.put(path, Collections.unmodifiableList(Arrays.asList(commentLines)));
 
         if (replaced != null) {
@@ -59,4 +61,23 @@ public void setComment(@NotNull String path, @NotNull String... commentLines) {
     public @NotNull @UnmodifiableView Map<String, @UnmodifiableView List<String>> getAllComments() {
         return Collections.unmodifiableMap(comments);
     }
+
+    /**
+     * Adds the given lines as footer comments. They will be written at the end of the configuration file.
+     *
+     * @param commentLines the comment lines to add as footer comments
+     */
+    public void setFooterComments(@NotNull String... commentLines) {
+        setComment(FOOTER_KEY, commentLines);
+    }
+
+    /**
+     * Adds the given lines as header comments. They will be written at the start of the configuration file.
+     *
+     * @param commentLines the comment lines to add as header comments
+     */
+    public void setHeaderComments(@NotNull String... commentLines) {
+        setComment("", commentLines);
+    }
+
 }

src/main/java/ch/jalu/configme/configurationdata/ConfigurationDataBuilder.java

@@ -56,7 +56,8 @@ public ConfigurationDataBuilder(@NotNull PropertyListBuilder propertyListBuilder
      * @return collected configuration data
      */
     @SafeVarargs
-    public static @NotNull ConfigurationData createConfiguration(@NotNull Class<? extends SettingsHolder>... classes) {
+    public static @NotNull ConfigurationData createConfiguration(
+                                                        @NotNull Class<? extends SettingsHolder> @NotNull ... classes) {
         return createConfiguration(Arrays.asList(classes));
     }
 

src/main/java/ch/jalu/configme/migration/version/VersionMigrationService.java

@@ -69,7 +69,7 @@ public VersionMigrationService(@NotNull Property<Integer> versionProperty,
      * @param migrations all known migrations
      */
     public VersionMigrationService(@NotNull Property<Integer> versionProperty,
-                                   @NotNull VersionMigration... migrations) {
+                                   @NotNull VersionMigration @NotNull ... migrations) {
         this(versionProperty, Arrays.asList(migrations));
     }
 

src/main/java/ch/jalu/configme/properties/MapProperty.java

@@ -1,25 +1,19 @@
 package ch.jalu.configme.properties;
 
-import ch.jalu.configme.properties.convertresult.ConvertErrorRecorder;
+import ch.jalu.configme.properties.types.MapPropertyType;
 import ch.jalu.configme.properties.types.PropertyType;
-import ch.jalu.configme.resource.PropertyReader;
 import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
 
 import java.util.Collections;
-import java.util.LinkedHashMap;
 import java.util.Map;
-import java.util.Objects;
 
 /**
- * Property for an immutable map whose keys is of type String and whose values can be configured.
- * The map retains the order of the elements.
+ * Property for a map with String keys and a configurable value type. The map retains the order of the elements.
+ * Maps produced by this property are guaranteed to never have a null key or null value.
  *
  * @param <V> the value type of the map
  */
-public class MapProperty<V> extends BaseProperty<Map<String, V>> {
-
-    private final PropertyType<V> valueType;
+public class MapProperty<V> extends TypeBasedProperty<Map<String, V>> {
 
     /**
      * Constructor. Builds a {@link MapProperty} with an empty map as default value.
@@ -28,9 +22,7 @@ public class MapProperty<V> extends BaseProperty<Map<String, V>> {
      * @param valueType the property type of the values
      */
     public MapProperty(@NotNull String path, @NotNull PropertyType<V> valueType) {
-        super(path, Collections.emptyMap());
-        Objects.requireNonNull(valueType, "valueType");
-        this.valueType = valueType;
+        super(path, new MapPropertyType<>(valueType), Collections.emptyMap());
     }
 
     /**
@@ -41,48 +33,46 @@ public MapProperty(@NotNull String path, @NotNull PropertyType<V> valueType) {
      * @param defaultValue the default value of the property
      */
     public MapProperty(@NotNull String path, @NotNull PropertyType<V> valueType, @NotNull Map<String, V> defaultValue) {
-        super(path, Collections.unmodifiableMap(defaultValue));
-        Objects.requireNonNull(valueType, "valueType");
-        this.valueType = valueType;
+        super(path, new MapPropertyType<>(valueType), defaultValue);
     }
 
-    @Override
-    protected @Nullable Map<String, V> getFromReader(@NotNull PropertyReader reader,
-                                                     @NotNull ConvertErrorRecorder errorRecorder) {
-        Object rawObject = reader.getObject(getPath());
-
-        if (!(rawObject instanceof Map<?, ?>)) {
-            return null;
-        }
-
-        Map<?, ?> rawMap = (Map<?, ?>) rawObject;
-        Map<String, V> map = new LinkedHashMap<>();
-
-        for (Map.Entry<?, ?> entry : rawMap.entrySet()) {
-            String path = entry.getKey().toString();
-            V value = valueType.convert(entry.getValue(), errorRecorder);
-
-            if (value != null) {
-                map.put(path, value);
-            }
-        }
-
-        return postProcessMap(map);
+    /**
+     * Constructor. Use {@link #withMapType}.
+     *
+     * @param mapType the map type
+     * @param path the path of the property
+     * @param defaultValue the default value of the property
+     */
+    // Constructor arguments are usually (path, type, defaultValue), but this is not possible here because there
+    // are other constructors with the same argument order.
+    protected MapProperty(@NotNull PropertyType<Map<String, V>> mapType, @NotNull String path,
+                          @NotNull Map<String, V> defaultValue) {
+        super(path, mapType, defaultValue);
     }
 
-    @Override
-    public @NotNull Object toExportValue(@NotNull Map<String, V> value) {
-        Map<String, Object> exportMap = new LinkedHashMap<>();
-
-        for (Map.Entry<String, V> entry : value.entrySet()) {
-            exportMap.put(entry.getKey(), valueType.toExportValue(entry.getValue()));
-        }
-
-        return exportMap;
+    /**
+     * Creates a new map property with the given path and type. An empty map is set as default value.
+     *
+     * @param path the path of the property
+     * @param mapType the map type
+     * @param <V> the type of the values in the map
+     * @return a new map property
+     */
+    public static <V> MapProperty<V> withMapType(@NotNull String path, @NotNull PropertyType<Map<String, V>> mapType) {
+        return new MapProperty<>(mapType, path, Collections.emptyMap());
     }
 
-    /* Allows to modify the map once its fully built based on the values in the property reader. */
-    protected @NotNull Map<String, V> postProcessMap(@NotNull Map<String, V> constructedMap) {
-        return Collections.unmodifiableMap(constructedMap);
+    /**
+     * Creates a new map property with the given path, type and default value.
+     *
+     * @param path the path of the property
+     * @param mapType the map type
+     * @param defaultValue the default value of the property
+     * @param <V> the type of the values in the map
+     * @return a new map property
+     */
+    public static <V> MapProperty<V> withMapType(@NotNull String path, @NotNull PropertyType<Map<String, V>> mapType,
+                                                 @NotNull Map<String, V> defaultValue) {
+        return new MapProperty<>(mapType, path, defaultValue);
     }
 }