Fix enum pointer decoding with @MaxMindDbCreator

When an enum with @MaxMindDbCreator was accessed via a pointer in the
database, decoding failed with ConstructorNotFoundException. This
affected enums like ConnectionType in GeoIP2 when data was deduplicated
via pointers.

The bug was in requiresLookupContext() which called
loadConstructorMetadata() before checking for creator methods. Enums
don't have usable public constructors, causing the exception.

Fix:
- Add cls.isEnum() to early-return checks (zero overhead for enums)
- Add @MaxMindDbCreator check for non-enum classes with creators
- Add negative caching to getCachedCreator() to avoid repeated method
  scanning for classes without creators

Fixes: maxmind/GeoIP2-java#644

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: oschwald

CHANGELOG.md

@@ -1,6 +1,14 @@
 CHANGELOG
 =========
 
+4.0.2
+------------------
+
+* Fixed a bug where enums with `@MaxMindDbCreator` would throw
+  `ConstructorNotFoundException` when the data was stored via a pointer
+  in the database. This commonly occurred with deduplicated data in larger
+  databases. Reported by Fabrice Bacchella. GitHub #644 in GeoIP2-java.
+
 4.0.1 (2025-12-02)
 ------------------
 

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

@@ -30,6 +30,9 @@ class Decoder {
 
     private static final int[] POINTER_VALUE_OFFSETS = {0, 0, 1 << 11, (1 << 19) + (1 << 11), 0};
 
+    // Sentinel to cache "no creator method exists" to avoid repeated method scanning
+    private static final CachedCreator NO_CREATOR = new CachedCreator(null, null);
+
     private final NodeCache cache;
 
     private final long pointerBase;
@@ -184,10 +187,17 @@ private boolean requiresLookupContext(Class<?> cls) {
             || cls.equals(Object.class)
             || Map.class.isAssignableFrom(cls)
             || List.class.isAssignableFrom(cls)
+            || cls.isEnum()
             || isSimpleType(cls)) {
             return false;
         }
 
+        // Non-enum classes with @MaxMindDbCreator don't require lookup context
+        // since they just convert simple values (strings, booleans, etc.)
+        if (getCachedCreator(cls) != null) {
+            return false;
+        }
+
         var cached = getCachedConstructor(cls);
         if (cached == null) {
             cached = loadConstructorMetadata(cls);
@@ -960,14 +970,15 @@ private Object convertValue(Object value, Class<?> targetType) {
 
     private CachedCreator getCachedCreator(Class<?> cls) {
         CachedCreator cached = this.creators.get(cls);
+        if (cached == NO_CREATOR) {
+            return null;  // Known to have no creator
+        }
         if (cached != null) {
             return cached;
         }
 
         CachedCreator creator = findCreatorMethod(cls);
-        if (creator != null) {
-            this.creators.putIfAbsent(cls, creator);
-        }
+        this.creators.putIfAbsent(cls, creator != null ? creator : NO_CREATOR);
         return creator;
     }
 

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

@@ -2042,6 +2042,110 @@ private void testIpV6(Reader reader, File file) throws IOException {
         }
     }
 
+    // =========================================================================
+    // Tests for enum with @MaxMindDbCreator when data is stored via pointer
+    // See: https://github.com/maxmind/GeoIP2-java/issues/644
+    // =========================================================================
+
+    /**
+     * Enum with @MaxMindDbCreator for converting string values.
+     * This simulates how ConnectionType enum works in geoip2.
+     */
+    enum ConnectionTypeEnum {
+        DIALUP("Dialup"),
+        CABLE_DSL("Cable/DSL"),
+        CORPORATE("Corporate"),
+        CELLULAR("Cellular"),
+        SATELLITE("Satellite"),
+        UNKNOWN("Unknown");
+
+        private final String name;
+
+        ConnectionTypeEnum(String name) {
+            this.name = name;
+        }
+
+        @MaxMindDbCreator
+        public static ConnectionTypeEnum fromString(String s) {
+            if (s == null) {
+                return UNKNOWN;
+            }
+            return switch (s) {
+                case "Dialup" -> DIALUP;
+                case "Cable/DSL" -> CABLE_DSL;
+                case "Corporate" -> CORPORATE;
+                case "Cellular" -> CELLULAR;
+                case "Satellite" -> SATELLITE;
+                default -> UNKNOWN;
+            };
+        }
+    }
+
+    /**
+     * Model class that uses the ConnectionTypeEnum for the connection_type field.
+     */
+    static class TraitsModel {
+        ConnectionTypeEnum connectionType;
+
+        @MaxMindDbConstructor
+        public TraitsModel(
+            @MaxMindDbParameter(name = "connection_type")
+            ConnectionTypeEnum connectionType
+        ) {
+            this.connectionType = connectionType;
+        }
+    }
+
+    /**
+     * Top-level model for Enterprise database records.
+     */
+    static class EnterpriseModel {
+        TraitsModel traits;
+
+        @MaxMindDbConstructor
+        public EnterpriseModel(
+            @MaxMindDbParameter(name = "traits")
+            TraitsModel traits
+        ) {
+            this.traits = traits;
+        }
+    }
+
+    /**
+     * This test passes because IP 74.209.24.0 has connection_type stored inline.
+     */
+    @ParameterizedTest
+    @MethodSource("chunkSizes")
+    public void testEnumCreatorWithInlineData(int chunkSize) throws IOException {
+        try (var reader = new Reader(getFile("GeoIP2-Enterprise-Test.mmdb"), chunkSize)) {
+            var ip = InetAddress.getByName("74.209.24.0");
+            var result = reader.get(ip, EnterpriseModel.class);
+            assertNotNull(result);
+            assertNotNull(result.traits);
+            assertEquals(ConnectionTypeEnum.CABLE_DSL, result.traits.connectionType);
+        }
+    }
+
+    /**
+     * This test verifies that enums with @MaxMindDbCreator work correctly when
+     * the data is stored via a pointer (common for deduplication in databases).
+     *
+     * <p>Previously, this would throw ConstructorNotFoundException because
+     * requiresLookupContext() called loadConstructorMetadata() before checking
+     * for creator methods.
+     */
+    @ParameterizedTest
+    @MethodSource("chunkSizes")
+    public void testEnumCreatorWithPointerData(int chunkSize) throws IOException {
+        try (var reader = new Reader(getFile("GeoIP2-Enterprise-Test.mmdb"), chunkSize)) {
+            var ip = InetAddress.getByName("89.160.20.112");
+            var result = reader.get(ip, EnterpriseModel.class);
+            assertNotNull(result);
+            assertNotNull(result.traits);
+            assertEquals(ConnectionTypeEnum.CORPORATE, result.traits.connectionType);
+        }
+    }
+
     static File getFile(String name) {
         return new File(ReaderTest.class.getResource("/maxmind-db/test-data/" + name).getFile());
     }