Defaults for missing constructor params via annotation

We need both useDefault and defaultValue as otherwise there is no way
to distinguish between the default value being the empty string and
no default being set. If defaultValue is not set but useDefault is, we
will use the Java default value, e.g., 0 or the empty string.

Author: oschwald

README.md

@@ -137,6 +137,29 @@ public class Lookup {
   `@MaxMindDbParameter` annotation, the reader throws a
   `ParameterNotFoundException` with guidance.
 
+Defaults for missing values
+
+- Provide a default with
+  `@MaxMindDbParameter(name = "...", useDefault = true, defaultValue = "...")`.
+- Supports primitives, boxed types, and `String`. If `defaultValue` is empty
+  and `useDefault` is true, Java defaults are used (0, false, 0.0, empty
+  string).
+- Example:
+
+  ```java
+  @MaxMindDbConstructor
+  Example(
+      @MaxMindDbParameter(name = "count", useDefault = true, defaultValue = "0")
+      int count,
+      @MaxMindDbParameter(
+          name = "enabled",
+          useDefault = true,
+          defaultValue = "true"
+      )
+      boolean enabled
+  ) { }
+  ```
+
 You can also use the reader object to iterate over the database.
 The `reader.networks()` and `reader.networksWithin()` methods can
 be used for this purpose.

src/main/java/com/maxmind/db/CachedConstructor.java

@@ -7,6 +7,6 @@ record CachedConstructor<T>(
     Constructor<T> constructor,
     Class<?>[] parameterTypes,
     java.lang.reflect.Type[] parameterGenericTypes,
-    Map<String, Integer> parameterIndexes
-) {
-}
+    Map<String, Integer> parameterIndexes,
+    Object[] parameterDefaults
+) {}

src/main/java/com/maxmind/db/Decoder.java

@@ -446,6 +446,7 @@ private <T> Object decodeMapIntoObject(int size, Class<T> cls)
         Class<?>[] parameterTypes;
         java.lang.reflect.Type[] parameterGenericTypes;
         Map<String, Integer> parameterIndexes;
+        Object[] parameterDefaults;
         if (cachedConstructor == null) {
             constructor = findConstructor(cls);
 
@@ -454,9 +455,11 @@ private <T> Object decodeMapIntoObject(int size, Class<T> cls)
             parameterGenericTypes = constructor.getGenericParameterTypes();
 
             parameterIndexes = new HashMap<>();
+            parameterDefaults = new Object[constructor.getParameterCount()];
             var annotations = constructor.getParameterAnnotations();
             for (int i = 0; i < constructor.getParameterCount(); i++) {
-                var name = getParameterName(annotations[i]);
+                var ann = getParameterAnnotation(annotations[i]);
+                var name = ann != null ? ann.name() : null;
                 if (name == null) {
                     // Fallbacks: record component name, then Java parameter name
                     // (requires -parameters)
@@ -474,6 +477,10 @@ private <T> Object decodeMapIntoObject(int size, Class<T> cls)
                         }
                     }
                 }
+                // Prepare parsed defaults once and cache them
+                if (ann != null && ann.useDefault()) {
+                    parameterDefaults[i] = parseDefault(ann.defaultValue(), parameterTypes[i]);
+                }
                 parameterIndexes.put(name, i);
             }
 
@@ -483,14 +490,16 @@ private <T> Object decodeMapIntoObject(int size, Class<T> cls)
                     constructor,
                     parameterTypes,
                     parameterGenericTypes,
-                    parameterIndexes
+                    parameterIndexes,
+                    parameterDefaults
                 )
             );
         } else {
             constructor = cachedConstructor.constructor();
             parameterTypes = cachedConstructor.parameterTypes();
             parameterGenericTypes = cachedConstructor.parameterGenericTypes();
             parameterIndexes = cachedConstructor.parameterIndexes();
+            parameterDefaults = cachedConstructor.parameterDefaults();
         }
 
         var parameters = new Object[parameterTypes.length];
@@ -510,6 +519,13 @@ private <T> Object decodeMapIntoObject(int size, Class<T> cls)
             ).value();
         }
 
+        // Apply cached defaults for missing parameters, if any
+        for (int i = 0; i < parameters.length; i++) {
+            if (parameters[i] == null && parameterDefaults[i] != null) {
+                parameters[i] = parameterDefaults[i];
+            }
+        }
+
         try {
             return constructor.newInstance(parameters);
         } catch (InstantiationException
@@ -583,17 +599,60 @@ private static <T> Constructor<T> findConstructor(Class<T> cls)
                 + "provide a record canonical constructor, or a single public constructor.");
     }
 
-    private static String getParameterName(Annotation[] annotations) {
+    private static MaxMindDbParameter getParameterAnnotation(Annotation[] annotations) {
         for (var annotation : annotations) {
             if (!annotation.annotationType().equals(MaxMindDbParameter.class)) {
                 continue;
             }
-            var paramAnnotation = (MaxMindDbParameter) annotation;
-            return paramAnnotation.name();
+            return (MaxMindDbParameter) annotation;
         }
         return null;
     }
 
+    private static Object parseDefault(String value, Class<?> target) {
+        try {
+            if (target.equals(Boolean.TYPE) || target.equals(Boolean.class)) {
+                return value.isEmpty() ? false : Boolean.parseBoolean(value);
+            }
+            if (target.equals(Byte.TYPE) || target.equals(Byte.class)) {
+                var v = value.isEmpty() ? 0 : Integer.parseInt(value);
+                if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) {
+                    throw new DeserializationException(
+                        "Default value out of range for byte");
+                }
+                return (byte) v;
+            }
+            if (target.equals(Short.TYPE) || target.equals(Short.class)) {
+                var v = value.isEmpty() ? 0 : Integer.parseInt(value);
+                if (v < Short.MIN_VALUE || v > Short.MAX_VALUE) {
+                    throw new DeserializationException(
+                        "Default value out of range for short");
+                }
+                return (short) v;
+            }
+            if (target.equals(Integer.TYPE) || target.equals(Integer.class)) {
+                return value.isEmpty() ? 0 : Integer.parseInt(value);
+            }
+            if (target.equals(Long.TYPE) || target.equals(Long.class)) {
+                return value.isEmpty() ? 0L : Long.parseLong(value);
+            }
+            if (target.equals(Float.TYPE) || target.equals(Float.class)) {
+                return value.isEmpty() ? 0.0f : Float.parseFloat(value);
+            }
+            if (target.equals(Double.TYPE) || target.equals(Double.class)) {
+                return value.isEmpty() ? 0.0d : Double.parseDouble(value);
+            }
+            if (target.equals(String.class)) {
+                return value;
+            }
+        } catch (NumberFormatException e) {
+            throw new DeserializationException(
+                "Invalid default '" + value + "' for type " + target.getSimpleName(), e);
+        }
+        throw new DeserializationException(
+            "Defaults are only supported for primitives, boxed types, and String.");
+    }
+
     private long nextValueOffset(long offset, int numberToSkip)
         throws InvalidDatabaseException {
         if (numberToSkip == 0) {

src/main/java/com/maxmind/db/MaxMindDbParameter.java

@@ -14,4 +14,16 @@
      * @return the name of the parameter in the MaxMind DB file
      */
     String name();
+
+    /**
+     * Whether to use a default when the value is missing in the database.
+     */
+    boolean useDefault() default false;
+
+    /**
+     * The default value as a string. Parsed according to the Java parameter
+     * type (e.g., "0", "false"). If empty and {@code useDefault} is true,
+     * the Java type's default is used (0, false, 0.0, and "" for String).
+     */
+    String defaultValue() default "";
 }