## 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.
  - `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

    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
  - 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

    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-2012 Red Hat, Inc. All Rights Reserved.