/* * Hibernate, Relational Persistence for Idiomatic Java * * Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as * indicated by the @author tags or express copyright attribution * statements applied by the authors. All third-party contributions are * distributed under license by Red Hat Middleware LLC. * * This copyrighted material is made available to anyone wishing to use, modify, * copy, or redistribute it subject to the terms and conditions of the GNU * Lesser General Public License, as published by the Free Software Foundation. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License * for more details. * * You should have received a copy of the GNU Lesser General Public License * along with this distribution; if not, write to: * Free Software Foundation, Inc. * 51 Franklin Street, Fifth Floor * Boston, MA 02110-1301 USA * */ package org.hibernate; import java.io.Serializable; import java.util.Iterator; import org.hibernate.type.Type; /** * 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 SessionFactory#openSession(Interceptor) * @see org.hibernate.cfg.Configuration#setInterceptor(Interceptor) * @see EmptyInterceptor * @author Gavin King */ public interface Interceptor { /** * 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. * * @return true if the user modified the state in any way. */ public boolean onLoad(Object entity, Serializable id, Object[] state, 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. * * @return true if the user modified the currentState in any way. */ public boolean onFlushDirty(Object entity, Serializable id, Object[] currentState, Object[] previousState, 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. * * @return true if the user modified the state in any way. */ public boolean onSave(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. */ public void onDelete(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types) throws CallbackException; /** * Called before a collection is (re)created. */ public void onCollectionRecreate(Object collection, Serializable key) throws CallbackException; /** * Called before a collection is deleted. */ public void onCollectionRemove(Object collection, Serializable key) throws CallbackException; /** * Called before a collection is updated. */ public void onCollectionUpdate(Object collection, Serializable key) throws CallbackException; /** * Called before a flush */ public void preFlush(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. */ public void postFlush(Iterator entities) throws CallbackException; /** * Called to distinguish between transient and detached entities. The return value determines the * state of the entity with respect to the current session. * * @param entity a transient or detached entity * @return Boolean or null to choose default behaviour */ public Boolean isTransient(Object entity); /** * Called from flush(). The return value determines whether the entity is updated * * @param entity a persistent entity * @return array of dirty property indices or null to choose default behaviour */ public int[] findDirty(Object entity, Serializable id, Object[] currentState, Object[] previousState, String[] propertyNames, Type[] types); /** * 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. * * @param entityName the name of the entity * @param entityMode The type of entity instance to be returned. * @param id the identifier of the new instance * @return an instance of the class, or null to choose default behaviour */ public Object instantiate(String entityName, EntityMode entityMode, Serializable id) throws CallbackException; /** * Get the entity name for a persistent or transient instance * @param object an entity instance * @return the name of the entity */ public String getEntityName(Object object) throws CallbackException; /** * Get a fully loaded entity instance that is cached externally * @param entityName the name of the entity * @param id the instance identifier * @return a fully initialized entity * @throws CallbackException */ public Object getEntity(String entityName, Serializable id) throws CallbackException; /** * 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). */ public void afterTransactionBegin(Transaction tx); /** * Called before a transaction is committed (but not before rollback). */ public void beforeTransactionCompletion(Transaction tx); /** * Called after a transaction is committed or rolled back. */ public void afterTransactionCompletion(Transaction tx); /** * Called when sql string is being prepared. * @param sql sql to be prepared * @return original or modified sql */ public String onPrepareStatement(String sql); }