OTMConnection


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 }
267
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags