Add @MaxMindDbCreator annotation for custom deserialization

oschwald · claude · oschwald · commit ffc9a7b13d1c · 2025-10-23T11:31:48.000-07:00
This adds support for marking static factory methods with @MaxMindDbCreator to enable custom deserialization logic, similar to Jackson's @JsonCreator. The decoder now automatically invokes creator methods when decoding values to target types, allowing for custom type conversions such as string-to-enum mappings with non-standard representations. This eliminates the need for redundant constructors that only perform type conversions, as the decoder can now apply conversions automatically via annotated static factory methods. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/src/main/java/com/maxmind/db/CachedCreator.java b/src/main/java/com/maxmind/db/CachedCreator.java
@@ -0,0 +1,16 @@
+package com.maxmind.db;
+
+import java.lang.reflect.Method;
+
+/**
+ * Cached creator method information for efficient deserialization.
+ * A creator method is a static factory method annotated with {@link MaxMindDbCreator}
+ * that converts a decoded value to the target type.
+ *
+ * @param method the static factory method annotated with {@link MaxMindDbCreator}
+ * @param parameterType the parameter type accepted by the creator method
+ */
+record CachedCreator(
+    Method method,
+    Class<?> parameterType
+) {}
diff --git a/src/main/java/com/maxmind/db/Decoder.java b/src/main/java/com/maxmind/db/Decoder.java
@@ -4,6 +4,8 @@
 import java.lang.annotation.Annotation;
 import java.lang.reflect.Constructor;
 import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
 import java.lang.reflect.ParameterizedType;
 import java.math.BigInteger;
 import java.net.InetAddress;
