Package org.hibernate

Interface Interceptor

All Known Implementing Classes:

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

• For a stateful session, the callbacks onLoad(java.lang.Object, java.lang.Object, java.lang.Object[], java.lang.String[], org.hibernate.type.Type[]), onPersist(java.lang.Object, java.lang.Object, java.lang.Object[], java.lang.String[], org.hibernate.type.Type[]), onRemove(java.lang.Object, java.lang.Object, java.lang.Object[], java.lang.String[], org.hibernate.type.Type[]), and onFlushDirty(java.lang.Object, java.lang.Object, java.lang.Object[], java.lang.Object[], java.lang.String[], org.hibernate.type.Type[]) reflect the basic lifecycle of a managed entity.
• For a stateless session, the relevant callbacks are onLoad(java.lang.Object, java.lang.Object, java.lang.Object[], java.lang.String[], org.hibernate.type.Type[]), onInsert(java.lang.Object, java.lang.Object, java.lang.Object[], java.lang.String[], org.hibernate.type.Type[]), onUpdate(java.lang.Object, java.lang.Object, java.lang.Object[], java.lang.String[], org.hibernate.type.Type[]), onUpsert(java.lang.Object, java.lang.Object, java.lang.Object[], java.lang.String[], org.hibernate.type.Type[]), and onDelete.

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:

• SessionEventSettings.INTERCEPTOR to specify an interceptor shared between sessions, or
• SessionEventSettings.SESSION_SCOPED_INTERCEPTOR to specify that there is a dedicated instance of the interceptor for each session.

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

This venerable callback interface, dating to the very earliest days of Hibernate, competes with JPA entity listener callbacks: PostLoad, PrePersist PreUpdate, and PreRemove.

See Also:

• SessionBuilder.interceptor(Interceptor)
• SharedSessionBuilder.interceptor()
• Configuration.setInterceptor(Interceptor)
• SessionFactoryBuilder.applyInterceptor(Interceptor)
• SessionFactoryBuilder.applyStatelessInterceptor(Class)

Method Summary

Modifier and Type	Method	Description
default void	afterTransactionBegin(Transaction tx)	Called when a Hibernate transaction is begun via the Hibernate Transaction API.
default void	afterTransactionCompletion(Transaction tx)	Called after a transaction is committed or rolled back.
default void	beforeTransactionCompletion(Transaction tx)	Called before a transaction is committed (but not before rollback).
default int[]	findDirty(Object entity, Serializable id, Object[] currentState, Object[] previousState, String[] propertyNames, Type[] types)	Deprecated. use findDirty(Object, Object, Object[], Object[], String[], Type[])
default int[]	findDirty(Object entity, Object id, Object[] currentState, Object[] previousState, String[] propertyNames, Type[] types)	Called from flush().
default Object	getEntity(String entityName, Serializable id)	Deprecated. use getEntity(String, Object)
default Object	getEntity(String entityName, Object id)	Get a fully loaded entity instance that is cached externally.
default String	getEntityName(Object object)	Get the entity name for a persistent or transient instance.
default Object	instantiate(String entityName, RepresentationMode representationMode, Object id)	Instantiate the entity.
default Object	instantiate(String entityName, EntityRepresentationStrategy representationStrategy, Object id)	Instantiate the entity.
default Boolean	isTransient(Object entity)	Called to distinguish between transient and detached entities.
default void	onCollectionRecreate(Object collection, Serializable key)	Deprecated. use onCollectionRecreate(Object, Object)
default void	onCollectionRecreate(Object collection, Object key)	Called before a collection is (re)created.
default void	onCollectionRemove(Object collection, Serializable key)	Deprecated. use onCollectionRemove(Object, Object)
default void	onCollectionRemove(Object collection, Object key)	Called before a collection is deleted.
default void	onCollectionUpdate(Object collection, Serializable key)	Deprecated. use onCollectionUpdate(Object, Object)
default void	onCollectionUpdate(Object collection, Object key)	Called before a collection is updated.
default void	onDelete(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types)	Deprecated. use onDelete(Object, Object, Object[], String[], Type[])
default void	onDelete(Object entity, Object id, Object[] state, String[] propertyNames, Type[] types)	Deprecated. Use onRemove(Object, Object, Object[], String[], Type[])
default void	onDelete(Object entity, Object id, String[] propertyNames, Type[] propertyTypes)	Called before a record is deleted by a StatelessSession.
default boolean	onFlushDirty(Object entity, Serializable id, Object[] currentState, Object[] previousState, String[] propertyNames, Type[] types)	Deprecated. use onFlushDirty(Object, Object, Object[], Object[], String[], Type[])
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.
default void	onInsert(Object entity, Object id, Object[] state, String[] propertyNames, Type[] propertyTypes)	Called before a record is inserted by a StatelessSession.
default boolean	onLoad(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types)	Deprecated. use onLoad(Object, Object, Object[], String[], Type[])
default boolean	onLoad(Object entity, Object id, Object[] state, String[] propertyNames, Type[] types)	Called just before an object is initialized.
default boolean	onPersist(Object entity, Object id, Object[] state, String[] propertyNames, Type[] types)	Called before an object is made persistent by a stateful session.
default void	onRemove(Object entity, Object id, Object[] state, String[] propertyNames, Type[] types)	Called before an object is removed by a stateful session.
default boolean	onSave(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types)	Deprecated. use onSave(Object, Object, Object[], String[], Type[])
default boolean	onSave(Object entity, Object id, Object[] state, String[] propertyNames, Type[] types)	Deprecated. Use onPersist(Object, Object, Object[], String[], Type[])
default void	onUpdate(Object entity, Object id, Object[] state, String[] propertyNames, Type[] propertyTypes)	Called before a record is updated by a StatelessSession.
default void	onUpsert(Object entity, Object id, Object[] state, String[] propertyNames, Type[] propertyTypes)	Called before a record is upserted by a StatelessSession.
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.
default void	preFlush(Iterator<Object> entities)	Called before a flush.

