Coverage Report

Coverage Report - org.apache.ojb.otm.OTMConnection

Classes in this File

 package org.apache.ojb.otm;
 
 /* Copyright 2003-2005 The Apache Software Foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 import java.util.Collection;
 import java.util.Iterator;
 import org.apache.ojb.broker.Identity;
 import org.apache.ojb.broker.cache.ObjectCache;
 import org.apache.ojb.broker.metadata.ClassDescriptor;
 import org.apache.ojb.broker.query.Query;
 import org.apache.ojb.otm.lock.LockingException;
 import org.apache.ojb.otm.core.Transaction;
 import org.apache.ojb.odmg.oql.EnhancedOQLQuery;
 import org.odmg.OQLQuery;
 
 /**
  *
  *  A OTMConnection within the given Environment
  *
  *  @author <a href="mailto:rraghuram@hotmail.com">Raghu Rajah</a>
  */
 public interface OTMConnection
 {
 
     /**
      *
      * Make the given object persistent by inserting it into the database.
      * Also read locks the object (OTM will automatically lock
      * it for write on transaction commit if the object will appear
      * to be modified).
      *
      * @param object       the object to be made persistent
      *
      */
     public void makePersistent(Object object)
             throws LockingException;
 
     /**
      * Obtain the Transaction this connection is associated with
      */
     public Transaction getTransaction();
 
     /**
      * Associate this connection with a given transaction.
      */
     public void setTransaction(Transaction tx);
 
     /**
      *
      *  Mark the given object for deletion from the persistent store. The object would then become
      *  a transient object, rather than a persistent one.
      *
      *  @param obj      the object to delete
      *
      */
     public void deletePersistent(Object obj)
             throws LockingException;
 
     /**
      *
      *  Lock the given object for Write. Only write locked objects are persisted back to the
      *  database. Changes to read objects are not inserted back into the database.
      *
      *  @param object       the object to be locked for write.
      *
      */
     public void lockForWrite(Object object)
             throws LockingException;
 
     /**
      *
      *  Get the object with the given Identity from the persistent store. By default, the fetch is
      *  for read. (OTM will automatically lock it for write on transaction commit
      * if the object will appear to be modified).
      *
      *  @param oid                  the Identity of the object to fetch
      *  @return                     the object from the persistent store.
      *  @throws LockingException    thrown by the LockManager to avoid deadlocks. The fetch could be
      *                              re-submitted.
      *
      */
     public Object getObjectByIdentity(Identity oid)
             throws LockingException;
 
     /**
      *
      * Get the object with the given Identity from the persistent store with the given lock value.
      *
      * @param oid                   the Identity of the object to fetch
      * @param lock                  the lock that need to be acquired on the object
      * Possible values are:
      * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
      * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
      * in this case the lock will be automatically upgraded to the write lock on transaction commit;
      * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
      *
      * @return                     the object from the persistent store.
      * @throws LockingException     thrown by the LockManager to avoid a deadlock.
      *
      */
     public Object getObjectByIdentity(Identity oid, int lock)
             throws LockingException;
 
     /**
      * @param query The query to execute
      * @return an Iterator that iterates Objects of class c if calling the .next()
      * method. The returned objects are locked for read.
      */
     public Iterator getIteratorByQuery(Query query);
 
     /**
      * @param query The query to execute
      * @param lock the lock that need to be acquired on the object
      * Possible values are:
      * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
      * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
      * in this case the lock will be automatically upgraded to the write lock on transaction commit;
      * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
      * @return an Iterator that iterates Objects of class c if calling the .next()
      * method. The returned objects are locked with the given lock value.
      */
     public Iterator getIteratorByQuery(Query query, int lock);
 
     /**
      * @param query The OQL query to execute
      * @return an Iterator that iterates Objects of class c if calling the .next()
      * method. The returned objects are locked for read.
      */
     public Iterator getIteratorByOQLQuery(OQLQuery query);
 
     /**
      * @param query The OQL query to execute
      * @param lock the lock that need to be acquired on the object
      * Possible values are:
      * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
      * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
      * in this case the lock will be automatically upgraded to the write lock on transaction commit;
      * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
      * @return an Iterator that iterates Objects of class c if calling the .next()
      * method. The returned objects are locked for read.
      */
     public Iterator getIteratorByOQLQuery(OQLQuery query, int lock);
 
     /**
      * @param query The query to execute
      * @param lock the lock that need to be acquired on the object
      * Possible values are:
      * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
      * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
      * in this case the lock will be automatically upgraded to the write lock on transaction commit;
      * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
      * @return an Iterator that iterates Objects of class c if calling the .next()
      * method. The returned objects are locked with the given lock value.
      */
     public Collection getCollectionByQuery(Query query, int lock);
 
     /**
      * @param query The query to execute
      * @return an Iterator that iterates Objects of class c if calling the .next()
      * method. The returned objects are locked for read.
      */
     public Collection getCollectionByQuery(Query query);
 
     /**
      * Get the identity of the object
      * @param object The object
      * @return the identity of the object
      */
     public Identity getIdentity(Object object);
 
     public ClassDescriptor getDescriptorFor(Class clazz);
 
     /**
      *
      *  Get the EditingContext associated with the transaction to which this connection belongs.
      *  EditingContext contains and manages the set of objects read/edited within the current
      *  transaction.
      *
      *  @return                     EditingContext associated with current Transaction
      *
      */
     public EditingContext getEditingContext();
 
     /**
      * In the case if the program need to change the objects
      * via direct JDBC call, it should first call invalidate()
      * for the object, which will lock the object for write
      * and tell OJB OTM that it must be re-read from the database,
      * only after that you shold perform JDBC operation.
      * NOTE: it is not recommended to use read-uncommitted isolation
      * if you want this feature to work correctly.
      */
     public void invalidate(Identity oid)
             throws LockingException;
 
     /**
      * clear the underlying caches
      */
     public void invalidateAll()
             throws LockingException;
 
     /**
      * returns a new OQL Query. This OQL query is Enhanced, meaning it does
      * the ODMG functionality as well as some additional OJB specific, non
      * portable functionality.
      * @return the new OQLQuery
      */
     public EnhancedOQLQuery newOQLQuery();
 
     /**
      * returns a new OQL Query. This OQL query is Enhanced, meaning it does
      * the ODMG functionality as well as some additional OJB specific, non
      * portable functionality.
      * @param lock the lock that need to be acquired on the object
      * Possible values are:
      * LockType.NO_LOCK (aka read only) - changes to the object will not be written to database;
      * LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database,
      * in this case the lock will be automatically upgraded to the write lock on transaction commit;
      * LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.
      * @return the new OQLQuery
      */
     public EnhancedOQLQuery newOQLQuery(int lock);
 
     /**
      * return the number of objects that would be returned from this query
      * @param query
      * @return the number of objects that would be returned from this query
      */
     int getCount(Query query);
 
     /**
      * Close the OTMConnection
      */
     void close();
 
     /**
      * check if the OTMConnection is closed
      */
 
     boolean isClosed();
 
     /**
      * get the global cache
      * @return
      */
     ObjectCache serviceObjectCache();
 
     /**
      * Updates the values in the object from the data in data store.
      * The state of the object becomes "Persistent-clean".
      */
     void refresh(Object object);
 }

