1 /***
2 * @(#)JDOService.java
3 *
4 * JFoxSOAF, Service-Oriented Application Framework
5 *
6 * Copyright(c) JFoxSOAF Team
7 *
8 * Licensed under the GNU LGPL, Version 2.1 (the "License");
9 * you may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
11 *
12 * http://www.gnu.org/copyleft/lesser.html
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS,
16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 * See the License for the specific language governing permissions and
18 * limitations under the License.
19 *
20 * For more information, please visit:
21 * http://www.jfox.cn/confluence/display/JFoxSOAF/Home
22 * http://www.huihoo.org/jfox/jfoxsoaf
23 */
24
25 package org.huihoo.jfox.soaf.services.persistence;
26
27 import java.util.Collection;
28 import java.util.Map;
29
30 import javax.jdo.JDOException;
31 import javax.jdo.PersistenceManagerFactory;
32
33 import org.huihoo.jfox.soaf.exception.DAOException;
34
35 /***
36 * <p>
37 * JDO persistence service wrapper.
38 * </p>
39 *
40 * @author <a href="mailto:founder_chen@yahoo.com.cn">Peter Cheng </a>
41 * @version $Revision:$ $Date:$
42 * @version Revision: 1.0
43 */
44
45 public interface JdoService {
46
47 /***
48 * Set SessionFactory
49 *
50 * @param sessionFactory
51 */
52 public void setPersistenceManagerFactory(PersistenceManagerFactory pmFactory);
53
54 /***
55 * Begin a transaction.
56 *
57 * @throws JDOException
58 */
59 public void beginTransaction() throws JDOException;
60
61 /***
62 * Commit the current transaction.
63 *
64 * @throws JDOException
65 */
66 public void commit() throws JDOException;
67
68 /***
69 * Roll back the current transaction.
70 *
71 * @throws JDOException
72 */
73 public void rollback() throws JDOException;
74
75 /***
76 * Close this PersistenceManager so that no further requests may be made on
77 * it.
78 */
79 public void close() throws JDOException;
80
81 /***
82 * The ObjectId returned by this method represents the JDO identity of the
83 * instance.
84 *
85 * @param object -
86 * the PersistenceCapable instance
87 * @return - the ObjectId of the instance
88 * @throws DAOException
89 */
90 public Object getObjectById(Object oid) throws JDOException, DAOException;
91
92 /***
93 * Looks up the instance of the given type with the given key.
94 *
95 * @param clazz
96 * @param oid
97 * @return the corresponding persistent instance
98 * @throws DAOException
99 */
100 public Object getObjectById(Class clazz, Object oid) throws JDOException,
101 DAOException;
102
103 /***
104 * This method locates a persistent instance in the cache of instances
105 * managed by this PersistenceManager.
106 *
107 * @param object
108 * @param validate
109 * @return the PersistenceCapable instance with the specified ObjectId
110 * @throws JDOException
111 * @throws DAOException
112 */
113 public Object getObjectById(Object oid, boolean validate)
114 throws JDOException, DAOException;
115
116 /***
117 * The ObjectId returned by this method represents the JDO identity of the
118 * instance. The ObjectId is a copy (clone) of the internal state of the
119 * instance, and changing it does not affect the JDO identity of the
120 * instance.
121 *
122 * @param object
123 * @return the ObjectId of the instance
124 * @throws JDOException
125 * @throws DAOException
126 */
127 public Object getObjectId(Object pc) throws JDOException, DAOException;
128
129 /***
130 * Return the Class that implements the JDO Identity for the specified
131 * PersistenceCapable class.
132 *
133 * @param clazz -
134 * cls - the PersistenceCapable Class
135 * @return the Class of the ObjectId of the parameter
136 * @throws JDOException
137 * @throws DAOException
138 */
139 public Class getObjectIdClass(Class clazz) throws JDOException,
140 DAOException;
141
142 /***
143 * Return the objects with the given oids.
144 *
145 * @param oids
146 * @return the objects that were looked up, in the same order as the oids
147 * parameter.
148 * @throws JDOException
149 * @throws DAOException
150 */
151 public Collection getObjectsById(Collection oids) throws JDOException,
152 DAOException;
153
154 /***
155 * Return the objects with the given oids.
156 *
157 * @param oids
158 * @param validate
159 * validate - if true, the existance of the objects in the
160 * datastore will be validated.
161 * @return the objects that were looked up, in the same order as the oids
162 * parameter.
163 * @throws JDOException
164 * @throws DAOException
165 */
166 public Collection getObjectsById(Collection oids, boolean validate)
167 throws JDOException, DAOException;
168
169 /***
170 * Return the objects with the given oids. This method is equivalent to
171 * calling getObjectsById(Object[],boolean) with the validate flag true.
172 *
173 * @param oids -
174 * the oids of the objects to return
175 * @return the objects that were looked up, in the same order as the oids
176 * parameter.
177 */
178 public Object[] getObjectsById(Object[] oids) throws JDOException,
179 DAOException;
180
181 /***
182 * Return the objects with the given oids.
183 *
184 * @param oids -
185 * the oids of the objects to return
186 * @param validate -
187 * validate - if true, the existance of the objects in the
188 * datastore will be validated.
189 * @return the objects that were looked up, in the same order as the oids
190 * parameter.
191 */
192 public Object[] getObjectsById(Object[] oids, boolean validate)
193 throws JDOException, DAOException;
194
195 /***
196 * @param clazz
197 * @return
198 * @throws JDOException
199 * @throws DAOException
200 */
201 public Collection query(Class clazz) throws JDOException, DAOException;
202
203 /***
204 * Query with the Class of the candidate instances and filter
205 *
206 * @param clazz
207 * @return the filtered Collection
208 * @throws JDOException
209 * @throws DAOException
210 */
211 public Collection query(Class clazz, String filter) throws JDOException,
212 DAOException;
213
214 /***
215 * Query with the Class of the candidate instances and filter
216 *
217 * @param clazz
218 * @return the filtered Collection
219 * @throws JDOException
220 * @throws DAOException
221 */
222 public Collection query(Class clazz, String filter, String ordering)
223 throws JDOException, DAOException;
224
225 /***
226 * Query with the Class of the candidate instances and filter
227 *
228 * @param clazz
229 * @return the filtered Collection
230 * @throws JDOException
231 * @throws DAOException
232 */
233 public Collection queryWithMap(Class clazz, String filter,
234 String parameters, Map values) throws JDOException, DAOException;
235
236 /***
237 * Query with the Class of the candidate instances and filter
238 *
239 * @param clazz
240 * @return the filtered Collection
241 * @throws JDOException
242 * @throws DAOException
243 */
244 public Collection queryWithMap(Class clazz, String filter, String ordering,
245 String parameters, Map values) throws JDOException, DAOException;
246
247 /***
248 * Query with the Class of the candidate instances and filter
249 *
250 * @param clazz
251 * @return the filtered Collection
252 * @throws JDOException
253 * @throws DAOException
254 */
255 public Collection queryWithMap(Class clazz, String filter,
256 String parameters, Object[] values) throws JDOException,
257 DAOException;
258
259 /***
260 * Query with the Class of the candidate instances and filter
261 *
262 * @param clazz
263 * @return the filtered Collection
264 * @throws JDOException
265 * @throws DAOException
266 */
267 public Collection queryWithMap(Class clazz, String filter, String ordering,
268 String parameters, Object[] values) throws JDOException,
269 DAOException;
270
271 /***
272 * Query with the Class of the candidate instances, candidate Collection.
273 *
274 * @param clazz
275 * @return the filtered Collection.
276 * @throws JDOException
277 * @throws DAOException
278 */
279 public Collection query(Class clazz, Collection coll) throws JDOException,
280 DAOException;
281
282 /***
283 * Query with the Class of the candidate instances, candidate Collection,
284 * and filter.
285 *
286 * @param clazz
287 * @return the filtered Collection.
288 * @throws JDOException
289 * @throws DAOException
290 */
291 public Collection query(Class clazz, Collection coll, String filter)
292 throws JDOException, DAOException;
293
294 /***
295 * Query using elements from another Query.
296 *
297 * @param clazz
298 * @return the filtered Collection.
299 * @throws JDOException
300 * @throws DAOException
301 */
302 public Collection query(Object object) throws JDOException, DAOException;
303
304 /***
305 * Query instance using the specified String as the single-string
306 * representation of the query.
307 *
308 * @param clazz
309 * @return the filtered Collection.
310 * @throws JDOException
311 * @throws DAOException
312 */
313 public Collection query(String queryStr) throws JDOException, DAOException;
314
315 /***
316 * Mark an instance as no longer needed in the cache
317 *
318 * @param pc -
319 * the instance to evict from the cache.
320 */
321 public void evict(Object object) throws JDOException, DAOException;
322
323 /***
324 * Mark all persistent-nontransactional instances as no longer needed in the
325 * cache.
326 *
327 * @throws JDOException
328 * @throws DAOException
329 */
330 public void evictAll() throws JDOException, DAOException;
331
332 /***
333 * Mark a Collection of instances as no longer needed in the cache.
334 *
335 * @param pcs
336 * @throws JDOException
337 * @throws DAOException
338 */
339 public void evictAll(Collection coll) throws JDOException, DAOException;
340
341 /***
342 * Mark an array of instances as no longer needed in the cache.
343 *
344 * @param pcs
345 * @throws JDOException
346 * @throws DAOException
347 */
348 public void evictAll(Object[] objects) throws JDOException, DAOException;
349
350 /***
351 * Flushes all dirty, new, and deleted instances to the data store. It has
352 * no effect if a transaction is not active.
353 *
354 * @throws JDOException
355 * @throws DAOException
356 */
357 public void flush() throws JDOException, DAOException;
358
359 /***
360 * Make the transient instance persistent in this PersistenceManager.
361 *
362 * @param object -
363 * a transient instance of a Class that implements
364 * PersistenceCapable
365 * @throws JDOException
366 * @throws DAOException
367 */
368 public void makePersistent(Object object) throws JDOException, DAOException;
369
370 /***
371 * Make a Collection of instances persistent.
372 *
373 * @param coll -
374 * a Collection of transient instances
375 */
376 public void makePersistentAll(Collection coll) throws JDOException,
377 DAOException;
378
379 /***
380 * Make an array of instances persistent.
381 *
382 * @param pcs
383 */
384 public void makePersistentAll(Object[] objects) throws JDOException,
385 DAOException;
386
387 /***
388 * Delete the persistent instance from the data store.
389 *
390 * @param pc
391 * @throws JDOException
392 * @throws DAOException
393 */
394 public void deletePersistent(Object object) throws JDOException,
395 DAOException;
396
397 /***
398 * Delete a Collection of instances from the data store.
399 *
400 * @param pcs
401 * @throws JDOException
402 * @throws DAOException
403 */
404 public void deletePersistentAll(Collection coll) throws JDOException,
405 DAOException;
406
407 /***
408 * Delete an array of instances from the data store.
409 *
410 * @param pcs
411 */
412 public void deletePersistentAll(Object[] objects) throws JDOException,
413 DAOException;
414
415 }