@@ -38,6 +40,8 @@ class Decoder {
 
     private final ConcurrentHashMap<Class<?>, CachedConstructor<?>> constructors;
 
+    private final ConcurrentHashMap<Class<?>, CachedCreator> creators;
+
     private final InetAddress lookupIp;
     private final Network lookupNetwork;
 
@@ -47,6 +51,7 @@ class Decoder {
             buffer,
             pointerBase,
             new ConcurrentHashMap<>(),
+            new ConcurrentHashMap<>(),
             null,
             null
         );
@@ -63,6 +68,7 @@ class Decoder {
             buffer,
             pointerBase,
             constructors,
+            new ConcurrentHashMap<>(),
             null,
             null
         );
@@ -73,13 +79,15 @@ class Decoder {
         Buffer buffer,
         long pointerBase,
         ConcurrentHashMap<Class<?>, CachedConstructor<?>> constructors,
+        ConcurrentHashMap<Class<?>, CachedCreator> creators,
         InetAddress lookupIp,
         Network lookupNetwork
     ) {
         this.cache = cache;
         this.pointerBase = pointerBase;
         this.buffer = buffer;
         this.constructors = constructors;
+        this.creators = creators;
         this.lookupIp = lookupIp;
         this.lookupNetwork = lookupNetwork;
     }
@@ -217,9 +225,11 @@ private <T> Object decodeByType(
                 }
                 return this.decodeArray(size, cls, elementClass);
             case BOOLEAN:
-                return Decoder.decodeBoolean(size);
+                Boolean bool = Decoder.decodeBoolean(size);
+                return convertValue(bool, cls);
             case UTF8_STRING:
-                return this.decodeString(size);
+                String str = this.decodeString(size);
+                return convertValue(str, cls);
             case DOUBLE:
                 return this.decodeDouble(size);
             case FLOAT:
@@ -653,6 +663,7 @@ private <T> Object decodeMapIntoObject(int size, Class<T> cls)
     private boolean shouldInstantiateFromContext(Class<?> parameterType) {
         if (parameterType == null
             || parameterType.isPrimitive()
+            || parameterType.isEnum()
             || isSimpleType(parameterType)
             || Map.class.isAssignableFrom(parameterType)
             || List.class.isAssignableFrom(parameterType)) {
@@ -870,6 +881,74 @@ private static void validateInjectionTarget(
         }
     }
 
+    /**
+     * Converts a decoded value to the target type using a creator method if available.
+     * If no creator method is found, returns the original value.
+     */
+    private Object convertValue(Object value, Class<?> targetType) {
+        if (value == null || targetType == null
+            || targetType == Object.class
+            || targetType.isInstance(value)) {
+            return value;
+        }
+
+        CachedCreator creator = getCachedCreator(targetType);
+        if (creator == null) {
+            return value;
+        }
+
+        if (!creator.parameterType().isInstance(value)) {
+            return value;
+        }
+
+        try {
+            return creator.method().invoke(null, value);
+        } catch (IllegalAccessException | InvocationTargetException e) {
+            throw new DeserializationException(
+                "Error invoking creator method " + creator.method().getName()
+                    + " on class " + targetType.getName(), e);
+        }
+    }
+
+    private CachedCreator getCachedCreator(Class<?> cls) {
+        CachedCreator cached = this.creators.get(cls);
+        if (cached != null) {
+            return cached;
+        }
+
+        CachedCreator creator = findCreatorMethod(cls);
+        if (creator != null) {
+            this.creators.putIfAbsent(cls, creator);
+        }
+        return creator;
+    }
+
+    private static CachedCreator findCreatorMethod(Class<?> cls) {
+        Method[] methods = cls.getDeclaredMethods();
+        for (Method method : methods) {
+            if (!method.isAnnotationPresent(MaxMindDbCreator.class)) {
+                continue;
+            }
+            if (!Modifier.isStatic(method.getModifiers())) {
+                throw new DeserializationException(
+                    "Creator method " + method.getName() + " on class " + cls.getName()
+                        + " must be static.");
+            }
+            if (method.getParameterCount() != 1) {
+                throw new DeserializationException(
+                    "Creator method " + method.getName() + " on class " + cls.getName()
+                        + " must have exactly one parameter.");
+            }
+            if (!cls.isAssignableFrom(method.getReturnType())) {
+                throw new DeserializationException(
+                    "Creator method " + method.getName() + " on class " + cls.getName()
+                        + " must return " + cls.getName() + " or a subtype.");
+            }
+            return new CachedCreator(method, method.getParameterTypes()[0]);
+        }
+        return null;
+    }
+
     private static Object parseDefault(String value, Class<?> target) {
         try {
             if (target.equals(Boolean.TYPE) || target.equals(Boolean.class)) {
diff --git a/src/main/java/com/maxmind/db/MaxMindDbCreator.java b/src/main/java/com/maxmind/db/MaxMindDbCreator.java
@@ -0,0 +1,43 @@
+package com.maxmind.db;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * {@code MaxMindDbCreator} is an annotation that can be used to mark a static factory
+ * method or constructor that should be used to create an instance of a class from a
+ * decoded value when decoding a MaxMind DB file.
+ *
+ * <p>This is similar to Jackson's {@code @JsonCreator} annotation and is useful for
+ * types that need custom deserialization logic, such as enums with non-standard
+ * string representations.</p>
+ *
+ * <p>Example usage:</p>
+ * <pre>
+ * public enum ConnectionType {
+ *     DIALUP("Dialup"),
+ *     CABLE_DSL("Cable/DSL");
+ *
+ *     private final String name;
+ *
+ *     ConnectionType(String name) {
+ *         this.name = name;
+ *     }
+ *
+ *     {@literal @}MaxMindDbCreator
+ *     public static ConnectionType fromString(String s) {
+ *         return switch (s) {
+ *             case "Dialup" -&gt; DIALUP;
+ *             case "Cable/DSL" -&gt; CABLE_DSL;
+ *             default -&gt; null;
+ *         };
+ *     }
+ * }
+ * </pre>
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
+public @interface MaxMindDbCreator {
+}
diff --git a/src/main/java/com/maxmind/db/Reader.java b/src/main/java/com/maxmind/db/Reader.java
@@ -28,6 +28,7 @@ public final class Reader implements Closeable {
     private final AtomicReference<BufferHolder> bufferHolderReference;
     private final NodeCache cache;
     private final ConcurrentHashMap<Class<?>, CachedConstructor<?>> constructors;
+    private final ConcurrentHashMap<Class<?>, CachedCreator> creators;
 
     /**
      * The file mode to use when opening a MaxMind DB.
@@ -166,6 +167,7 @@ private Reader(BufferHolder bufferHolder, String name, NodeCache cache) throws I
         this.ipV4Start = this.findIpV4StartNode(buffer);
 
         this.constructors = new ConcurrentHashMap<>();
+        this.creators = new ConcurrentHashMap<>();
     }
 
     /**
@@ -443,6 +445,7 @@ <T> T resolveDataPointer(
             buffer,
             this.searchTreeSize + DATA_SECTION_SEPARATOR_SIZE,
             this.constructors,
+            this.creators,
             lookupIp,
             network
         );
diff --git a/src/test/java/com/maxmind/db/ReaderTest.java b/src/test/java/com/maxmind/db/ReaderTest.java
@@ -595,6 +595,51 @@ public void testNestedContextAnnotationsWithCache(int chunkSize) throws IOExcept
         }
     }
 
+    @ParameterizedTest
+    @MethodSource("chunkSizes")
+    public void testCreatorMethod(int chunkSize) throws IOException {
+        try (var reader = new Reader(getFile("MaxMind-DB-test-decoder.mmdb"), chunkSize)) {
+            // Test with IP that has boolean=true
+            var ipTrue = InetAddress.getByName("1.1.1.1");
+            var resultTrue = reader.get(ipTrue, CreatorMethodModel.class);
+            assertNotNull(resultTrue);
+            assertNotNull(resultTrue.enumField);
+            assertEquals(BooleanEnum.TRUE_VALUE, resultTrue.enumField);
+
+            // Test with IP that has boolean=false
+            var ipFalse = InetAddress.getByName("::");
+            var resultFalse = reader.get(ipFalse, CreatorMethodModel.class);
+            assertNotNull(resultFalse);
+            assertNotNull(resultFalse.enumField);
+            assertEquals(BooleanEnum.FALSE_VALUE, resultFalse.enumField);
+        }
+    }
+
+    @ParameterizedTest
+    @MethodSource("chunkSizes")
+    public void testCreatorMethodWithString(int chunkSize) throws IOException {
+        try (var reader = new Reader(getFile("MaxMind-DB-test-decoder.mmdb"), chunkSize)) {
+            // The database has utf8_stringX="hello" in map.mapX at this IP
+            var ip = InetAddress.getByName("1.1.1.1");
+
+            // Get the nested map containing utf8_stringX to verify the raw data
+            var record = reader.get(ip, Map.class);
+            var map = (Map<?, ?>) record.get("map");
+            assertNotNull(map);
+            var mapX = (Map<?, ?>) map.get("mapX");
+            assertNotNull(mapX);
+            assertEquals("hello", mapX.get("utf8_stringX"));
+
+            // Now test that the creator method converts "hello" to StringEnum.HELLO
+            var result = reader.get(ip, StringEnumModel.class);
+            assertNotNull(result);
+            assertNotNull(result.map);
+            assertNotNull(result.map.mapX);
+            assertNotNull(result.map.mapX.stringEnumField);
+            assertEquals(StringEnum.HELLO, result.map.mapX.stringEnumField);
+        }
+    }
+
     @ParameterizedTest
     @MethodSource("chunkSizes")
     public void testDecodingTypesPointerDecoderFile(int chunkSize) throws IOException {
@@ -911,6 +956,97 @@ public WrapperContextOnlyModel(
         }
     }
 
+    enum BooleanEnum {
+        TRUE_VALUE,
+        FALSE_VALUE,
+        UNKNOWN;
+
+        @MaxMindDbCreator
+        public static BooleanEnum fromBoolean(Boolean b) {
+            if (b == null) {
+                return UNKNOWN;
+            }
+            return b ? TRUE_VALUE : FALSE_VALUE;
+        }
+    }
+
+    enum StringEnum {
+        HELLO("hello"),
+        GOODBYE("goodbye"),
+        UNKNOWN("unknown");
+
+        private final String value;
+
+        StringEnum(String value) {
+            this.value = value;
+        }
+
+        @MaxMindDbCreator
+        public static StringEnum fromString(String s) {
+            if (s == null) {
+                return UNKNOWN;
+            }
+            return switch (s) {
+                case "hello" -> HELLO;
+                case "goodbye" -> GOODBYE;
+                default -> UNKNOWN;
+            };
+        }
+
+        @Override
+        public String toString() {
+            return value;
+        }
+    }
+
+    static class CreatorMethodModel {
+        BooleanEnum enumField;
+
+        @MaxMindDbConstructor
+        public CreatorMethodModel(
+            @MaxMindDbParameter(name = "boolean")
+            BooleanEnum enumField
+        ) {
+            this.enumField = enumField;
+        }
+    }
+
+    static class MapXWithEnum {
+        StringEnum stringEnumField;
+
+        @MaxMindDbConstructor
+        public MapXWithEnum(
+            @MaxMindDbParameter(name = "utf8_stringX")
+            StringEnum stringEnumField
+        ) {
+            this.stringEnumField = stringEnumField;
+        }
+    }
+
+    static class MapWithEnum {
+        MapXWithEnum mapX;
+
+        @MaxMindDbConstructor
+        public MapWithEnum(
+            @MaxMindDbParameter(name = "mapX")
+            MapXWithEnum mapX
+        ) {
+            this.mapX = mapX;
+        }
+    }
+
+    static class StringEnumModel {
+        MapWithEnum map;
+
+        @MaxMindDbConstructor
+        public StringEnumModel(
+            @MaxMindDbParameter(name = "map")
+            MapWithEnum map
+        ) {
+            this.map = map;
+        }
+    }
+
     static class MapModelBoxed {
         MapXModelBoxed mapXField;
 
