org.hibernate
Interface Interceptor

All Known Implementing Classes:
EmptyInterceptor

public interface Interceptor

Allows user code to inspect and/or change property values.

Inspection occurs before property values are written and after they are read from the database.

There might be a single instance of Interceptor for a SessionFactory, or a new instance might be specified for each Session. Whichever approach is used, the interceptor must be serializable if the Session is to be serializable. This means that SessionFactory-scoped interceptors should implement readResolve().

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

Instead of implementing this interface directly, it is usually better to extend EmptyInterceptor and override only the callback methods of interest.

See Also:
SessionBuilder.interceptor(Interceptor), SharedSessionBuilder.interceptor(), Configuration.setInterceptor(Interceptor), EmptyInterceptor

Method Summary
 void afterTransactionBegin(Transaction tx)
          Called when a Hibernate transaction is begun via the Hibernate Transaction API.
 void afterTransactionCompletion(Transaction tx)
          Called after a transaction is committed or rolled back.
 void beforeTransactionCompletion(Transaction tx)
          Called before a transaction is committed (but not before rollback).
 int[] findDirty(Object entity, Serializable id, Object[] currentState, Object[] previousState, String[] propertyNames, Type[] types)
          Called from flush().
 Object getEntity(String entityName, Serializable id)
          Get a fully loaded entity instance that is cached externally
 String getEntityName(Object object)
          Get the entity name for a persistent or transient instance
 Object instantiate(String entityName, EntityMode entityMode, Serializable id)
          Instantiate the entity class.
 Boolean isTransient(Object entity)
          Called to distinguish between transient and detached entities.
 void onCollectionRecreate(Object collection, Serializable key)
          Called before a collection is (re)created.
 void onCollectionRemove(Object collection, Serializable key)
          Called before a collection is deleted.
 void onCollectionUpdate(Object collection, Serializable key)
          Called before a collection is updated.
 void onDelete(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types)
          Called before an object is deleted.
 boolean onFlushDirty(Object entity, Serializable id, Object[] currentState, Object[] previousState, String[] propertyNames, Type[] types)
          Called when an object is detected to be dirty, during a flush.
 boolean onLoad(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types)
          Called just before an object is initialized.
 String onPrepareStatement(String sql)
          Called when sql string is being prepared.
 boolean onSave(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types)
          Called before an object is saved.
 void postFlush(Iterator entities)
          Called after a flush that actually ends in execution of the SQL statements required to synchronize in-memory state with the database.
 void preFlush(Iterator entities)
          Called before a flush
 

Method Detail

onLoad

boolean onLoad(Object entity,
               Serializable 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.

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

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.

onFlushDirty

boolean onFlushDirty(Object entity,
                     Serializable 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.

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

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.

onSave

boolean onSave(Object entity,
               Serializable id,
               Object[] state,
               String[] propertyNames,
               Type[] types)
               throws CallbackException
Called before an object is saved. 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.

onDelete

void onDelete(Object entity,
              Serializable id,
              Object[] state,
              String[] propertyNames,
              Type[] types)
              throws CallbackException
Called before an object is deleted. 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.

onCollectionRecreate

void onCollectionRecreate(Object collection,
                          Serializable 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

void onCollectionRemove(Object collection,
                        Serializable 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

void onCollectionUpdate(Object collection,
                        Serializable 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

void preFlush(Iterator 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

void postFlush(Iterator 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

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.

Parameters:
entity - a transient or detached entity
Returns:
Boolean or null to choose default behaviour

findDirty

int[] findDirty(Object entity,
                Serializable id,
                Object[] currentState,
                Object[] previousState,
                String[] propertyNames,
                Type[] types)
Called from flush(). The return value determines whether the entity is updated

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

Object instantiate(String entityName,
                   EntityMode entityMode,
                   Serializable id)
                   throws CallbackException
Instantiate the entity class. 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.

Parameters:
entityName - the name of the entity
entityMode - The type of entity instance to be returned.
id - the identifier of the new instance
Returns:
an instance of the class, or null to choose default behaviour
Throws:
CallbackException - Thrown if the interceptor encounters any problems handling the callback.

getEntityName

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.

getEntity

Object getEntity(String entityName,
                 Serializable 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

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

void beforeTransactionCompletion(Transaction tx)
Called before a transaction is committed (but not before rollback).

Parameters:
tx - The Hibernate transaction facade object

afterTransactionCompletion

void afterTransactionCompletion(Transaction tx)
Called after a transaction is committed or rolled back.

Parameters:
tx - The Hibernate transaction facade object

onPrepareStatement

String onPrepareStatement(String sql)
Called when sql string is being prepared.

Parameters:
sql - sql to be prepared
Returns:
original or modified sql


Copyright © 2001-2013 Red Hat, Inc. All Rights Reserved.