Support fallback constructor/parameter selection

- Prefer @MaxMindDbConstructor; fallback to record canonical or single
  public constructor
- Infer parameter names: annotation > record component > Java parameter
  when `-parameters` is set; throw ParameterNotFoundException if names
  unavailable
- Enable -parameters in maven-compiler-plugin

Author: oschwald

CHANGELOG.md

@@ -22,6 +22,14 @@ CHANGELOG
     accessor methods (e.g., `binaryFormatMajorVersion()`, `databaseType()`, etc.).
   * `Network.getNetworkAddress()` and `Network.getPrefixLength()` have been
     replaced with record accessor methods `networkAddress()` and `prefixLength()`.
+* Deserialization improvements:
+  * If no constructor is annotated with `@MaxMindDbConstructor`, records now
+    use their canonical constructor automatically. For non‑record classes with
+    a single public constructor, that constructor is used by default.
+  * `@MaxMindDbParameter` annotations are now optional when parameter names
+    match field names in the database: for records, component names are used;
+    for classes, Java parameter names are used (when compiled with
+    `-parameters`). Annotations still take precedence when present.
 
 3.2.0 (2025-05-28)
 ------------------

README.md

@@ -120,6 +120,23 @@ public class Lookup {
 }
 ```
 
+### Constructor and parameter selection
+
+- Preferred: annotate a constructor with `@MaxMindDbConstructor` and its
+  parameters with `@MaxMindDbParameter(name = "...")`.
+- Records: if no constructor is annotated, the canonical record constructor is
+  used automatically. Record component names are used as field names.
+- Classes with a single public constructor: if no constructor is annotated,
+  that constructor is used automatically.
+- Unannotated parameters: when a parameter is not annotated, the reader falls
+  back to the parameter name. For records, this is the component name; for
+  classes, this is the Java parameter name. To use Java parameter names at
+  runtime, compile your model classes with the `-parameters` flag (Maven:
+  `maven-compiler-plugin` with `<parameters>true</parameters>`).
+  If Java parameter names are unavailable (no `-parameters`) and there is no
+  `@MaxMindDbParameter` annotation, the reader throws a
+  `ParameterNotFoundException` with guidance.
+
 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.

pom.xml

@@ -150,6 +150,7 @@
                     <release>17</release>
                     <source>17</source>
                     <target>17</target>
+                    <parameters>true</parameters>
                 </configuration>
             </plugin>
             <plugin>

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

@@ -388,8 +388,25 @@ private <T> Object decodeMapIntoObject(int size, Class<T> cls)
             parameterIndexes = new HashMap<>();
             var annotations = constructor.getParameterAnnotations();
             for (int i = 0; i < constructor.getParameterCount(); i++) {
-                var parameterName = getParameterName(cls, i, annotations[i]);
-                parameterIndexes.put(parameterName, i);
+                var name = getParameterName(annotations[i]);
+                if (name == null) {
+                    // Fallbacks: record component name, then Java parameter name
+                    // (requires -parameters)
+                    if (cls.isRecord()) {
+                        name = cls.getRecordComponents()[i].getName();
+                    } else {
+                        var param = constructor.getParameters()[i];
+                        if (param.isNamePresent()) {
+                            name = param.getName();
+                        } else {
+                            throw new ParameterNotFoundException(
+                                "Parameter name for index " + i + " on class " + cls.getName()
+                                    + " is not available. Annotate with @MaxMindDbParameter "
+                                    + "or compile with -parameters.");
+                        }
+                    }
+                }
+                parameterIndexes.put(name, i);
             }
 
             this.constructors.put(
@@ -457,34 +474,56 @@ private <T> CachedConstructor<T> getCachedConstructor(Class<T> cls) {
     private static <T> Constructor<T> findConstructor(Class<T> cls)
         throws ConstructorNotFoundException {
         var constructors = cls.getConstructors();
+        // Prefer explicitly annotated constructor
         for (var constructor : constructors) {
             if (constructor.getAnnotation(MaxMindDbConstructor.class) == null) {
                 continue;
             }
             @SuppressWarnings("unchecked")
-            Constructor<T> constructor2 = (Constructor<T>) constructor;
-            return constructor2;
+            var selected = (Constructor<T>) constructor;
+            return selected;
         }
 
-        throw new ConstructorNotFoundException("No constructor on class " + cls.getName()
-            + " with the MaxMindDbConstructor annotation was found.");
+        // Fallback for records: use canonical constructor
+        if (cls.isRecord()) {
+            try {
+                var components = cls.getRecordComponents();
+                var types = new Class<?>[components.length];
+                for (int i = 0; i < components.length; i++) {
+                    types[i] = components[i].getType();
+                }
+                var c = cls.getDeclaredConstructor(types);
+                @SuppressWarnings("unchecked")
+                var selected = (Constructor<T>) c;
+                return selected;
+            } catch (NoSuchMethodException e) {
+                // ignore and continue to next fallback
+            }
+        }
+
+        // Fallback for single-constructor classes
+        if (constructors.length == 1) {
+            var only = constructors[0];
+            @SuppressWarnings("unchecked")
+            var selected = (Constructor<T>) only;
+            return selected;
+        }
+
+        throw new ConstructorNotFoundException(
+            "No usable constructor on class " + cls.getName()
+                + ". Annotate a constructor with MaxMindDbConstructor, "
+                + "provide a record canonical constructor, or a single public constructor.");
     }
 
-    private static <T> String getParameterName(
-        Class<T> cls,
-        int index,
-        Annotation[] annotations
-    ) throws ParameterNotFoundException {
+    private static String getParameterName(Annotation[] annotations) {
         for (var annotation : annotations) {
             if (!annotation.annotationType().equals(MaxMindDbParameter.class)) {
                 continue;
             }
             var paramAnnotation = (MaxMindDbParameter) annotation;
             return paramAnnotation.name();
         }
-        throw new ParameterNotFoundException(
-            "Constructor parameter " + index + " on class " + cls.getName()
-                + " is not annotated with MaxMindDbParameter.");
+        return null;
     }
 
     private long nextValueOffset(long offset, int numberToSkip)

src/test/java/com/maxmind/db/ReaderTest.java

@@ -506,6 +506,9 @@ public void testDecodingTypesFile(int chunkSize) throws IOException {
         this.testDecodingTypesIntoModelObject(this.testReader, true);
         this.testDecodingTypesIntoModelObjectBoxed(this.testReader, true);
         this.testDecodingTypesIntoModelWithList(this.testReader);
+        this.testRecordImplicitConstructor(this.testReader);
+        this.testSingleConstructorWithoutAnnotation(this.testReader);
+        this.testPojoImplicitParameters(this.testReader);
     }
 
     @ParameterizedTest
@@ -516,6 +519,9 @@ public void testDecodingTypesStream(int chunkSize) throws IOException {
         this.testDecodingTypesIntoModelObject(this.testReader, true);
         this.testDecodingTypesIntoModelObjectBoxed(this.testReader, true);
         this.testDecodingTypesIntoModelWithList(this.testReader);
+        this.testRecordImplicitConstructor(this.testReader);
+        this.testSingleConstructorWithoutAnnotation(this.testReader);
+        this.testPojoImplicitParameters(this.testReader);
     }
 
     @ParameterizedTest
@@ -831,6 +837,65 @@ public TestModelList(
         }
     }
 
+    // Record-based decoding without annotations
+    record MapXRecord(List<Long> arrayX) {}
+    record MapRecord(MapXRecord mapX) {}
+    record TestRecordImplicit(MapRecord map) {}
+
+    private void testRecordImplicitConstructor(Reader reader) throws IOException {
+        var model = reader.get(InetAddress.getByName("::1.1.1.0"), TestRecordImplicit.class);
+        assertEquals(List.of(7L, 8L, 9L), model.map().mapX().arrayX());
+    }
+
+    // Single-constructor classes without @MaxMindDbConstructor
+    static class MapXPojo {
+        List<Long> arrayX;
+        String utf8StringX;
+
+        public MapXPojo(
+            @MaxMindDbParameter(name = "arrayX") List<Long> arrayX,
+            @MaxMindDbParameter(name = "utf8_stringX") String utf8StringX
+        ) {
+            this.arrayX = arrayX;
+            this.utf8StringX = utf8StringX;
+        }
+    }
+
+    static class MapContainerPojo {
+        MapXPojo mapX;
+
+        public MapContainerPojo(@MaxMindDbParameter(name = "mapX") MapXPojo mapX) {
+            this.mapX = mapX;
+        }
+    }
+
+    static class TopLevelPojo {
+        MapContainerPojo map;
+
+        public TopLevelPojo(@MaxMindDbParameter(name = "map") MapContainerPojo map) {
+            this.map = map;
+        }
+    }
+
+    private void testSingleConstructorWithoutAnnotation(Reader reader) throws IOException {
+        var pojo = reader.get(InetAddress.getByName("::1.1.1.0"), TopLevelPojo.class);
+        assertEquals(List.of(7L, 8L, 9L), pojo.map.mapX.arrayX);
+    }
+
+    // Unannotated parameters on non-record types using Java parameter names
+    static class TestPojoImplicit {
+        MapContainerPojo map;
+
+        public TestPojoImplicit(MapContainerPojo map) {
+            this.map = map;
+        }
+    }
+
+    private void testPojoImplicitParameters(Reader reader) throws IOException {
+        var model = reader.get(InetAddress.getByName("::1.1.1.0"), TestPojoImplicit.class);
+        assertEquals(List.of(7L, 8L, 9L), model.map.mapX.arrayX);
+    }
+
     @ParameterizedTest
     @MethodSource("chunkSizes")
     public void testZerosFile(int chunkSize) throws IOException {