Phase 1: Extract Mapper interface and add MapperType config option

[evanchooly]

Summary

• Converts Mapper.java from a concrete class to a @MorphiaInternal interface
• Extracts AbstractMapper with all shared entity registration, lookup, and lifecycle logic
• Creates ReflectiveMapper extends AbstractMapper — the current reflection-based implementation
• Adds MapperType enum (LEGACY, CRITTER) to dev.morphia.mapping
• Adds mapper() method to MorphiaConfig (default: LEGACY) and ManualMorphiaConfig
• Updates MorphiaDatastore to use a createMapper() factory method (wired for Phase 4/5)
• Adds invalid.mapper.config message to sofia.properties

This is the foundation for the CritterMapper integration. All 1,166 existing tests pass unchanged since everything continues to use ReflectiveMapper via the LEGACY default.

Closes #4184
Part of #4179

Test plan

• ./mvnw install -pl :morphia-core -am -DskipTests -Ddeploy.skip=true — clean compile
• ./mvnw test -pl :morphia-core -Ddeploy.skip=true — 1166 tests pass, 1 skipped (pre-existing)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR lays the groundwork for the planned CritterMapper integration by making Mapper an internal interface, moving shared mapping/registration logic into a new AbstractMapper, and routing mapper selection through configuration (defaulting to the legacy reflection-based implementation).

Changes:

• Refactors Mapper from a concrete class into a @MorphiaInternal interface and extracts shared logic into AbstractMapper.
• Introduces ReflectiveMapper as the legacy reflection-based implementation and updates MorphiaDatastore to create mappers via a factory method.
• Adds MapperType and a new MorphiaConfig.mapper() configuration option (plus docs + Sofia message updates).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/modules/ROOT/examples/complete-morphia-config.properties	Documents the new morphia.mapper config option and possible values.
core/src/test/java/dev/morphia/test/mapping/TestMapper.java	Updates mapper cloning test to use Mapper.copy() now that Mapper is an interface.
core/src/main/resources/sofia.properties	Adds a message key intended for invalid mapper configuration handling.
core/src/main/java/dev/morphia/mapping/Mapper.java	Converts Mapper to an internal interface, defining the mapper contract.
core/src/main/java/dev/morphia/mapping/AbstractMapper.java	New shared base class holding most of the previous Mapper implementation logic.
core/src/main/java/dev/morphia/mapping/ReflectiveMapper.java	New legacy reflection-based mapper implementation extending AbstractMapper.
core/src/main/java/dev/morphia/MorphiaDatastore.java	Switches datastore to create the mapper via createMapper(config) and wires in mapper() selection.
core/src/main/java/dev/morphia/mapping/MapperType.java	Adds the MapperType enum (LEGACY, CRITTER) for config-driven selection.
core/src/main/java/dev/morphia/config/MorphiaConfig.java	Adds mapper() with default legacy and a fluent updater mapper(MapperType).
core/src/main/java/dev/morphia/config/ManualMorphiaConfig.java	Stores and defaults the new mapper config field to MapperType.LEGACY.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.