Module storm.foundation
Package st.orm

Annotation Interface DynamicUpdate

@Target(TYPE) @Retention(RUNTIME) public @interface DynamicUpdate
Configures how changes are detected and how UPDATE statements are generated for a specific entity.

@DynamicUpdate controls how changes observed within a transaction are interpreted and how UPDATE statements are constructed for the annotated entity.

The configuration has two independent concerns:

  • The UpdateMode determines when an UPDATE is issued and whether it updates the whole entity or only individual columns.
  • The dirty checking strategy determines how a change is detected for a column.

@DynamicUpdate primarily affects performance and write behavior. It does not provide a strict correctness guarantee. Correctness under concurrent updates must be enforced using optimistic locking, for example via a version column.

If not specified, the default UpdateMode applies. The default can be configured via the storm.update.default_mode property (see StormConfig). If the property is not set, the default update mode is UpdateMode.ENTITY.

The dirty checking strategy can be configured separately. By default, dirty checking is instance-based, meaning that reference changes are detected using instance identity rather than semantic value comparison.

Value-based dirty checking can be enabled via the storm.update.dirty_check property (see StormConfig), or per entity via this annotation.

For example, replacing a referenced entity with a different instance that has the same identifier is considered a change when instance-based dirty checking is used.

Dirty checking is evaluated for the entity's updatable columns. Fields that are not updatable are ignored.

When available, generated metamodel implementations (Java annotation processor / Kotlin KSP) are used to perform type-specific comparisons that avoid reflective access and prevent boxing for primitive fields. If no generated metamodel is available, reflective accessors are used.

General rules

  • Dirty checking applies to entities read within a transaction context.
  • Dirty checking is applied only 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. This does not affect dirty detection.
  • Unless configured otherwise, entity observation is automatically disabled for READ_UNCOMMITTED transactions. At this isolation level, the application expects to see uncommitted changes from other transactions. Caching observed state would mask these changes, contradicting the requested isolation semantics. When observation is disabled, all entities are treated as dirty, resulting in full-row updates.
Since:
1.7

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    UpdateMode
    value
    Defines how changes are detected and how UPDATE statements are generated for the annotated entity.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    DirtyCheck
    dirtyCheck
    Defines how dirty checking is performed for this entity.

  • Element Details

    • value

      UpdateMode value
      Defines how changes are detected and how UPDATE statements are generated for the annotated entity.

      If set to UpdateMode.OFF, all mapped columns are always updated.

      If set to UpdateMode.ENTITY, dirty checking is evaluated per updatable column. A full-row UPDATE is issued if any column is considered dirty. If no column changes are detected, the UPDATE is skipped.

      If set to UpdateMode.FIELD, dirty checking is evaluated per updatable column and only the columns considered dirty are included in the UPDATE.

    • dirtyCheck

      DirtyCheck dirtyCheck
      Defines how dirty checking is performed for this entity.

      This setting controls whether changes are detected based on instance identity or semantic value comparison.

      If set to DirtyCheck.DEFAULT, the configured dirty check strategy applies. The default can be configured via the storm.update.dirty_check property (see StormConfig).

      This setting only affects dirty detection. It does not change the selected UpdateMode.

      Default:
      DEFAULT