feat: add MapperType enum and mapper() config option (#4192)

- Create MapperType enum (LEGACY, CRITTER) in dev.morphia.mapping
- Add mapper() method to MorphiaConfig interface with default LEGACY
- Add mapper field to ManualMorphiaConfig with getter and copy constructor support
- Update ManualMorphiaConfig.toString() to include mapper field

Implements task 1 (MapperType enum) and task 2 (mapper() config) from issue #4184.

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

Author: evanchooly

core/src/main/java/dev/morphia/config/ManualMorphiaConfig.java

@@ -8,6 +8,7 @@
 
 import dev.morphia.mapping.DateStorage;
 import dev.morphia.mapping.DiscriminatorFunction;
+import dev.morphia.mapping.MapperType;
 import dev.morphia.mapping.NamingStrategy;
 import dev.morphia.mapping.PropertyDiscovery;
 import dev.morphia.query.DefaultQueryFactory;
@@ -43,6 +44,7 @@ public class ManualMorphiaConfig implements MorphiaConfig {
     String discriminatorKey;
     Boolean enablePolymorphicQueries;
     Boolean ignoreFinals;
+    MapperType mapper;
     List<String> packages;
     PropertyDiscovery propertyDiscovery;
     List<PropertyAnnotationProvider<?>> propertyAnnotationProviders;
@@ -72,6 +74,7 @@ public ManualMorphiaConfig(MorphiaConfig base) {
         discriminatorKey = base.discriminatorKey();
         enablePolymorphicQueries = base.enablePolymorphicQueries();
         ignoreFinals = base.ignoreFinals();
+        mapper = base.mapper();
         packages = new ArrayList<>(base.packages());
         propertyDiscovery = base.propertyDiscovery();
         propertyNaming = base.propertyNaming();
@@ -99,11 +102,11 @@ public static ManualMorphiaConfig configure(MorphiaConfig base) {
     public String toString() {
         return ("MorphiaConfig{applyCaps=%s, applyDocumentValidations=%s, applyIndexes=%s, database='%s', codecProvider=%s, " +
                 "collectionNaming=%s, dateStorage=%s, discriminator=%s, discriminatorKey='%s', enablePolymorphicQueries=%s, " +
-                "ignoreFinals=%s, packages=%s, propertyDiscovery=%s, propertyNaming=%s, queryFactory=%s, " +
+                "ignoreFinals=%s, mapper=%s, packages=%s, propertyDiscovery=%s, propertyNaming=%s, queryFactory=%s, " +
                 "storeEmpties=%s, storeNulls=%s}").formatted(
                         applyCaps(), applyDocumentValidations(), applyIndexes(), database(), codecProvider(), collectionNaming(),
-                        dateStorage(), discriminator(), discriminatorKey(), enablePolymorphicQueries(), ignoreFinals(), packages(),
-                        propertyDiscovery(), propertyNaming(), queryFactory(), storeEmpties(), storeNulls());
+                        dateStorage(), discriminator(), discriminatorKey(), enablePolymorphicQueries(), ignoreFinals(), mapper(),
+                        packages(), propertyDiscovery(), propertyNaming(), queryFactory(), storeEmpties(), storeNulls());
     }
 
     @Override
@@ -160,6 +163,11 @@ public Boolean ignoreFinals() {
         return orDefault(ignoreFinals, FALSE);
     }
 
+    @Override
+    public MapperType mapper() {
+        return orDefault(mapper, MapperType.LEGACY);
+    }
+
     @Override
     public List<String> packages() {
         return orDefault(packages, List.of());

core/src/main/java/dev/morphia/config/MorphiaConfig.java

@@ -16,6 +16,7 @@
 import dev.morphia.config.converters.QueryFactoryConverter;
 import dev.morphia.mapping.DateStorage;
 import dev.morphia.mapping.DiscriminatorFunction;
+import dev.morphia.mapping.MapperType;
 import dev.morphia.mapping.NamingStrategy;
 import dev.morphia.mapping.PropertyDiscovery;
 import dev.morphia.query.QueryFactory;
@@ -357,6 +358,30 @@ default MorphiaConfig legacy() {
 
     }
 
+    /**
+     * The mapper implementation to use. Defaults to {@link MapperType#LEGACY} (reflection-based).
+     * Set to {@link MapperType#CRITTER} to use the bytecode-generated mapper (requires critter dependencies).
+     *
+     * @return the mapper type to use
+     * @since 3.0
+     */
+    @WithDefault("legacy")
+    MapperType mapper();
+
+    /**
+     * Updates this configuration with a new value and returns a new instance. The original instance is unchanged.
+     *
+     * @param value the new value
+     * @return a new instance with the updated configuration
+     * @since 3.0
+     */
+    default MorphiaConfig mapper(MapperType value) {
+        var newConfig = new ManualMorphiaConfig(this);
+
+        newConfig.mapper = value;
+        return newConfig;
+    }
+
     /**
      * A comma delimited list of packages that Morphia should map. If subpackages of a specific package should also be mapped, simply add
      * a '*' to the end of the package name. e.g., 'com.foo.bar.*'

core/src/main/java/dev/morphia/mapping/MapperType.java

@@ -0,0 +1,18 @@
+package dev.morphia.mapping;
+
+/**
+ * Selects the mapper implementation Morphia uses to map entity classes.
+ *
+ * @since 3.0
+ */
+public enum MapperType {
+    /**
+     * The default reflection-based mapper.
+     */
+    LEGACY,
+
+    /**
+     * The bytecode-generated mapper using critter. Requires critter dependencies on the classpath.
+     */
+    CRITTER
+}