Package org.hibernate

Interface Interceptor

All Known Implementing Classes:
EmptyInterceptor
public interfaceInterceptor
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.

TheSession 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 ofInterceptor for aSessionFactory, or a new instance might be created for eachSession. Use:

Whichever approach is used, the interceptor must be serializable for theSession to be serializable. This means thatSessionFactory-scoped interceptors should implementreadResolve().

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, andPreRemove. 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.

  • 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 thestate, 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 thestate.
      types - The types of the entity properties, corresponding to thestate.
      Returns:
      true if the user modified thestate in any way.
      API Note:
      The indexes across thestate,propertyNames, andtypes 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 thestate, which will be used for the SQLINSERT 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 thestate 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 thestate.

      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 detectedcurrentState, 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 newcurrentState will be propagated to the object, but not necessarily (immediately) to the database. It is strongly recommended that the interceptornot modify thepreviousState.
      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 thecurrentState in any way.
      See Also:
      API Note:
      The indexes across thecurrentState,previousState,propertyNames, andtypes arrays match.

    • onSave

      @Deprecated(since="6.6")default boolean onSave(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 thestate, which will be used for the SQLINSERT 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 thestate in any way.
      See Also:

    • onDelete

      @Deprecated(since="6.6")default void onDelete(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 thestate.

      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 thegenerated id field, or theversion field, if any.
      Parameters:
      entity - a transient or detached entity
      Returns:
      Boolean ornull to choose default behaviour

    • findDirty

      default int[] findDirty(Object entity,Object id,Object[] currentState,Object[] previousState,String[] propertyNames,Type[] types)
      Called fromflush(). 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 ornull to indicate Hibernate should perform default behaviour

    • instantiate

      default Object instantiate(String entityName,EntityRepresentationStrategy representationStrategy,Object id)
      Instantiate the entity. Returnnull 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. Returnnull 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-standardEntityTransaction API, or viaTransaction. 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 aStatelessSession.
      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 aStatelessSession.
      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 aStatelessSession.
      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 aStatelessSession.
      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: