001: //$Id: Interceptor.java 7883 2005-08-12 20:03:07Z oneovthafew $
002: package org.hibernate;
003:
004: import java.io.Serializable;
005: import java.util.Iterator;
006:
007: import org.hibernate.type.Type;
008:
009: /**
010: * Allows user code to inspect and/or change property values.
011: * <br><br>
012: * Inspection occurs before property values are written and after they are read
013: * from the database.<br>
014: * <br>
015: * There might be a single instance of <tt>Interceptor</tt> for a <tt>SessionFactory</tt>, or a new instance
016: * might be specified for each <tt>Session</tt>. Whichever approach is used, the interceptor must be
017: * serializable if the <tt>Session</tt> is to be serializable. This means that <tt>SessionFactory</tt>-scoped
018: * interceptors should implement <tt>readResolve()</tt>.<br>
019: * <br>
020: * The <tt>Session</tt> may not be invoked from a callback (nor may a callback cause a collection or proxy to
021: * be lazily initialized).<br>
022: * <br>
023: * Instead of implementing this interface directly, it is usually better to extend <tt>EmptyInterceptor</tt>
024: * and override only the callback methods of interest.
025: *
026: * @see SessionFactory#openSession(Interceptor)
027: * @see org.hibernate.cfg.Configuration#setInterceptor(Interceptor)
028: * @see EmptyInterceptor
029: * @author Gavin King
030: */
031: public interface Interceptor {
032: /**
033: * Called just before an object is initialized. The interceptor may change the <tt>state</tt>, which will
034: * be propagated to the persistent object. Note that when this method is called, <tt>entity</tt> will be
035: * an empty uninitialized instance of the class.
036: *
037: * @return <tt>true</tt> if the user modified the <tt>state</tt> in any way.
038: */
039: public boolean onLoad(Object entity, Serializable id,
040: Object[] state, String[] propertyNames, Type[] types)
041: throws CallbackException;
042:
043: /**
044: * Called when an object is detected to be dirty, during a flush. The interceptor may modify the detected
045: * <tt>currentState</tt>, which will be propagated to both the database and the persistent object.
046: * Note that not all flushes end in actual synchronization with the database, in which case the
047: * new <tt>currentState</tt> will be propagated to the object, but not necessarily (immediately) to
048: * the database. It is strongly recommended that the interceptor <b>not</b> modify the <tt>previousState</tt>.
049: *
050: * @return <tt>true</tt> if the user modified the <tt>currentState</tt> in any way.
051: */
052: public boolean onFlushDirty(Object entity, Serializable id,
053: Object[] currentState, Object[] previousState,
054: String[] propertyNames, Type[] types)
055: throws CallbackException;
056:
057: /**
058: * Called before an object is saved. The interceptor may modify the <tt>state</tt>, which will be used for
059: * the SQL <tt>INSERT</tt> and propagated to the persistent object.
060: *
061: * @return <tt>true</tt> if the user modified the <tt>state</tt> in any way.
062: */
063: public boolean onSave(Object entity, Serializable id,
064: Object[] state, String[] propertyNames, Type[] types)
065: throws CallbackException;
066:
067: /**
068: * Called before an object is deleted. It is not recommended that the interceptor modify the <tt>state</tt>.
069: */
070: public void onDelete(Object entity, Serializable id,
071: Object[] state, String[] propertyNames, Type[] types)
072: throws CallbackException;
073:
074: /**
075: * Called before a collection is (re)created.
076: */
077: public void onCollectionRecreate(Object collection, Serializable key)
078: throws CallbackException;
079:
080: /**
081: * Called before a collection is deleted.
082: */
083: public void onCollectionRemove(Object collection, Serializable key)
084: throws CallbackException;
085:
086: /**
087: * Called before a collection is updated.
088: */
089: public void onCollectionUpdate(Object collection, Serializable key)
090: throws CallbackException;
091:
092: /**
093: * Called before a flush
094: */
095: public void preFlush(Iterator entities) throws CallbackException;
096:
097: /**
098: * Called after a flush that actually ends in execution of the SQL statements required to synchronize
099: * in-memory state with the database.
100: */
101: public void postFlush(Iterator entities) throws CallbackException;
102:
103: /**
104: * Called to distinguish between transient and detached entities. The return value determines the
105: * state of the entity with respect to the current session.
106: * <ul>
107: * <li><tt>Boolean.TRUE</tt> - the entity is transient
108: * <li><tt>Boolean.FALSE</tt> - the entity is detached
109: * <li><tt>null</tt> - Hibernate uses the <tt>unsaved-value</tt> mapping and other heuristics to
110: * determine if the object is unsaved
111: * </ul>
112: * @param entity a transient or detached entity
113: * @return Boolean or <tt>null</tt> to choose default behaviour
114: */
115: public Boolean isTransient(Object entity);
116:
117: /**
118: * Called from <tt>flush()</tt>. The return value determines whether the entity is updated
119: * <ul>
120: * <li>an array of property indices - the entity is dirty
121: * <li>an empty array - the entity is not dirty
122: * <li><tt>null</tt> - use Hibernate's default dirty-checking algorithm
123: * </ul>
124: * @param entity a persistent entity
125: * @return array of dirty property indices or <tt>null</tt> to choose default behaviour
126: */
127: public int[] findDirty(Object entity, Serializable id,
128: Object[] currentState, Object[] previousState,
129: String[] propertyNames, Type[] types);
130:
131: /**
132: * Instantiate the entity class. Return <tt>null</tt> to indicate that Hibernate should use
133: * the default constructor of the class. The identifier property of the returned instance
134: * should be initialized with the given identifier.
135: *
136: * @param entityName the name of the entity
137: * @param entityMode The type of entity instance to be returned.
138: * @param id the identifier of the new instance
139: * @return an instance of the class, or <tt>null</tt> to choose default behaviour
140: */
141: public Object instantiate(String entityName, EntityMode entityMode,
142: Serializable id) throws CallbackException;
143:
144: /**
145: * Get the entity name for a persistent or transient instance
146: * @param object an entity instance
147: * @return the name of the entity
148: */
149: public String getEntityName(Object object) throws CallbackException;
150:
151: /**
152: * Get a fully loaded entity instance that is cached externally
153: * @param entityName the name of the entity
154: * @param id the instance identifier
155: * @return a fully initialized entity
156: * @throws CallbackException
157: */
158: public Object getEntity(String entityName, Serializable id)
159: throws CallbackException;
160:
161: /**
162: * Called when a Hibernate transaction is begun via the Hibernate <tt>Transaction</tt>
163: * API. Will not be called if transactions are being controlled via some other
164: * mechanism (CMT, for example).
165: */
166: public void afterTransactionBegin(Transaction tx);
167:
168: /**
169: * Called before a transaction is committed (but not before rollback).
170: */
171: public void beforeTransactionCompletion(Transaction tx);
172:
173: /**
174: * Called after a transaction is committed or rolled back.
175: */
176: public void afterTransactionCompletion(Transaction tx);
177:
178: /**
179: * Called when sql string is being prepared.
180: * @param sql sql to be prepared
181: * @return original or modified sql
182: */
183: public String onPrepareStatement(String sql);
184: }
|