skip to content

Explain how MappingMongoConverter instantiates and populates entities on read, and the role of the _class type hint and persistence constructor. What edge cases arise?

level: principalimportance: nice to knowfreq 25%

answer

  1. persistence creator: single ctor / @PersistenceCreator / Kotlin primary
  2. ctor params bound by name, rest via field access (no setters needed)
  3. _class = FQCN type hint for polymorphism; @TypeAlias for stability
  4. missing field -> null/default; extra field -> ignored
  5. records/immutables need all state as ctor params

basics

~20 s

On read, MappingMongoConverter picks a persistence constructor (or default), maps constructor args from document fields, then sets remaining properties by field access. It writes a _class type hint so polymorphic/abstract types can be reconstructed. Immutable objects and missing/extra fields are the main edge cases.

solid answer

~50 s

When reading a document, MappingMongoConverter looks up the MongoPersistentEntity, chooses a persistence creator — a single constructor, or the one marked @PersistenceCreator (Kotlin: primary constructor) — and resolves each constructor parameter from the BSON by mapped field name, applying value converters. Remaining properties not covered by the constructor are populated via a PropertyAccessor, typically by direct field access (bypassing setters, even final fields), so entities need neither setters nor a no-arg constructor. To support polymorphism, on write it stores a _class field with the fully-qualified type name via DefaultMongoTypeMapper; on read it uses that to instantiate the concrete subtype. Edge cases: missing fields become null/defaults, extra document fields are ignored, immutable/record types must get everything through the constructor, renamed classes break _class resolution unless you configure type aliases, and null-vs-absent distinctions and generic/collection element types need care. You can customize the type hint via a custom MongoTypeMapper.

code

java · 23 lines
java
import org.springframework.data.annotation.Id;
import org.springframework.data.annotation.PersistenceCreator;
import org.springframework.data.annotation.TypeAlias;
import org.springframework.data.mongodb.core.mapping.Document;

@Document("payments")
@TypeAlias("payment")   // stored in _class instead of the FQCN -> survives class moves/renames
public final class Payment {

    @Id private final String id;
    private final long amountMinor;
    private final String currency;

    // Chosen as the persistence creator; params bound from the document by name.
    @PersistenceCreator
    public Payment(String id, long amountMinor, String currency) {
        this.id = id;
        this.amountMinor = amountMinor;
        this.currency = currency;
    }
    // Immutable: ALL persistent state must arrive via the constructor (no setters/field injection).
    // A field missing in the document binds to null/default; extra document fields are ignored.
}

go deeper

for a junior

Aware that Spring builds the object back from the stored document automatically.

for a middle

Knows a persistence constructor is used and setters aren't required.

for a senior

Explains constructor selection, field-access population, and the _class type hint for polymorphism.

for a principal

Designs for schema evolution and refactor-safety with @TypeAlias/custom MongoTypeMapper, reasons about immutability, Kotlin defaults, null-vs-absent, and generic erasure edge cases.