1		package org.apache.ojb.otm;
2
3		/* Copyright 2003-2005 The Apache Software Foundation
4		*
5		* Licensed under the Apache License, Version 2.0 (the "License");
6		* you may not use this file except in compliance with the License.
7		* You may obtain a copy of the License at
8		*
9		* http://www.apache.org/licenses/LICENSE-2.0
10		*
11		* Unless required by applicable law or agreed to in writing, software
12		* distributed under the License is distributed on an "AS IS" BASIS,
13		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14		* See the License for the specific language governing permissions and
15		* limitations under the License.
16		*/
17
18		import java.util.Collection;
19		import java.util.Iterator;
20		import org.apache.ojb.broker.Identity;
21		import org.apache.ojb.broker.cache.ObjectCache;
22		import org.apache.ojb.broker.metadata.ClassDescriptor;
23		import org.apache.ojb.broker.query.Query;
24		import org.apache.ojb.otm.lock.LockingException;
25		import org.apache.ojb.otm.core.Transaction;
26		import org.apache.ojb.odmg.oql.EnhancedOQLQuery;
27		import org.odmg.OQLQuery;
28
29		/**
30		*
31		* A OTMConnection within the given Environment
32		*
33		* @author <a href="mailto:rraghuram@hotmail.com">Raghu Rajah</a>
34		*/
35		public interface OTMConnection
36		{
37
38		/**
39		*
40		* Make the given object persistent by inserting it into the database.
41		* Also read locks the object (OTM will automatically lock
42		* it for write on transaction commit if the object will appear
43		* to be modified).
44		*
45		* @param object the object to be made persistent
46		*
47		*/
48		public void makePersistent(Object object)
49		throws LockingException;
50
51		/**
52		* Obtain the Transaction this connection is associated with
53		*/
54		public Transaction getTransaction();
55
56		/**
57		* Associate this connection with a given transaction.
58		*/
59		public void setTransaction(Transaction tx);
60
61		/**
62		*
63		* Mark the given object for deletion from the persistent store. The object would then become
64		* a transient object, rather than a persistent one.
65		*
66		* @param obj the object to delete
67		*
68		*/
69		public void deletePersistent(Object obj)
70		throws LockingException;
71
72		/**
73		*
74		* Lock the given object for Write. Only write locked objects are persisted back to the
75		* database. Changes to read objects are not inserted back into the database.
76		*
77		* @param object the object to be locked for write.
78		*
79		*/
80		public void lockForWrite(Object object)
81		throws LockingException;
82
83		/**
84		*
85		* Get the object with the given Identity from the persistent store. By default, the fetch is
86		* for read. (OTM will automatically lock it for write on transaction commit
87		* if the object will appear to be modified).
88		*
89		* @param oid the Identity of the object to fetch
90		* @return the object from the persistent store.
91		* @throws LockingException thrown by the LockManager to avoid deadlocks. The fetch could be
92		* re-submitted.
93		*
94		*/
95		public Object getObjectByIdentity(Identity oid)
96		throws LockingException;
97
98		/**
99		*
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		}