KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > hibernate > Interceptor


1 //$Id: Interceptor.java,v 1.5 2005/04/29 15:13:02 oneovthafew Exp $
2 package org.hibernate;
3
4 import java.io.Serializable JavaDoc;
5 import java.util.Iterator JavaDoc;
6
7 import org.hibernate.type.Type;
8
9 /**
10  * Allows user code to inspect and/or change property values.
11  * <br><br>
12  * Inspection occurs before property values are written and after they are read
13  * from the database.<br>
14  * <br>
15  * There might be a single instance of <tt>Interceptor</tt> for a <tt>SessionFactory</tt>, or a new instance
16  * might be specified for each <tt>Session</tt>. Whichever approach is used, the interceptor must be
17  * serializable if the <tt>Session</tt> is to be serializable. This means that <tt>SessionFactory</tt>-scoped
18  * interceptors should implement <tt>readResolve()</tt>.<br>
19  * <br>
20  * The <tt>Session</tt> may not be invoked from a callback (nor may a callback cause a collection or proxy to
21  * be lazily initialized).<br>
22  *
23  * @see SessionFactory#openSession(Interceptor)
24  * @see org.hibernate.cfg.Configuration#setInterceptor(Interceptor)
25  * @author Gavin King
26  */
27 public interface Interceptor {
28     /**
29      * Called just before an object is initialized. The interceptor may change the <tt>state</tt>, which will
30      * be propagated to the persistent object. Note that when this method is called, <tt>entity</tt> will be
31      * an empty uninitialized instance of the class.
32      *
33      * @return <tt>true</tt> if the user modified the <tt>state</tt> in any way.
34      */
35     public boolean onLoad(Object JavaDoc entity, Serializable JavaDoc id, Object JavaDoc[] state, String JavaDoc[] propertyNames, Type[] types) throws CallbackException;
36     /**
37      * Called when an object is detected to be dirty, during a flush. The interceptor may modify the detected
38      * <tt>currentState</tt>, which will be propagated to both the database and the persistent object.
39      * Note that not all flushes end in actual synchronization with the database, in which case the
40      * new <tt>currentState</tt> will be propagated to the object, but not necessarily (immediately) to
41      * the database. It is strongly recommended that the interceptor <b>not</b> modify the <tt>previousState</tt>.
42      *
43      * @return <tt>true</tt> if the user modified the <tt>currentState</tt> in any way.
44      */
45     public boolean onFlushDirty(Object JavaDoc entity, Serializable JavaDoc id, Object JavaDoc[] currentState, Object JavaDoc[] previousState, String JavaDoc[] propertyNames, Type[] types) throws CallbackException;
46     /**
47      * Called before an object is saved. The interceptor may modify the <tt>state</tt>, which will be used for
48      * the SQL <tt>INSERT</tt> and propagated to the persistent object.
49      *
50      * @return <tt>true</tt> if the user modified the <tt>state</tt> in any way.
51      */
52     public boolean onSave(Object JavaDoc entity, Serializable JavaDoc id, Object JavaDoc[] state, String JavaDoc[] propertyNames, Type[] types) throws CallbackException;
53     /**
54      * Called before an object is deleted. It is not recommended that the interceptor modify the <tt>state</tt>.
55      */
56     public void onDelete(Object JavaDoc entity, Serializable JavaDoc id, Object JavaDoc[] state, String JavaDoc[] propertyNames, Type[] types) throws CallbackException;
57     /**
58      * Called before a flush
59      */
60     public void preFlush(Iterator JavaDoc entities) throws CallbackException;
61     /**
62      * Called after a flush that actually ends in execution of the SQL statements required to synchronize
63      * in-memory state with the database.
64      */
65     public void postFlush(Iterator JavaDoc entities) throws CallbackException;
66     /**
67      * Called to distinguish between transient and detached entities. The return value determines the
68      * state of the entity with respect to the current session.
69      * <ul>
70      * <li><tt>Boolean.TRUE</tt> - the entity is transient
71      * <li><tt>Boolean.FALSE</tt> - the entity is detached
72      * <li><tt>null</tt> - Hibernate uses the <tt>unsaved-value</tt> mapping and other heuristics to
73      * determine if the object is unsaved
74      * </ul>
75      * @param entity a transient or detached entity
76      * @return Boolean or <tt>null</tt> to choose default behaviour
77      */
78     public Boolean JavaDoc isTransient(Object JavaDoc entity);
79     /**
80      * Called from <tt>flush()</tt>. The return value determines whether the entity is updated
81      * <ul>
82      * <li>an array of property indices - the entity is dirty
83      * <li>and empty array - the entity is not dirty
84      * <li><tt>null</tt> - use Hibernate's default dirty-checking algorithm
85      * </ul>
86      * @param entity a persistent entity
87      * @return array of dirty property indices or <tt>null</tt> to choose default behaviour
88      */
89     public int[] findDirty(Object JavaDoc entity, Serializable JavaDoc id, Object JavaDoc[] currentState, Object JavaDoc[] previousState, String JavaDoc[] propertyNames, Type[] types);
90     /**
91      * Instantiate the entity class. Return <tt>null</tt> to indicate that Hibernate should use
92      * the default constructor of the class. The identifier property of the returned instance
93      * should be initialized with the given identifier.
94      *
95      * @param entityName the name of the entity
96      * @param entityMode The type of entity instance to be returned.
97      * @param id the identifier of the new instance
98      * @return an instance of the class, or <tt>null</tt> to choose default behaviour
99      */
100     public Object JavaDoc instantiate(String JavaDoc entityName, EntityMode entityMode, Serializable JavaDoc id) throws CallbackException;
101
102     /**
103      * Get the entity name for a persistent or transient instance
104      * @param object an entity instance
105      * @return the name of the entity
106      */
107     public String JavaDoc getEntityName(Object JavaDoc object) throws CallbackException;
108
109     /**
110      * Get a fully loaded entity instance that is cached externally
111      * @param entityName the name of the entity
112      * @param id the instance identifier
113      * @return a fully initialized entity
114      * @throws CallbackException
115      */
116     public Object JavaDoc getEntity(String JavaDoc entityName, Serializable JavaDoc id) throws CallbackException;
117     
118     /**
119      * Called when a Hibernate transaction is begun via the Hibernate <tt>Transaction</tt>
120      * API. Will not be called if transactions are being controlled via some other
121      * mechanism (CMT, for example).
122      */
123     public void afterTransactionBegin(Transaction tx);
124     /**
125      * Called before a transaction is committed (but not before rollback).
126      */
127     public void beforeTransactionCompletion(Transaction tx);
128     /**
129      * Called after a transaction is committed or rolled back.
130      */
131     public void afterTransactionCompletion(Transaction tx);
132
133 }
134
Popular Tags