This is the deep mechanics of Spring Data MongoDB's read path, owned by `MappingMongoConverter` plus `MongoMappingContext`. **Step 1 — resolve the entity.** For a target type, the converter fetches the cached `MongoPersistentEntity` (a `PersistentEntity` with `MongoPersistentProperty` entries). This metadata knows the id, `@Field` names, associations (`@DBRef`/`@DocumentReference`), and which constructor to use. **Step 2 — pick the persistence creator.** Instantiation goes through an `EntityInstantiator`. Selection rules: - If there is exactly **one constructor**, it is used. - If multiple, the one annotated `@PersistenceCreator` (`org.springframework.data.annotation.PersistenceCreator`; older code used `@PersistenceConstructor`) is used. - A **no-arg** constructor is used if present and nothing else is chosen. - In **Kotlin**, the **primary constructor** is the default persistence creator. Spring can generate bytecode (via `ObjectInstantiator`) to invoke constructors quickly instead of reflection where possible. **Step 3 — bind constructor parameters.** For each constructor parameter, the converter finds the matching persistent property (by name / `@Field`) and reads its value from the `org.bson.Document`, running it through the conversion stack (simple type, custom `Converter`, nested entity, or association resolution). **Step 4 — populate remaining properties.** Properties **not** set through the constructor are written via a `PersistentPropertyAccessor`. Spring Data prefers **direct field access** using generated accessors/reflection, so it can set fields **without setters** and even set **final** fields. This is why domain objects don't need JavaBean setters or a no-arg constructor. **The _class type hint.** On **write**, `MappingMongoConverter` (through `DefaultMongoTypeMapper`, a `MongoTypeMapper`) stores a `_class` key containing the **fully-qualified class name** of the written object. On **read**, when a property is declared as an interface/abstract/base type or `Object`, the converter reads `_class` to instantiate the correct **concrete subtype** — enabling **polymorphism**. You can customize this: - Change the key name, or use **type aliases** (`@TypeAlias("...")`) so the stored value is a short stable alias instead of the FQCN — decoupling storage from class names. - Configure or disable it with a custom `MongoTypeMapper`/`DefaultMongoTypeMapper(null, ...)`, but **disabling breaks polymorphic reads** and can break reads after refactors. **Edge cases and gotchas:** 1. **Renaming/moving a class** changes the FQCN; old documents' `_class` no longer resolves. Mitigate with `@TypeAlias` from the start. 2. **Immutable types / records / Kotlin data classes** must receive **all** needed state via the constructor — anything not a constructor param can't be set afterward on a truly immutable object (final with no setter can still be field-injected for non-constructor props, but records forbid this). Records/`val` therefore should expose all persistent state as constructor params. 3. **Missing fields:** a document lacking a field yields `null` (or the type's default / Kotlin default parameter value if defined). Kotlin nullability + default params interact here — a non-null Kotlin property with no default and a missing field can throw. 4. **Extra fields** in the document not present on the class are simply ignored (no error), which aids schema evolution. 5. **Null vs absent:** by default nulls may be written; use `@Field(write = Field.Write.NON_NULL)` to omit nulls, but then reads can't distinguish null from absent. 6. **Generics/collections:** element types are resolved from declared generics; raw types or wildcards can lose the target type and fall back to `Document`/`LinkedHashMap`. 7. **Id handling:** the `_id` is bound to the `@Id`/`id` property; type mismatches (String vs ObjectId) surface here. 8. **`_class` bloat/leak:** storing FQCNs increases document size and leaks package structure; aliases mitigate both. **When this matters:** designing immutable domain models, evolving schemas over years, supporting inheritance hierarchies in one collection, or building a shared persistence layer where class refactors must not break stored data. The controls are `@PersistenceCreator`, `@TypeAlias`, and a custom `MongoTypeMapper`.

  • Why should you add @TypeAlias early in a project that stores an inheritance hierarchy?
    Because _class stores the fully-qualified class name; if you later rename or move the class, existing documents' _class no longer resolves and polymorphic reads break. @TypeAlias pins a short, stable identifier decoupled from the class's package/name, so refactors don't corrupt stored data.
  • How does Spring Data instantiate an immutable entity with a final id field and no setters?
    It selects a persistence constructor (single ctor or @PersistenceCreator; Kotlin primary), binds each parameter from the document by mapped name, and constructs the object with those values. Non-constructor properties would be set by field access, but for a fully-immutable type all state must come through the constructor.
  • What happens on read if a document has a field the class doesn't declare?
    It is silently ignored. This tolerance supports schema evolution — adding fields in the DB doesn't break older code, and removing a class field just drops that data on the next write.

saying these in an interview costs you the question

  • Believing entities require a public no-arg constructor and setters.
  • Assuming the _class hint is optional cosmetic data — removing it breaks polymorphic reads.
  • Thinking class renames are safe when documents store the FQCN in _class.
  • Expecting an exception when the document has extra/unknown fields (it doesn't).

context

resolving links…