Method Details

onLoad

default boolean onLoad(Object entity,
 Object id,
 Object[] state,
 String[] propertyNames,
 Type[] types)
                throws CallbackException

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.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

API Note:

The indexes across the state, propertyNames, and types arrays match.

onLoad

@Deprecated(since="6.0")
default boolean onLoad(Object entity,
 Serializable id,
 Object[] state,
 String[] propertyNames,
 Type[] types)
                throws CallbackException

Deprecated.

use onLoad(Object, Object, Object[], String[], Type[])

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.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

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)
                   throws CallbackException

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.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

See Also:

• Session.persist(Object)
• Session.merge(Object)

onRemove

default void onRemove(Object entity,
 Object id,
 Object[] state,
 String[] propertyNames,
 Type[] types)
               throws CallbackException

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

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

See Also:

• Session.remove(Object)

onFlushDirty

default boolean onFlushDirty(Object entity,
 Object id,
 Object[] currentState,
 Object[] previousState,
 String[] propertyNames,
 Type[] types)
                      throws CallbackException

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.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

See Also:

• Session.flush()

API Note:

The indexes across the currentState, previousState, propertyNames, and types arrays match.

onFlushDirty

@Deprecated(since="6.0")
default boolean onFlushDirty(Object entity,
 Serializable id,
 Object[] currentState,
 Object[] previousState,
 String[] propertyNames,
 Type[] types)
                      throws CallbackException

Deprecated.

use onFlushDirty(Object, Object, Object[], Object[], String[], Type[])

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.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

API Note:

The indexes across the currentState, previousState, propertyNames, and types arrays match.

onSave

@Deprecated(since="6.0")
default boolean onSave(Object entity,
 Serializable id,
 Object[] state,
 String[] propertyNames,
 Type[] types)
                throws CallbackException

Deprecated.

