Module storm.foundation
Package st.orm

Interface EntityCallback<E extends Entity<?>>

Type Parameters:
E - the entity type this callback applies to. Use Entity<?> to match all entity types.
public interface EntityCallback<E extends Entity<?>>
Typed callback interface for entity lifecycle events.

The type parameter E determines which entity type this callback applies to. The framework automatically resolves the type parameter at runtime and only invokes the callback for matching entity types. Use EntityCallback<Entity<?>> to create a global callback that fires for all entities.

The "before" callbacks for insert, update, and upsert return the (potentially transformed) entity to persist, which is essential for immutable record-based entities that cannot be mutated in place. The "after" callbacks and beforeRemove(E) are observers that do not affect the persisted data.

Upsert callback routing

An upsert operation may be executed as a SQL-level upsert (e.g., INSERT ... ON CONFLICT, MERGE), or it may be routed to a plain insert or update depending on the entity's primary key state and the database dialect. The callbacks that fire depend on which path is taken:

Exactly one pair of callbacks fires per entity; they are never combined.

"After" callback entity state

The "after" callbacks observe what the calling method reports to its caller:

  • Methods that return nothing (insert, update, upsert) report the entity as it was sent to the database, after the corresponding "before" transformation. No key is read back, so a database-generated primary key is not reflected.
  • The *AndFetchId methods report that same entity carrying the primary key the database assigned.
  • The *AndFetch methods report the entity as read back from the database, reflecting generated keys, column defaults, version increments and trigger-applied changes.

A callback that needs the primary key must therefore be driven by a method that reports one. Selecting the method is the caller's choice: the callback receives exactly what the caller receives, and no more.

All methods have default no-op implementations, so users only need to override the hooks they care about.

Typical use cases include auditing (setting created/updated timestamps), validation, and logging.

Since:
1.9

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    afterInsert(E entity)
    Called after an entity has been successfully inserted into the database.
    default void
    afterRemove(E entity)
    Called after an entity has been successfully removed from the database.
    default void
    afterUpdate(E entity)
    Called after an entity has been successfully updated in the database.
    default void
    afterUpsert(E entity)
    Called after an entity has been successfully upserted via a SQL-level upsert statement.
    default E
    beforeInsert(E entity)
    Called before an entity is inserted into the database.
    default void
    beforeRemove(E entity)
    Called before an entity is removed from the database.
    default E
    beforeUpdate(E entity)
    Called before an entity is updated in the database.
    default E
    beforeUpsert(E entity)
    Called before an entity is upserted via a SQL-level upsert statement (e.g., INSERT ... ON CONFLICT, MERGE).

  • Method Details

    • beforeInsert

      default E beforeInsert(E entity)
      Called before an entity is inserted into the database.

      The returned entity is the one that will actually be persisted. Implementations may return a modified copy of the entity (e.g., with audit fields populated) or the original entity unchanged.

      This callback also fires when an upsert operation is routed to an insert (e.g., for auto-generated primary keys on databases that cannot perform a SQL-level upsert with generated keys).

      Parameters:
      entity - the entity about to be inserted; never null.
      Returns:
      the entity to insert; never null.

    • beforeUpdate

      default E beforeUpdate(E entity)
      Called before an entity is updated in the database.

      The returned entity is the one that will actually be persisted. Implementations may return a modified copy of the entity (e.g., with an updated timestamp) or the original entity unchanged.

      This callback also fires when an upsert operation is routed to an update (i.e., when the entity has an auto-generated primary key with a non-default value, indicating it was previously inserted).

      Parameters:
      entity - the entity about to be updated; never null.
      Returns:
      the entity to update; never null.

    • afterInsert

      default void afterInsert(E entity)
      Called after an entity has been successfully inserted into the database.

      The entity passed to this method reflects what the calling method reports: the entity as sent for insert, the entity carrying its generated primary key for insertAndFetchId(s), and the row as read back for insertAndFetch.

      This callback also fires when an upsert operation is routed to an insert.

      Parameters:
      entity - the entity that was inserted; never null.

    • afterUpdate

      default void afterUpdate(E entity)
      Called after an entity has been successfully updated in the database.

      The entity passed to this method reflects what the calling method reports: the entity as sent for update, and the row as read back for updateAndFetch. Only the latter reflects database-side changes such as version increments or trigger-applied modifications.

      This callback also fires when an upsert operation is routed to an update.

      Parameters:
      entity - the entity that was updated; never null.

    • beforeUpsert

      default E beforeUpsert(E entity)
      Called before an entity is upserted via a SQL-level upsert statement (e.g., INSERT ... ON CONFLICT, MERGE).

      This callback only fires when the upsert is executed as a SQL-level upsert. When the operation is routed to a plain insert or update, beforeInsert(E) or beforeUpdate(E) fires instead.

      The returned entity is the one that will actually be persisted. By default, this delegates to beforeInsert(Entity), so that insert callbacks automatically cover the upsert path. Override this method to provide upsert-specific behavior.

      Parameters:
      entity - the entity about to be upserted; never null.
      Returns:
      the entity to upsert; never null.

    • afterUpsert

      default void afterUpsert(E entity)
      Called after an entity has been successfully upserted via a SQL-level upsert statement.

      This callback only fires when the upsert is executed as a SQL-level upsert. When the operation is routed to a plain insert or update, afterInsert(E) or afterUpdate(E) fires instead.

      The entity passed to this method reflects what the calling method reports: the entity as sent for upsert, the entity carrying its generated primary key for upsertAndFetchId(s), and the row as read back for upsertAndFetch.

      By default, this delegates to afterInsert(Entity), so that insert callbacks automatically cover the upsert path. Override this method to provide upsert-specific behavior.

      Parameters:
      entity - the entity that was upserted; never null.

    • beforeRemove

      default void beforeRemove(E entity)
      Called before an entity is removed from the database.

      Fires where the operation carries an entity, so remove(entity) and its collection and stream forms trigger it. removeById, removeByRef, removeAll and the delete() query builder identify rows by key or by predicate rather than by entity, so there is no entity to pass and this callback does not fire. A callback that throws in order to block a removal therefore blocks only the paths that carry an entity, and is not an enforcement point.

      Parameters:
      entity - the entity about to be removed; never null.

    • afterRemove

      default void afterRemove(E entity)
      Called after an entity has been successfully removed from the database.

      As with beforeRemove(E), fires only where the operation carries an entity.

      Parameters:
      entity - the entity that was removed; never null.