Add @MaxMindDbCreator annotation for custom deserialization

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>

Author: oschwald

README.md

@@ -170,6 +170,38 @@ Lookup context injection
   constructor argument. Values are populated for every lookup without being
   cached between different IPs.
 
+Custom deserialization
+
+- Use `@MaxMindDbCreator` to mark a static factory method or constructor that
+  should be used for custom deserialization of a type from a MaxMind DB file.
+- This annotation is similar to Jackson's `@JsonCreator` and is useful for
+  types that need custom deserialization logic, such as enums with non-standard
+  string representations or types that require special initialization.
+- The annotation can be applied to both constructors and static factory methods.
+- Example with an enum:
+
+  ```java
+  public enum ConnectionType {
+      DIALUP("Dialup"),
+      CABLE_DSL("Cable/DSL");
+
+      private final String name;
+
+      ConnectionType(String name) {
+          this.name = name;
+      }
+
+      @MaxMindDbCreator
+      public static ConnectionType fromString(String s) {
+          return switch (s) {
+              case "Dialup" -> DIALUP;
+              case "Cable/DSL" -> CABLE_DSL;
+              default -> null;
+          };
+      }
+  }
+  ```
+
 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/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
+) {}

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)) {

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 {
+}

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
         );