@Target(FIELD) @Retention(RUNTIME) public @interface IgnoreNullFromDB

Protects a field from null values during deserialization from the database.

Behavior Summary:

By default, Morphium accepts null values from the database and sets fields to null, even if they have default values. This annotation changes that behavior for specific fields that need protection from null contamination.

IMPORTANT: Field Missing vs. Field = null

Morphium distinguishes between two scenarios when reading from the database:

Field missing from DB document: The field key is not present in the document at all. In this case, the Java default value is ALWAYS preserved, regardless of this annotation.
Field present in DB with null value: The field key exists in the document but the value is null. This is where @IgnoreNullFromDB matters - it controls whether to accept or ignore the explicit null.

NOTE: Special Handling for @Id Fields

Fields annotated with Id are NEVER stored when null, regardless of this annotation. This is fundamental MongoDB behavior - if the _id field is missing, MongoDB auto-generates it. Storing _id as null would cause duplicate key errors.

Default Behavior (Without @IgnoreNullFromDB):

Serialization (Writing to DB): When a field value is null, the field is stored in the database with an explicit null value.
Deserialization (Reading from DB):
- Field missing from DB: Default value preserved
- Field in DB with null: Field set to null, overriding any default value

With @IgnoreNullFromDB:

Serialization (Writing to DB): When a field value is null, the field is omitted from the database document (not stored at all).
Deserialization (Reading from DB):
- Field missing from DB: Default value preserved
- Field in DB with null: Null value ignored, default value preserved (protected!)

Example:

@Entity
public class MyEntity {
    // Field without @IgnoreNullFromDB - standard behavior
    private String regularField;      // null values stored; null from DB accepted

    // Field with @IgnoreNullFromDB - protected from nulls
    @IgnoreNullFromDB
    private String protectedField;    // null values not stored; null from DB ignored

    // Field with default value, without @IgnoreNullFromDB
    private Integer counter = 42;     // Missing from DB: stays 42
                                      // null in DB: becomes null

    // Field with default value, with @IgnoreNullFromDB
    @IgnoreNullFromDB
    private Integer protectedCounter = 99; // Missing from DB: stays 99
                                           // null in DB: stays 99 (protected!)
}

Protection from Null Contamination:

Fields WITH @IgnoreNullFromDB are protected from null values in the database:

// Scenario 1: MongoDB document has: { counter: null }
// Without @IgnoreNullFromDB: counter becomes null
// With @IgnoreNullFromDB: counter stays at default (99)

// Scenario 2: MongoDB document has: { }  (field missing entirely)
// Without @IgnoreNullFromDB: counter stays at default (42)
// With @IgnoreNullFromDB: counter stays at default (99)
// -> Both cases preserve default when field is missing!

Use Cases:

This annotation is useful for:

Protecting fields from null contamination during data migrations or manual edits
Maintaining data integrity when documents are modified outside the application
Ensuring fields with meaningful default values are never overridden by null
Backward compatibility when introducing new fields with defaults to existing documents
Defensive programming against unexpected null values in the database

Autor:: stephan

Annotationsschnittstelle IgnoreNullFromDB