Module storm.foundation
Package st.orm

Enum Class UpdateMode

java.lang.Object
java.lang.Enum<UpdateMode>
st.orm.UpdateMode
All Implemented Interfaces:
Serializable, Comparable<UpdateMode>, Constable
public enum UpdateMode extends Enum<UpdateMode>
Controls how changes are detected and how UPDATE statements are generated for entities.

UpdateMode primarily affects performance, but it also influences how likely concurrent updates are to overwrite each other. It does not provide a strict correctness guarantee under concurrency. Correctness must be enforced using optimistic locking via a version column.

In practice, more precise update modes, especially field-level updates, often reduce the chance of lost updates by limiting which columns are written. This improvement is situational and must not be relied upon as a formal correctness mechanism.

The default update mode is ENTITY. A different default can be configured via the storm.update.default_mode property (see StormConfig). The update mode can also be configured per entity using DynamicUpdate.

General rules

  • Dirty checking applies to entities read within a transaction context.
  • Application of dirty checking is limited to updates performed via the entity repository.
  • Manual or bulk SQL updates bypass dirty checking and may leave cached entities stale.
  • Field-level updates are a performance optimization and may fall back to full-row updates to preserve batching efficiency.
Since:
1.7

  • Enum Constant Details

    • OFF

      public static final UpdateMode OFF
      Dirty checking is disabled.

      All mapped columns are always included in UPDATE statements. No comparisons are performed.

      This mode provides predictable behavior, optimal batching, and minimal runtime overhead.

    • ENTITY

      public static final UpdateMode ENTITY
      Full-row updates with column-level dirty detection.

      Dirty checking is evaluated per updatable column against the state observed when the entity was read. If no column changes are detected, the UPDATE is skipped entirely. If any column is considered dirty, a full-row UPDATE is issued and all mapped columns are included.

      This mode reduces unnecessary UPDATE statements while keeping SQL shape stable. It does not reduce the number of updated columns when an UPDATE is issued.

      By skipping redundant writes, contention may be reduced and the probability of conflicting updates may be lowered. This effect is best-effort and must not be relied upon as a correctness mechanism.

      This is the default and recommended mode.

    • FIELD

      public static final UpdateMode FIELD
      Field-level updates with column-level dirty detection.

      Dirty checking is evaluated per updatable column against the state observed when the entity was read. UPDATE statements include only the columns considered dirty.

      This mode often reduces write amplification and lock scope. By limiting updates to changed columns, behavior under concurrent updates can improve, especially when different transactions modify different fields.

      These benefits are best-effort and situational. Field-level updates improve concurrency characteristics but do not guarantee correctness. Optimistic locking is still required to reliably detect conflicting updates.

      To prevent performance degradation, a fallback to full-row updates may be used when too many distinct update statement shapes would otherwise be generated.

  • Method Details

    • values

      public static UpdateMode[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static UpdateMode valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null