WebSVN - WebE - Blame - Rev 33 - /trunk/src/org/hibernate/Interceptor.java

Rev	Author	Line No.	Line
33	PointedEar	1	/*
		2	* Hibernate, Relational Persistence for Idiomatic Java
		3	*
		4	* Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
		5	* indicated by the @author tags or express copyright attribution
		6	* statements applied by the authors. All third-party contributions are
		7	* distributed under license by Red Hat Middleware LLC.
		8	*
		9	* This copyrighted material is made available to anyone wishing to use, modify,
		10	* copy, or redistribute it subject to the terms and conditions of the GNU
		11	* Lesser General Public License, as published by the Free Software Foundation.
		12	*
		13	* This program is distributed in the hope that it will be useful,
		14	* but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
		15	* or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
		16	* for more details.
		17	*
		18	* You should have received a copy of the GNU Lesser General Public License
		19	* along with this distribution; if not, write to:
		20	* Free Software Foundation, Inc.
		21	* 51 Franklin Street, Fifth Floor
		22	* Boston, MA 02110-1301 USA
		23	*
		24	*/
		25	package org.hibernate;
		26
		27	import java.io.Serializable;
		28	import java.util.Iterator;
		29
		30	import org.hibernate.type.Type;
		31
		32	/**
		33	* Allows user code to inspect and/or change property values.
		34	* <br><br>
		35	* Inspection occurs before property values are written and after they are read
		36	* from the database.<br>
		37	* <br>
		38	* There might be a single instance of <tt>Interceptor</tt> for a <tt>SessionFactory</tt>, or a new instance
		39	* might be specified for each <tt>Session</tt>. Whichever approach is used, the interceptor must be
		40	* serializable if the <tt>Session</tt> is to be serializable. This means that <tt>SessionFactory</tt>-scoped
		41	* interceptors should implement <tt>readResolve()</tt>.<br>
		42	* <br>
		43	* The <tt>Session</tt> may not be invoked from a callback (nor may a callback cause a collection or proxy to
		44	* be lazily initialized).<br>
		45	* <br>
		46	* Instead of implementing this interface directly, it is usually better to extend <tt>EmptyInterceptor</tt>
		47	* and override only the callback methods of interest.
		48	*
		49	* @see SessionFactory#openSession(Interceptor)
		50	* @see org.hibernate.cfg.Configuration#setInterceptor(Interceptor)
		51	* @see EmptyInterceptor
		52	* @author Gavin King
		53	*/
		54	public interface Interceptor {
		55	/**
		56	* Called just before an object is initialized. The interceptor may change the <tt>state</tt>, which will
		57	* be propagated to the persistent object. Note that when this method is called, <tt>entity</tt> will be
		58	* an empty uninitialized instance of the class.
		59	*
		60	* @return <tt>true</tt> if the user modified the <tt>state</tt> in any way.
		61	*/
		62	public boolean onLoad(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types) throws CallbackException;
		63	/**
		64	* Called when an object is detected to be dirty, during a flush. The interceptor may modify the detected
		65	* <tt>currentState</tt>, which will be propagated to both the database and the persistent object.
		66	* Note that not all flushes end in actual synchronization with the database, in which case the
		67	* new <tt>currentState</tt> will be propagated to the object, but not necessarily (immediately) to
		68	* the database. It is strongly recommended that the interceptor <b>not</b> modify the <tt>previousState</tt>.
		69	*
		70	* @return <tt>true</tt> if the user modified the <tt>currentState</tt> in any way.
		71	*/
		72	public boolean onFlushDirty(Object entity, Serializable id, Object[] currentState, Object[] previousState, String[] propertyNames, Type[] types) throws CallbackException;
		73	/**
		74	* Called before an object is saved. The interceptor may modify the <tt>state</tt>, which will be used for
		75	* the SQL <tt>INSERT</tt> and propagated to the persistent object.
		76	*
		77	* @return <tt>true</tt> if the user modified the <tt>state</tt> in any way.
		78	*/
		79	public boolean onSave(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types) throws CallbackException;
		80	/**
		81	* Called before an object is deleted. It is not recommended that the interceptor modify the <tt>state</tt>.
		82	*/
		83	public void onDelete(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types) throws CallbackException;
		84	/**
		85	* Called before a collection is (re)created.
		86	*/
		87	public void onCollectionRecreate(Object collection, Serializable key) throws CallbackException;
		88	/**
		89	* Called before a collection is deleted.
		90	*/
		91	public void onCollectionRemove(Object collection, Serializable key) throws CallbackException;
		92	/**
		93	* Called before a collection is updated.
		94	*/
		95	public void onCollectionUpdate(Object collection, Serializable key) throws CallbackException;
		96	/**
		97	* Called before a flush
		98	*/
		99	public void preFlush(Iterator entities) throws CallbackException;
		100	/**
		101	* Called after a flush that actually ends in execution of the SQL statements required to synchronize
		102	* in-memory state with the database.
		103	*/
		104	public void postFlush(Iterator entities) throws CallbackException;
		105	/**
		106	* Called to distinguish between transient and detached entities. The return value determines the
		107	* state of the entity with respect to the current session.
		108	* <ul>
		109	* <li><tt>Boolean.TRUE</tt> - the entity is transient
		110	* <li><tt>Boolean.FALSE</tt> - the entity is detached
		111	* <li><tt>null</tt> - Hibernate uses the <tt>unsaved-value</tt> mapping and other heuristics to
		112	* determine if the object is unsaved
		113	* </ul>
		114	* @param entity a transient or detached entity
		115	* @return Boolean or <tt>null</tt> to choose default behaviour
		116	*/
		117	public Boolean isTransient(Object entity);
		118	/**
		119	* Called from <tt>flush()</tt>. The return value determines whether the entity is updated
		120	* <ul>
		121	* <li>an array of property indices - the entity is dirty
		122	* <li>an empty array - the entity is not dirty
		123	* <li><tt>null</tt> - use Hibernate's default dirty-checking algorithm
		124	* </ul>
		125	* @param entity a persistent entity
		126	* @return array of dirty property indices or <tt>null</tt> to choose default behaviour
		127	*/
		128	public int[] findDirty(Object entity, Serializable id, Object[] currentState, Object[] previousState, String[] propertyNames, Type[] types);
		129	/**
		130	* Instantiate the entity class. Return <tt>null</tt> to indicate that Hibernate should use
		131	* the default constructor of the class. The identifier property of the returned instance
		132	* should be initialized with the given identifier.
		133	*
		134	* @param entityName the name of the entity
		135	* @param entityMode The type of entity instance to be returned.
		136	* @param id the identifier of the new instance
		137	* @return an instance of the class, or <tt>null</tt> to choose default behaviour
		138	*/
		139	public Object instantiate(String entityName, EntityMode entityMode, Serializable id) throws CallbackException;
		140
		141	/**
		142	* Get the entity name for a persistent or transient instance
		143	* @param object an entity instance
		144	* @return the name of the entity
		145	*/
		146	public String getEntityName(Object object) throws CallbackException;
		147
		148	/**
		149	* Get a fully loaded entity instance that is cached externally
		150	* @param entityName the name of the entity
		151	* @param id the instance identifier
		152	* @return a fully initialized entity
		153	* @throws CallbackException
		154	*/
		155	public Object getEntity(String entityName, Serializable id) throws CallbackException;
		156
		157	/**
		158	* Called when a Hibernate transaction is begun via the Hibernate <tt>Transaction</tt>
		159	* API. Will not be called if transactions are being controlled via some other
		160	* mechanism (CMT, for example).
		161	*/
		162	public void afterTransactionBegin(Transaction tx);
		163	/**
		164	* Called before a transaction is committed (but not before rollback).
		165	*/
		166	public void beforeTransactionCompletion(Transaction tx);
		167	/**
		168	* Called after a transaction is committed or rolled back.
		169	*/
		170	public void afterTransactionCompletion(Transaction tx);
		171
		172	/**
		173	* Called when sql string is being prepared.
		174	* @param sql sql to be prepared
		175	* @return original or modified sql
		176	*/
		177	public String onPrepareStatement(String sql);
		178	}

Subversion Repositories WebE

(root)/trunk/src/org/hibernate/Interceptor.java - Rev 33