use onSave(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.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

onSave

@Deprecated(since="6.6")
default boolean onSave(Object entity,
 Object id,
 Object[] state,
 String[] propertyNames,
 Type[] types)
                throws CallbackException

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.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

See Also:

• Session.persist(Object)
• Session.merge(Object)
• Session.save(Object)

onDelete

@Deprecated(since="6.0")
default void onDelete(Object entity,
 Serializable id,
 Object[] state,
 String[] propertyNames,
 Type[] types)
               throws CallbackException

Deprecated.

use onDelete(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

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

onDelete

@Deprecated(since="6.6")
default void onDelete(Object entity,
 Object id,
 Object[] state,
 String[] propertyNames,
 Type[] types)
               throws CallbackException

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

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

See Also:

• Session.remove(Object)
• Session.delete(Object)

onCollectionRecreate

@Deprecated(since="6.0")
default void onCollectionRecreate(Object collection,
 Serializable key)
                           throws CallbackException

Deprecated.

use onCollectionRecreate(Object, Object)

Called before a collection is (re)created.

Parameters:

collection - The collection instance.

key - The collection key value.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

onCollectionRecreate

default void onCollectionRecreate(Object collection,
 Object key)
                           throws CallbackException

Called before a collection is (re)created.

Parameters:

collection - The collection instance.

key - The collection key value.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

onCollectionRemove

@Deprecated(since="6.0")
default void onCollectionRemove(Object collection,
 Serializable key)
                         throws CallbackException

Deprecated.

use onCollectionRemove(Object, Object)

Called before a collection is deleted.

Parameters:

collection - The collection instance.

key - The collection key value.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

onCollectionRemove

default void onCollectionRemove(Object collection,
 Object key)
                         throws CallbackException

Called before a collection is deleted.

Parameters:

collection - The collection instance.

key - The collection key value.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

onCollectionUpdate

@Deprecated(since="6.0")
default void onCollectionUpdate(Object collection,
 Serializable key)
                         throws CallbackException

Deprecated.

use onCollectionUpdate(Object, Object)

Called before a collection is updated.

Parameters:

collection - The collection instance.

key - The collection key value.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

onCollectionUpdate

default void onCollectionUpdate(Object collection,
 Object key)
                         throws CallbackException

Called before a collection is updated.

Parameters:

collection - The collection instance.

key - The collection key value.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

preFlush

default void preFlush(Iterator<Object> entities)
               throws CallbackException

Called before a flush.

Parameters:

entities - The entities to be flushed.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

postFlush

default void postFlush(Iterator<Object> entities)
                throws CallbackException

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.

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

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.

• Boolean.TRUE - the entity is transient
• Boolean.FALSE - the entity is detached
• null - Hibernate uses the unsaved-value mapping and other heuristics to determine if the object is unsaved

Parameters:

entity - a transient or detached entity

Returns:

Boolean or null to choose default behaviour

findDirty

@Deprecated(since="6.0")
default int[] findDirty(Object entity,
 Serializable id,
 Object[] currentState,
 Object[] previousState,
 String[] propertyNames,
 Type[] types)

Deprecated.

use findDirty(Object, Object, Object[], Object[], String[], Type[])

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

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

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

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

instantiate

default Object instantiate(String entityName,
 EntityRepresentationStrategy representationStrategy,
 Object id)
                    throws CallbackException

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.

Throws:

CallbackException

instantiate

default Object instantiate(String entityName,
 RepresentationMode representationMode,
 Object id)
                    throws CallbackException

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.

Throws:

CallbackException

getEntityName

default String getEntityName(Object object)
                      throws CallbackException

Get the entity name for a persistent or transient instance.

Parameters:

object - an entity instance

Returns:

the name of the entity

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

See Also:

• EntityNameResolver

getEntity

@Deprecated(since="6.0")
default Object getEntity(String entityName,
 Serializable id)
                  throws CallbackException

Deprecated.

use getEntity(String, Object)

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

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

getEntity

default Object getEntity(String entityName,
 Object id)
                  throws CallbackException

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

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

afterTransactionBegin

default void afterTransactionBegin(Transaction tx)

Called when a Hibernate transaction is begun via the Hibernate Transaction API. Will not be called if transactions are being controlled via some other mechanism (CMT, for example).

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

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

See Also:

• StatelessSession.insert(Object)

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

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

See Also:

• StatelessSession.update(Object)

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

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

See Also:

• StatelessSession.upsert(String, Object)

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

Throws:

CallbackException - Thrown if the interceptor encounters any problems handling the callback.

See Also:

• StatelessSession.delete(Object)