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: * Make the given object persistent by inserting it into the database.
040: * Also read locks the object (OTM will automatically lock
041: * it for write on transaction commit if the object will appear
042: * to be modified).
043: *
044: * @param object the object to be made persistent
045: *
046: */
047: public void makePersistent(Object object) throws LockingException;
048:
049: /**
050: * Obtain the Transaction this connection is associated with
051: */
052: public Transaction getTransaction();
053:
054: /**
055: * Associate this connection with a given transaction.
056: */
057: public void setTransaction(Transaction tx);
058:
059: /**
060: *
061: * Mark the given object for deletion from the persistent store. The object would then become
062: * a transient object, rather than a persistent one.
063: *
064: * @param obj the object to delete
065: *
066: */
067: public void deletePersistent(Object obj) throws LockingException;
068:
069: /**
070: *
071: * Lock the given object for Write. Only write locked objects are persisted back to the
072: * database. Changes to read objects are not inserted back into the database.
073: *
074: * @param object the object to be locked for write.
075: *
076: */
077: public void lockForWrite(Object object) throws LockingException;
078:
079: /**
080: *
081: * Get the object with the given Identity from the persistent store. By default, the fetch is
082: * for read. (OTM will automatically lock it for write on transaction commit
083: * if the object will appear to be modified).
084: *
085: * @param oid the Identity of the object to fetch
086: * @return the object from the persistent store.
087: * @throws LockingException thrown by the LockManager to avoid deadlocks. The fetch could be
088: * re-submitted.
089: *
090: */
091: public Object getObjectByIdentity(Identity oid)
092: throws LockingException;
093:
094: /**
095: *
096: * Get the object with the given Identity from the persistent store with the given lock value.
097: *
098: * @param oid the Identity of the object to fetch
099: * @param lock the lock that need to be acquired on the object
100: * Possible values are:
101: * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
102: * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
103: * in this case the lock will be automatically upgraded to the write lock on transaction commit;
104: * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
105: *
106: * @return the object from the persistent store.
107: * @throws LockingException thrown by the LockManager to avoid a deadlock.
108: *
109: */
110: public Object getObjectByIdentity(Identity oid, int lock)
111: throws LockingException;
112:
113: /**
114: * @param query The query to execute
115: * @return an Iterator that iterates Objects of class c if calling the .next()
116: * method. The returned objects are locked for read.
117: */
118: public Iterator getIteratorByQuery(Query query);
119:
120: /**
121: * @param query The query to execute
122: * @param lock the lock that need to be acquired on the object
123: * Possible values are:
124: * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
125: * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
126: * in this case the lock will be automatically upgraded to the write lock on transaction commit;
127: * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
128: * @return an Iterator that iterates Objects of class c if calling the .next()
129: * method. The returned objects are locked with the given lock value.
130: */
131: public Iterator getIteratorByQuery(Query query, int lock);
132:
133: /**
134: * @param query The OQL query to execute
135: * @return an Iterator that iterates Objects of class c if calling the .next()
136: * method. The returned objects are locked for read.
137: */
138: public Iterator getIteratorByOQLQuery(OQLQuery query);
139:
140: /**
141: * @param query The OQL query to execute
142: * @param lock the lock that need to be acquired on the object
143: * Possible values are:
144: * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
145: * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
146: * in this case the lock will be automatically upgraded to the write lock on transaction commit;
147: * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
148: * @return an Iterator that iterates Objects of class c if calling the .next()
149: * method. The returned objects are locked for read.
150: */
151: public Iterator getIteratorByOQLQuery(OQLQuery query, int lock);
152:
153: /**
154: * @param query The query to execute
155: * @param lock the lock that need to be acquired on the object
156: * Possible values are:
157: * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
158: * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
159: * in this case the lock will be automatically upgraded to the write lock on transaction commit;
160: * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
161: * @return an Iterator that iterates Objects of class c if calling the .next()
162: * method. The returned objects are locked with the given lock value.
163: */
164: public Collection getCollectionByQuery(Query query, int lock);
165:
166: /**
167: * @param query The query to execute
168: * @return an Iterator that iterates Objects of class c if calling the .next()
169: * method. The returned objects are locked for read.
170: */
171: public Collection getCollectionByQuery(Query query);
172:
173: /**
174: * Get the identity of the object
175: * @param object The object
176: * @return the identity of the object
177: */
178: public Identity getIdentity(Object object);
179:
180: public ClassDescriptor getDescriptorFor(Class clazz);
181:
182: /**
183: *
184: * Get the EditingContext associated with the transaction to which this connection belongs.
185: * EditingContext contains and manages the set of objects read/edited within the current
186: * transaction.
187: *
188: * @return EditingContext associated with current Transaction
189: *
190: */
191: public EditingContext getEditingContext();
192:
193: /**
194: * In the case if the program need to change the objects
195: * via direct JDBC call, it should first call invalidate()
196: * for the object, which will lock the object for write
197: * and tell OJB OTM that it must be re-read from the database,
198: * only after that you shold perform JDBC operation.
199: * NOTE: it is not recommended to use read-uncommitted isolation
200: * if you want this feature to work correctly.
201: */
202: public void invalidate(Identity oid) throws LockingException;
203:
204: /**
205: * clear the underlying caches
206: */
207: public void invalidateAll() throws LockingException;
208:
209: /**
210: * returns a new OQL Query. This OQL query is Enhanced, meaning it does
211: * the ODMG functionality as well as some additional OJB specific, non
212: * portable functionality.
213: * @return the new OQLQuery
214: */
215: public EnhancedOQLQuery newOQLQuery();
216:
217: /**
218: * returns a new OQL Query. This OQL query is Enhanced, meaning it does
219: * the ODMG functionality as well as some additional OJB specific, non
220: * portable functionality.
221: * @param lock the lock that need to be acquired on the object
222: * Possible values are:
223: * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
224: * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
225: * in this case the lock will be automatically upgraded to the write lock on transaction commit;
226: * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
227: * @return the new OQLQuery
228: */
229: public EnhancedOQLQuery newOQLQuery(int lock);
230:
231: /**
232: * return the number of objects that would be returned from this query
233: * @param query
234: * @return the number of objects that would be returned from this query
235: */
236: int getCount(Query query);
237:
238: /**
239: * Close the OTMConnection
240: */
241: void close();
242:
243: /**
244: * check if the OTMConnection is closed
245: */
246:
247: boolean isClosed();
248:
249: /**
250: * get the global cache
251: * @return
252: */
253: ObjectCache serviceObjectCache();
254:
255: /**
256: * Updates the values in the object from the data in data store.
257: * The state of the object becomes "Persistent-clean".
258: */
259: void refresh(Object object);
260: }
|