001 package org.apache.ojb.otm;
002
003 /* Copyright 2003-2005 The Apache Software Foundation
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 import java.util.Collection;
019 import java.util.Iterator;
020 import org.apache.ojb.broker.Identity;
021 import org.apache.ojb.broker.cache.ObjectCache;
022 import org.apache.ojb.broker.metadata.ClassDescriptor;
023 import org.apache.ojb.broker.query.Query;
024 import org.apache.ojb.otm.lock.LockingException;
025 import org.apache.ojb.otm.core.Transaction;
026 import org.apache.ojb.odmg.oql.EnhancedOQLQuery;
027 import org.odmg.OQLQuery;
028
029 /**
030 *
031 * A OTMConnection within the given Environment
032 *
033 * @author <a href="mailto:rraghuram@hotmail.com">Raghu Rajah</a>
034 */
035 public interface OTMConnection
036 {
037
038 /**
039 *
040 * Make the given object persistent by inserting it into the database.
041 * Also read locks the object (OTM will automatically lock
042 * it for write on transaction commit if the object will appear
043 * to be modified).
044 *
045 * @param object the object to be made persistent
046 *
047 */
048 public void makePersistent(Object object)
049 throws LockingException;
050
051 /**
052 * Obtain the Transaction this connection is associated with
053 */
054 public Transaction getTransaction();
055
056 /**
057 * Associate this connection with a given transaction.
058 */
059 public void setTransaction(Transaction tx);
060
061 /**
062 *
063 * Mark the given object for deletion from the persistent store. The object would then become
064 * a transient object, rather than a persistent one.
065 *
066 * @param obj the object to delete
067 *
068 */
069 public void deletePersistent(Object obj)
070 throws LockingException;
071
072 /**
073 *
074 * Lock the given object for Write. Only write locked objects are persisted back to the
075 * database. Changes to read objects are not inserted back into the database.
076 *
077 * @param object the object to be locked for write.
078 *
079 */
080 public void lockForWrite(Object object)
081 throws LockingException;
082
083 /**
084 *
085 * Get the object with the given Identity from the persistent store. By default, the fetch is
086 * for read. (OTM will automatically lock it for write on transaction commit
087 * if the object will appear to be modified).
088 *
089 * @param oid the Identity of the object to fetch
090 * @return the object from the persistent store.
091 * @throws LockingException thrown by the LockManager to avoid deadlocks. The fetch could be
092 * re-submitted.
093 *
094 */
095 public Object getObjectByIdentity(Identity oid)
096 throws LockingException;
097
098 /**
099 *
100 * Get the object with the given Identity from the persistent store with the given lock value.
101 *
102 * @param oid the Identity of the object to fetch
103 * @param lock the lock that need to be acquired on the object
104 * Possible values are:
105 * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
106 * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
107 * in this case the lock will be automatically upgraded to the write lock on transaction commit;
108 * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
109 *
110 * @return the object from the persistent store.
111 * @throws LockingException thrown by the LockManager to avoid a deadlock.
112 *
113 */
114 public Object getObjectByIdentity(Identity oid, int lock)
115 throws LockingException;
116
117 /**
118 * @param query The query to execute
119 * @return an Iterator that iterates Objects of class c if calling the .next()
120 * method. The returned objects are locked for read.
121 */
122 public Iterator getIteratorByQuery(Query query);
123
124 /**
125 * @param query The query to execute
126 * @param lock the lock that need to be acquired on the object
127 * Possible values are:
128 * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
129 * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
130 * in this case the lock will be automatically upgraded to the write lock on transaction commit;
131 * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
132 * @return an Iterator that iterates Objects of class c if calling the .next()
133 * method. The returned objects are locked with the given lock value.
134 */
135 public Iterator getIteratorByQuery(Query query, int lock);
136
137 /**
138 * @param query The OQL query to execute
139 * @return an Iterator that iterates Objects of class c if calling the .next()
140 * method. The returned objects are locked for read.
141 */
142 public Iterator getIteratorByOQLQuery(OQLQuery query);
143
144 /**
145 * @param query The OQL query to execute
146 * @param lock the lock that need to be acquired on the object
147 * Possible values are:
148 * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
149 * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
150 * in this case the lock will be automatically upgraded to the write lock on transaction commit;
151 * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
152 * @return an Iterator that iterates Objects of class c if calling the .next()
153 * method. The returned objects are locked for read.
154 */
155 public Iterator getIteratorByOQLQuery(OQLQuery query, int lock);
156
157 /**
158 * @param query The query to execute
159 * @param lock the lock that need to be acquired on the object
160 * Possible values are:
161 * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
162 * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
163 * in this case the lock will be automatically upgraded to the write lock on transaction commit;
164 * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
165 * @return an Iterator that iterates Objects of class c if calling the .next()
166 * method. The returned objects are locked with the given lock value.
167 */
168 public Collection getCollectionByQuery(Query query, int lock);
169
170 /**
171 * @param query The query to execute
172 * @return an Iterator that iterates Objects of class c if calling the .next()
173 * method. The returned objects are locked for read.
174 */
175 public Collection getCollectionByQuery(Query query);
176
177 /**
178 * Get the identity of the object
179 * @param object The object
180 * @return the identity of the object
181 */
182 public Identity getIdentity(Object object);
183
184 public ClassDescriptor getDescriptorFor(Class clazz);
185
186 /**
187 *
188 * Get the EditingContext associated with the transaction to which this connection belongs.
189 * EditingContext contains and manages the set of objects read/edited within the current
190 * transaction.
191 *
192 * @return EditingContext associated with current Transaction
193 *
194 */
195 public EditingContext getEditingContext();
196
197 /**
198 * In the case if the program need to change the objects
199 * via direct JDBC call, it should first call invalidate()
200 * for the object, which will lock the object for write
201 * and tell OJB OTM that it must be re-read from the database,
202 * only after that you shold perform JDBC operation.
203 * NOTE: it is not recommended to use read-uncommitted isolation
204 * if you want this feature to work correctly.
205 */
206 public void invalidate(Identity oid)
207 throws LockingException;
208
209 /**
210 * clear the underlying caches
211 */
212 public void invalidateAll()
213 throws LockingException;
214
215 /**
216 * returns a new OQL Query. This OQL query is Enhanced, meaning it does
217 * the ODMG functionality as well as some additional OJB specific, non
218 * portable functionality.
219 * @return the new OQLQuery
220 */
221 public EnhancedOQLQuery newOQLQuery();
222
223 /**
224 * returns a new OQL Query. This OQL query is Enhanced, meaning it does
225 * the ODMG functionality as well as some additional OJB specific, non
226 * portable functionality.
227 * @param lock the lock that need to be acquired on the object
228 * Possible values are:
229 * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
230 * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
231 * in this case the lock will be automatically upgraded to the write lock on transaction commit;
232 * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
233 * @return the new OQLQuery
234 */
235 public EnhancedOQLQuery newOQLQuery(int lock);
236
237 /**
238 * return the number of objects that would be returned from this query
239 * @param query
240 * @return the number of objects that would be returned from this query
241 */
242 int getCount(Query query);
243
244 /**
245 * Close the OTMConnection
246 */
247 void close();
248
249 /**
250 * check if the OTMConnection is closed
251 */
252
253 boolean isClosed();
254
255 /**
256 * get the global cache
257 * @return
258 */
259 ObjectCache serviceObjectCache();
260
261 /**
262 * Updates the values in the object from the data in data store.
263 * The state of the object becomes "Persistent-clean".
264 */
265 void refresh(Object object);
266 }