Skip to main content

Nullity

Jimmer handles the issue of whether entity object properties can be null in a very strict way. Even for Java developers, it requires thinking about whether each property can be null in the same way as Kotlin developers.

caution

Explicitly stating whether each property of the entity object allows null is very important for Jimmer and affects many features.

Define nullity of properties​

Kotlin​

Kotlin supports null safety. Declaring entity properties as T for non-null and T? for nullable according to Kotlin's own way.

Java​

Whether a property is null in Java is determined by the following rules:

  • If the property type is boolean, char, byte, short, int, long, float or double, then it is non-null.

  • If the property type is Boolean, Character, Byte, Short, Integer, Long, Float or Double, then it is nullable.

  • Otherwise

    • If the property is decorated by any annotation simply named Nullable or Null, then it is nullable.

    • Otherwise, the default is non-null.

    note

    It is recommended to use org.jetbrains.annotations.Nullable, because

    • Although recognizable annotations are not restricted, if an annotation not included by default in the Jimmer annotation processor is used, its dependency needs to be added to the annotation processor, which is troublesome after all.

    • org.jetbrains.annotations.Nullable is supported by Intellij.

Precautions​

info

A series of concepts not explained yet will appear here. They will all be explained in subsequent documents.

Here is just a simple list of precautions. Please ignore these terms for now. This document does not provide related examples either. Come back and check after you understand all subsequent concepts.

  • The @Id property must be non-null.

    Very different from JPA/Hibernate.

    • JPA/Hibernate recommends declaring the id property as a nullable type, e.g. Long instead of long in Java, so that the absence of id and the need for automatic allocation can be expressed when saving data.

    • Jimmer must declare the id property as a non-null type, e.g. long instead of Long in Java. Jimmer relies on the dynamism of the entity objects themselves to express the absence of the id property.

  • One-to-many and many-to-many properties must be non-null.

    One-to-many and many-to-many properties are represented by collections of length 0 instead of null when there is no data.

  • One-to-one and many-to-one properties must be nullable when any of the following conditions is met:

    • Mapping based on join table, rather than foreign key

    • Mapping based on pseudo foreign key, rather than real foreign key

      info

      A "pseudo foreign key" refers to a foreign key in the developer's mind, but there is no corresponding foreign key constraint in the database.

    • Remote association

    • As the mirror side of @OneToOne association

  • If the associated entity has global filters applied, then for one-to-one/many-to-one associations must be nullable even if they are directly based on foreign keys, unless all of the following conditions are met:

    • All global filters applied to the associated entity implement the AssociationIntegrityAssuranceFilter/KAssociationIntegrityAssuranceFilter interface.

    • All global filters applied to the associated entity are also applied to the current entity.

inputNotNull​

As mentioned before, due to some query scenarios, one-to-one and many-to-one properties based on foreign keys must be declared as nullable.

However, when saving data, developers may not expect users to modify the foreign key fields in the database to null. In this case, inputNotNull of @OneToOne or @ManyToOne can be set to true, for example:

  • @OneToOne(inputNotNull = true)
  • @ManyToOne(inputNotNull = true)

If inputNotNull is configured for an associated property, it will be given priority consideration in database validation to verify that the foreign key field in the database cannot be null.