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 "before delete" 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 always receive the entity as it was sent to the database (after the corresponding "before" transformation), not the entity as it exists in the database after the operation. Database-generated values such as auto-incremented primary keys, version increments, or default column values are not reflected. This applies to all repository methods, including the *AndFetch variants; the fetched entity is only returned to the caller, not passed to the callback.

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
    afterDelete(E entity)
    Called after an entity has been successfully deleted from the database.
    default void
    afterInsert(E entity)
    Called after an entity has been successfully inserted into 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 void
    beforeDelete(E entity)
    Called before an entity is deleted from the database.
    default E
    beforeInsert(E entity)
    Called before an entity is inserted into 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(@Nonnull 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(@Nonnull 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(@Nonnull E entity)
      Called after an entity has been successfully inserted into the database.

      The entity passed to this method is the entity as it was sent to the database (after beforeInsert(E) transformation). Database-generated values such as auto-incremented primary keys or default column values are not reflected.

      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(@Nonnull E entity)
      Called after an entity has been successfully updated in the database.

      The entity passed to this method is the entity as it was sent to the database (after beforeUpdate(E) transformation). Database-side changes such as version increments or trigger-applied modifications are not reflected.

      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(@Nonnull 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(@Nonnull 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 is the entity as it was sent to the database (after beforeUpsert(E) transformation). Database-generated values are not reflected.

      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.

    • beforeDelete

      default void beforeDelete(@Nonnull E entity)
      Called before an entity is deleted from the database.
      Parameters:
      entity - the entity about to be deleted; never null.

    • afterDelete

      default void afterDelete(@Nonnull E entity)
      Called after an entity has been successfully deleted from the database.
      Parameters:
      entity - the entity that was deleted; never null.