Hibernate example source code file (Interceptor.java)

This example Hibernate source code file (Interceptor.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Hibernate tags/keywords

boolean, callbackexception, callbackexception, entitymode, interceptor, io, object, object, serializable, serializable, string, string, type, util

The Hibernate Interceptor.java source code

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

 * Inspection occurs before property values are written and after they are read
 * from the database.<br>
 * <br>
 * There might be a single instance of <tt>Interceptor for a SessionFactory, or a new instance
 * might be specified for each <tt>Session. Whichever approach is used, the interceptor must be
 * serializable if the <tt>Session is to be serializable. This means that SessionFactory-scoped
 * interceptors should implement <tt>readResolve().

 * <br>
 * The <tt>Session may not be invoked from a callback (nor may a callback cause a collection or proxy to
 * be lazily initialized).<br>
 * <br>
 * Instead of implementing this interface directly, it is usually better to extend <tt>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 <tt>state, which will
	 * be propagated to the persistent object. Note that when this method is called, <tt>entity will be
	 * an empty uninitialized instance of the class.
	 *
	 * @return <tt>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
	 * <tt>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 <tt>currentState will be propagated to the object, but not necessarily (immediately) to
	 * the database. It is strongly recommended that the interceptor <b>not modify the previousState.
	 *
	 * @return <tt>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 <tt>state, which will be used for
	 * the SQL <tt>INSERT and propagated to the persistent object.
	 *
	 * @return <tt>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 <tt>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.
	 * <ul>
	 * <li>Boolean.TRUE - the entity is transient
	 * <li>Boolean.FALSE - the entity is detached
	 * <li>null - Hibernate uses the unsaved-value mapping and other heuristics to 
	 * determine if the object is unsaved
	 * </ul>
	 * @param entity a transient or detached entity
	 * @return Boolean or <tt>null to choose default behaviour
	 */
	public Boolean isTransient(Object entity);
	/**
	 * Called from <tt>flush(). The return value determines whether the entity is updated
	 * <ul>
	 * <li>an array of property indices - the entity is dirty
	 * <li>an empty array - the entity is not dirty
	 * <li>null - use Hibernate's default dirty-checking algorithm
	 * </ul>
	 * @param entity a persistent entity
	 * @return array of dirty property indices or <tt>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 <tt>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 <tt>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 <tt>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);
}