/*
* 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.
*