Package org.hibernate

Interface Interceptor

All Known Implementing Classes:
EmptyInterceptor
public interface Interceptor
Allows user code to inspect and/or change entity property values before they are written to the database, or after they are read from the database.

The Session may not be invoked from a callback (nor may a callback cause a collection or proxy to be lazily initialized).

There might be a single instance of Interceptor for a SessionFactory, or a new instance might be created for each Session. Use:

Whichever approach is used, the interceptor must be serializable for the Session to be serializable. This means that SessionFactory-scoped interceptors should implement readResolve().

See Also:
API Note:
This venerable callback interface, dating from the very earliest days of Hibernate, competes with standard JPA entity listener callbacks: PostLoad, PrePersist, PreUpdate, and PreRemove. However, JPA callbacks do not provide the ability to access the previous value of an updated property in a @PreUpdate callback, and do not provide a well-defined way to intercept changes to collections.

Note that this API exposes the interface Type, which in modern versions of Hibernate is considered an SPI. This is unfortunate, and might change in the future, but is bearable for now.

  • Method Details

    • onLoad

      default boolean onLoad(Object entity, Object id, Object[] state, String[] propertyNames, Type[] types)
      Called just before an object is initialized. The interceptor may change the state, which will be propagated to the persistent object. Note that when this method is called, entity will be an empty uninitialized instance of the class.
      Parameters:
      entity - The entity instance being loaded
      id - The identifier value being loaded
      state - The entity state (which will be pushed into the entity instance)
      propertyNames - The names of the entity properties, corresponding to the state.
      types - The types of the entity properties, corresponding to the state.
      Returns:
      true if the user modified the state in any way.
      API Note:
      The indexes across the state, propertyNames, and types arrays match.

    • onPersist

      default boolean onPersist(Object entity, Object id, Object[] state, String[] propertyNames, Type[] types)
      Called before an object is made persistent by a stateful session.

      The interceptor may modify the state, which will be used for the SQL INSERT and propagated to the persistent object.

      Parameters:
      entity - The entity instance whose state is being inserted
      id - The identifier of the entity
      state - The state of the entity which will be inserted
      propertyNames - The names of the entity properties.
      types - The types of the entity properties
      Returns:
      true if the user modified the state in any way.
      See Also:

    • onRemove

      default void onRemove(Object entity, Object id, Object[] state, String[] propertyNames, Type[] types)
      Called before an object is removed by a stateful session.

      It is not recommended that the interceptor modify the state.

      Parameters:
      entity - The entity instance being deleted
      id - The identifier of the entity
      state - The state of the entity
      propertyNames - The names of the entity properties.
      types - The types of the entity properties
      See Also:

    • onFlushDirty

      default boolean onFlushDirty(Object entity, Object id, Object[] currentState, Object[] previousState, String[] propertyNames, Type[] types)
      Called when an object is detected to be dirty, during a flush. The interceptor may modify the detected currentState, which will be propagated to both the database and the persistent object. Note that not all flushes end in actual synchronization with the database, in which case the new currentState will be propagated to the object, but not necessarily (immediately) to the database. It is strongly recommended that the interceptor not modify the previousState.
      Parameters:
      entity - The entity instance detected as being dirty and being flushed
      id - The identifier of the entity
      currentState - The entity's current state
      previousState - The entity's previous (load time) state.
      propertyNames - The names of the entity properties
      types - The types of the entity properties
      Returns:
      true if the user modified the currentState in any way.
      See Also:
      API Note:
      The indexes across the currentState, previousState, propertyNames, and types arrays match.

    • onSave

      @Deprecated(since="6.6") default boolean onSave(Object entity, Object id, Object[] state, String[] propertyNames, Type[] types)
      Deprecated.
      Use onPersist(Object, Object, Object[], String[], Type[])
      Called before an object is made persistent by a stateful session.

      The interceptor may modify the state, which will be used for the SQL INSERT and propagated to the persistent object.

      Parameters:
      entity - The entity instance whose state is being inserted
      id - The identifier of the entity
      state - The state of the entity which will be inserted
      propertyNames - The names of the entity properties.
      types - The types of the entity properties
      Returns:
      true if the user modified the state in any way.
      See Also:

    • onDelete

      @Deprecated(since="6.6") default void onDelete(Object entity, Object id, Object[] state, String[] propertyNames, Type[] types)
      Deprecated.
      Use onRemove(Object, Object, Object[], String[], Type[])
      Called before an object is removed by a stateful session.

      It is not recommended that the interceptor modify the state.

      Parameters:
      entity - The entity instance being deleted
      id - The identifier of the entity
      state - The state of the entity
      propertyNames - The names of the entity properties.
      types - The types of the entity properties
      See Also:

    • onCollectionRecreate

      default void onCollectionRecreate(Object collection, Object key)
      Called before a collection is (re)created.
      Parameters:
      collection - The collection instance.
      key - The collection key value.

    • onCollectionRemove

      default void onCollectionRemove(Object collection, Object key)
      Called before a collection is deleted.
      Parameters:
      collection - The collection instance.
      key - The collection key value.

    • onCollectionUpdate

      default void onCollectionUpdate(Object collection, Object key)
      Called before a collection is updated.
      Parameters:
      collection - The collection instance.
      key - The collection key value.

    • preFlush

      default void preFlush(Iterator<Object> entities)
      Called before a flush.
      Parameters:
      entities - The entities to be flushed.

    • postFlush

      default void postFlush(Iterator<Object> entities)
      Called after a flush that actually ends in execution of the SQL statements required to synchronize in-memory state with the database.
      Parameters:
      entities - The entities that were flushed.

    • isTransient

      default Boolean isTransient(Object entity)
      Called to distinguish between transient and detached entities. The return value determines the state of the entity with respect to the current session. This method should return:
      • Boolean.TRUE if the entity is transient,
      • Boolean.FALSE if the entity is detached, or
      • null to signal that the usual heuristics should be used to determine if the instance is transient
      Heuristics used when this method returns null are based on the value of the generated id field, or the version field, if any.
      Parameters:
      entity - a transient or detached entity
      Returns:
      Boolean or null to choose default behaviour

    • findDirty

      default int[] findDirty(Object entity, Object id, Object[] currentState, Object[] previousState, String[] propertyNames, Type[] types)
      Called from flush(). The return value determines whether the entity is updated
      • an array of property indices - the entity is dirty
      • an empty array - the entity is not dirty
      • null - use Hibernate's default dirty-checking algorithm
      Parameters:
      entity - The entity for which to find dirty properties.
      id - The identifier of the entity
      currentState - The current entity state as taken from the entity instance
      previousState - The state of the entity when it was last synchronized (generally when it was loaded)
      propertyNames - The names of the entity properties.
      types - The types of the entity properties
      Returns:
      array of dirty property indices or null to indicate Hibernate should perform default behaviour

    • instantiate

      default Object instantiate(String entityName, EntityRepresentationStrategy representationStrategy, Object id)
      Instantiate the entity. Return null to indicate that Hibernate should use the default constructor of the class. The identifier property of the returned instance should be initialized with the given identifier.

    • instantiate

      default Object instantiate(String entityName, RepresentationMode representationMode, Object id)
      Instantiate the entity. Return null to indicate that Hibernate should use the default constructor of the class. The identifier property of the returned instance should be initialized with the given identifier.

    • getEntityName

      default String getEntityName(Object object)
      Get the entity name for a persistent or transient instance.
      Parameters:
      object - an entity instance
      Returns:
      the name of the entity
      See Also:

    • getEntity

      default Object getEntity(String entityName, Object id)
      Get a fully loaded entity instance that is cached externally.
      Parameters:
      entityName - the name of the entity
      id - the instance identifier
      Returns:
      a fully initialized entity

    • afterTransactionBegin

      default void afterTransactionBegin(Transaction tx)
      Called when a Hibernate transaction is begun via the JPA-standard EntityTransaction API, or via Transaction. This method is not be called if transactions are being controlled via some other mechanism, for example, if transactions are managed by a container.
      Parameters:
      tx - The Hibernate transaction facade object

    • beforeTransactionCompletion

      default void beforeTransactionCompletion(Transaction tx)
      Called before a transaction is committed (but not before rollback).
      Parameters:
      tx - The Hibernate transaction facade object

    • afterTransactionCompletion

      default void afterTransactionCompletion(Transaction tx)
      Called after a transaction is committed or rolled back.
      Parameters:
      tx - The Hibernate transaction facade object

    • onInsert

      default void onInsert(Object entity, Object id, Object[] state, String[] propertyNames, Type[] propertyTypes)
      Called before a record is inserted by a StatelessSession.
      Parameters:
      entity - The entity instance being deleted
      id - The identifier of the entity
      state - The entity state
      propertyNames - The names of the entity properties.
      propertyTypes - The types of the entity properties
      See Also:

    • onUpdate

      default void onUpdate(Object entity, Object id, Object[] state, String[] propertyNames, Type[] propertyTypes)
      Called before a record is updated by a StatelessSession.
      Parameters:
      entity - The entity instance being deleted
      id - The identifier of the entity
      state - The entity state
      propertyNames - The names of the entity properties
      propertyTypes - The types of the entity properties
      See Also:

    • onUpsert

      default void onUpsert(Object entity, Object id, Object[] state, String[] propertyNames, Type[] propertyTypes)
      Called before a record is upserted by a StatelessSession.
      Parameters:
      entity - The entity instance being deleted
      id - The identifier of the entity
      state - The entity state
      propertyNames - The names of the entity properties
      propertyTypes - The types of the entity properties
      See Also:

    • onDelete

      default void onDelete(Object entity, Object id, String[] propertyNames, Type[] propertyTypes)
      Called before a record is deleted by a StatelessSession.
      Parameters:
      entity - The entity instance being deleted
      id - The identifier of the entity
      propertyNames - The names of the entity properties
      propertyTypes - The types of the entity properties
      See Also:

    • preMerge

      @Incubating default void preMerge(Object entity, Object[] state, String[] propertyNames, Type[] propertyTypes)
      Called before copying the state of a merged entity to a managed entity belonging to the persistence context of a stateful Session.

      The interceptor may modify the state.

      Parameters:
      entity - The entity passed to merge()
      state - The state of the entity passed to merge()
      propertyNames - The names of the entity properties
      propertyTypes - The types of the entity properties
      Since:
      7.1

    • postMerge

      @Incubating default void postMerge(Object source, Object target, Object id, Object[] targetState, Object[] originalState, String[] propertyNames, Type[] propertyTypes)
      Called after copying the state of a merged entity to a managed entity belonging to the persistence context of a stateful Session.

      Modification of the sourceState or targetState has no effect.

      Parameters:
      source - The entity passed to merge()
      target - The target managed entity
      id - The identifier of the managed entity
      targetState - The copied state already assigned to the target managed entity
      originalState - The original state of the target managed entity before assignment of the copied state, or null if the target entity is a new instance
      propertyNames - The names of the entity properties
      propertyTypes - The types of the entity properties
      Since:
      7.1