← Back to branch summary

~ubuntu-branches/ubuntu/wily/libhibernate3-java/wily-proposed

« back to all changes in this revision

Viewing changes to src/org/hibernate/Interceptor.java

  • Committer: Bazaar Package Importer
  • Author(s): Torsten Werner
  • Date: 2007-10-14 14:43:34 UTC
  • Revision ID: james.westby@ubuntu.com-20071014144334-eamc8i0q10gs1aro
Tags: upstream-3.2.5
Import upstream version 3.2.5

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/org/hibernate/Interceptor.java
 
1
//$Id: Interceptor.java 7883 2005-08-12 20:03:07Z oneovthafew $
 
2
package org.hibernate;
 
3
 
 
4
import java.io.Serializable;
 
5
import java.util.Iterator;
 
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
 * <br>
 
23
 * Instead of implementing this interface directly, it is usually better to extend <tt>EmptyInterceptor</tt>
 
24
 * and override only the callback methods of interest.
 
25
 *
 
26
 * @see SessionFactory#openSession(Interceptor)
 
27
 * @see org.hibernate.cfg.Configuration#setInterceptor(Interceptor)
 
28
 * @see EmptyInterceptor
 
29
 * @author Gavin King
 
30
 */
 
31
public interface Interceptor {
 
32
        /**
 
33
         * Called just before an object is initialized. The interceptor may change the <tt>state</tt>, which will
 
34
         * be propagated to the persistent object. Note that when this method is called, <tt>entity</tt> will be
 
35
         * an empty uninitialized instance of the class.
 
36
         *
 
37
         * @return <tt>true</tt> if the user modified the <tt>state</tt> in any way.
 
38
         */
 
39
        public boolean onLoad(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types) throws CallbackException;
 
40
        /**
 
41
         * Called when an object is detected to be dirty, during a flush. The interceptor may modify the detected
 
42
         * <tt>currentState</tt>, which will be propagated to both the database and the persistent object.
 
43
         * Note that not all flushes end in actual synchronization with the database, in which case the
 
44
         * new <tt>currentState</tt> will be propagated to the object, but not necessarily (immediately) to
 
45
         * the database. It is strongly recommended that the interceptor <b>not</b> modify the <tt>previousState</tt>.
 
46
         *
 
47
         * @return <tt>true</tt> if the user modified the <tt>currentState</tt> in any way.
 
48
         */
 
49
        public boolean onFlushDirty(Object entity, Serializable id, Object[] currentState, Object[] previousState, String[] propertyNames, Type[] types) throws CallbackException;
 
50
        /**
 
51
         * Called before an object is saved. The interceptor may modify the <tt>state</tt>, which will be used for
 
52
         * the SQL <tt>INSERT</tt> and propagated to the persistent object.
 
53
         *
 
54
         * @return <tt>true</tt> if the user modified the <tt>state</tt> in any way.
 
55
         */
 
56
        public boolean onSave(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types) throws CallbackException;
 
57
        /**
 
58
         *  Called before an object is deleted. It is not recommended that the interceptor modify the <tt>state</tt>.
 
59
         */
 
60
        public void onDelete(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types) throws CallbackException;
 
61
        /**
 
62
         * Called before a collection is (re)created.
 
63
         */
 
64
        public void onCollectionRecreate(Object collection, Serializable key) throws CallbackException;
 
65
        /**
 
66
         * Called before a collection is deleted.
 
67
         */
 
68
        public void onCollectionRemove(Object collection, Serializable key) throws CallbackException;
 
69
        /**
 
70
         * Called before a collection is updated.
 
71
         */
 
72
        public void onCollectionUpdate(Object collection, Serializable key) throws CallbackException;
 
73
        /**
 
74
         * Called before a flush
 
75
         */
 
76
        public void preFlush(Iterator entities) throws CallbackException;
 
77
        /**
 
78
         * Called after a flush that actually ends in execution of the SQL statements required to synchronize
 
79
         * in-memory state with the database.
 
80
         */
 
81
        public void postFlush(Iterator entities) throws CallbackException;
 
82
        /**
 
83
         * Called to distinguish between transient and detached entities. The return value determines the
 
84
         * state of the entity with respect to the current session.
 
85
         * <ul>
 
86
         * <li><tt>Boolean.TRUE</tt> - the entity is transient
 
87
         * <li><tt>Boolean.FALSE</tt> - the entity is detached
 
88
         * <li><tt>null</tt> - Hibernate uses the <tt>unsaved-value</tt> mapping and other heuristics to 
 
89
         * determine if the object is unsaved
 
90
         * </ul>
 
91
         * @param entity a transient or detached entity
 
92
         * @return Boolean or <tt>null</tt> to choose default behaviour
 
93
         */
 
94
        public Boolean isTransient(Object entity);
 
95
        /**
 
96
         * Called from <tt>flush()</tt>. The return value determines whether the entity is updated
 
97
         * <ul>
 
98
         * <li>an array of property indices - the entity is dirty
 
99
         * <li>an empty array - the entity is not dirty
 
100
         * <li><tt>null</tt> - use Hibernate's default dirty-checking algorithm
 
101
         * </ul>
 
102
         * @param entity a persistent entity
 
103
         * @return array of dirty property indices or <tt>null</tt> to choose default behaviour
 
104
         */
 
105
        public int[] findDirty(Object entity, Serializable id, Object[] currentState, Object[] previousState, String[] propertyNames, Type[] types);
 
106
        /**
 
107
         * Instantiate the entity class. Return <tt>null</tt> to indicate that Hibernate should use
 
108
         * the default constructor of the class. The identifier property of the returned instance
 
109
         * should be initialized with the given identifier.
 
110
         *
 
111
         * @param entityName the name of the entity
 
112
         * @param entityMode The type of entity instance to be returned.
 
113
         * @param id the identifier of the new instance
 
114
         * @return an instance of the class, or <tt>null</tt> to choose default behaviour
 
115
         */
 
116
        public Object instantiate(String entityName, EntityMode entityMode, Serializable id) throws CallbackException;
 
117
 
 
118
        /**
 
119
         * Get the entity name for a persistent or transient instance
 
120
         * @param object an entity instance
 
121
         * @return the name of the entity
 
122
         */
 
123
        public String getEntityName(Object object) throws CallbackException;
 
124
 
 
125
        /**
 
126
         * Get a fully loaded entity instance that is cached externally
 
127
         * @param entityName the name of the entity
 
128
         * @param id the instance identifier
 
129
         * @return a fully initialized entity
 
130
         * @throws CallbackException
 
131
         */
 
132
        public Object getEntity(String entityName, Serializable id) throws CallbackException;
 
133
        
 
134
        /**
 
135
         * Called when a Hibernate transaction is begun via the Hibernate <tt>Transaction</tt> 
 
136
         * API. Will not be called if transactions are being controlled via some other 
 
137
         * mechanism (CMT, for example).
 
138
         */
 
139
        public void afterTransactionBegin(Transaction tx);
 
140
        /**
 
141
         * Called before a transaction is committed (but not before rollback).
 
142
         */
 
143
        public void beforeTransactionCompletion(Transaction tx);
 
144
        /**
 
145
         * Called after a transaction is committed or rolled back.
 
146
         */
 
147
        public void afterTransactionCompletion(Transaction tx);
 
148
 
 
149
        /**
 
150
         * Called when sql string is being prepared. 
 
151
         * @param sql sql to be prepared
 
152
         * @return original or modified sql
 
153
         */
 
154
        public String onPrepareStatement(String sql);
 
155
}