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.PersistenceManager;
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 * The Transaction instance is always associated with exactly one
49 * PersistenceManager.
50 *
51 * @return PersistenceManager
52 * @throws JDOException
53 */
54 public PersistenceManager getPersistenceManager() throws JDOException;
55
56 /***
57 * Begin a transaction.
58 *
59 * @throws JDOException
60 */
61 public void beginTransaction() throws JDOException;
62
63 /***
64 * Commit the current transaction.
65 *
66 * @throws JDOException
67 */
68 public void commit() throws JDOException;
69
70 /***
71 * Roll back the current transaction.
72 *
73 * @throws JDOException
74 */
75 public void rollback() throws JDOException;
76
77 /***
78 * Close this PersistenceManager so that no further requests may be made on
79 * it.
80 */
81 public void close() throws JDOException;
82
83 /***
84 * The ObjectId returned by this method represents the JDO identity of the
85 * instance.
86 *
87 * @param object - the PersistenceCapable instance
88 * @return - the ObjectId of the instance
89 * @throws DAOException
90 */
91 public Object getObjectById(Object oid) throws JDOException, DAOException;
92
93 /***
94 * Looks up the instance of the given type with the given key.
95 *
96 * @param clazz
97 * @param oid
98 * @return the corresponding persistent instance
99 * @throws DAOException
100 */
101 public Object getObjectById(Class clazz, Object oid) throws JDOException,
102 DAOException;
103
104 /***
105 * This method locates a persistent instance in the cache of instances
106 * managed by this PersistenceManager.
107 *
108 * @param object
109 * @param validate
110 * @return the PersistenceCapable instance with the specified ObjectId
111 * @throws JDOException
112 * @throws DAOException
113 */
114 public Object getObjectById(Object oid, boolean validate)
115 throws JDOException, DAOException;
116
117 /***
118 * The ObjectId returned by this method represents the JDO identity of the
119 * instance. The ObjectId is a copy (clone) of the internal state of the
120 * instance, and changing it does not affect the JDO identity of the
121 * instance.
122 *
123 * @param object
124 * @return the ObjectId of the instance
125 * @throws JDOException
126 * @throws DAOException
127 */
128 public Object getObjectId(Object pc) throws JDOException, DAOException;
129
130 /***
131 * Return the Class that implements the JDO Identity for the specified
132 * PersistenceCapable class.
133 *
134 * @param clazz - 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 validate - if true, the existance of the objects in the
159 * datastore will be validated.
160 * @return the objects that were looked up, in the same order as the oids
161 * parameter.
162 * @throws JDOException
163 * @throws DAOException
164 */
165 public Collection getObjectsById(Collection oids, boolean validate)
166 throws JDOException, DAOException;
167
168 /***
169 * Return the objects with the given oids. This method is equivalent to
170 * calling getObjectsById(Object[],boolean) with the validate flag true.
171 *
172 * @param oids - the oids of the objects to return
173 * @return the objects that were looked up, in the same order as the oids
174 * parameter.
175 */
176 public Object[] getObjectsById(Object[] oids) throws JDOException,
177 DAOException;
178
179 /***
180 * Return the objects with the given oids.
181 *
182 * @param oids - the oids of the objects to return
183 * @param validate - validate - if true, the existance of the objects in the
184 * datastore will be validated.
185 * @return the objects that were looked up, in the same order as the oids
186 * parameter.
187 */
188 public Object[] getObjectsById(Object[] oids, boolean validate)
189 throws JDOException, DAOException;
190
191 /***
192 * @param clazz
193 * @return
194 * @throws JDOException
195 * @throws DAOException
196 */
197 public Collection query(Class clazz) throws JDOException, DAOException;
198
199 /***
200 * Query with the Class of the candidate instances and filter
201 *
202 * @param clazz
203 * @return the filtered Collection
204 * @throws JDOException
205 * @throws DAOException
206 */
207 public Collection query(Class clazz, String filter) throws JDOException,
208 DAOException;
209
210 /***
211 * Query with the Class of the candidate instances and filter
212 *
213 * @param clazz
214 * @return the filtered Collection
215 * @throws JDOException
216 * @throws DAOException
217 */
218 public Collection query(Class clazz, String filter, String ordering)
219 throws JDOException, DAOException;
220
221 /***
222 * Query with the Class of the candidate instances and filter
223 *
224 * @param clazz
225 * @return the filtered Collection
226 * @throws JDOException
227 * @throws DAOException
228 */
229 public Collection queryWithMap(Class clazz, String filter,
230 String parameters, Map values) throws JDOException, DAOException;
231
232 /***
233 * Query with the Class of the candidate instances and filter
234 *
235 * @param clazz
236 * @return the filtered Collection
237 * @throws JDOException
238 * @throws DAOException
239 */
240 public Collection queryWithMap(Class clazz, String filter, String ordering,
241 String parameters, Map values) throws JDOException, DAOException;
242
243 /***
244 * Query with the Class of the candidate instances and filter
245 *
246 * @param clazz
247 * @return the filtered Collection
248 * @throws JDOException
249 * @throws DAOException
250 */
251 public Collection queryWithMap(Class clazz, String filter,
252 String parameters, Object[] values) throws JDOException,
253 DAOException;
254
255 /***
256 * Query with the Class of the candidate instances and filter
257 *
258 * @param clazz
259 * @return the filtered Collection
260 * @throws JDOException
261 * @throws DAOException
262 */
263 public Collection queryWithMap(Class clazz, String filter, String ordering,
264 String parameters, Object[] values) throws JDOException,
265 DAOException;
266
267 /***
268 * Query with the Class of the candidate instances, candidate Collection.
269 *
270 * @param clazz
271 * @return the filtered Collection.
272 * @throws JDOException
273 * @throws DAOException
274 */
275 public Collection query(Class clazz, Collection coll) throws JDOException,
276 DAOException;
277
278 /***
279 * Query with the Class of the candidate instances, candidate Collection,
280 * and filter.
281 *
282 * @param clazz
283 * @return the filtered Collection.
284 * @throws JDOException
285 * @throws DAOException
286 */
287 public Collection query(Class clazz, Collection coll, String filter)
288 throws JDOException, DAOException;
289
290 /***
291 * Query using elements from another Query.
292 *
293 * @param clazz
294 * @return the filtered Collection.
295 * @throws JDOException
296 * @throws DAOException
297 */
298 public Collection query(Object object) throws JDOException, DAOException;
299
300 /***
301 * Query instance using the specified String as the single-string
302 * representation of the query.
303 *
304 * @param clazz
305 * @return the filtered Collection.
306 * @throws JDOException
307 * @throws DAOException
308 */
309 public Collection query(String queryStr) throws JDOException, DAOException;
310
311 /***
312 * Mark an instance as no longer needed in the cache
313 *
314 * @param pc - the instance to evict from the cache.
315 */
316 public void evict(Object object) throws JDOException, DAOException;
317
318 /***
319 * Mark all persistent-nontransactional instances as no longer needed in the
320 * cache.
321 *
322 * @throws JDOException
323 * @throws DAOException
324 */
325 public void evictAll() throws JDOException, DAOException;
326
327 /***
328 * Mark a Collection of instances as no longer needed in the cache.
329 *
330 * @param pcs
331 * @throws JDOException
332 * @throws DAOException
333 */
334 public void evictAll(Collection coll) throws JDOException, DAOException;
335
336 /***
337 * Mark an array of instances as no longer needed in the cache.
338 *
339 * @param pcs
340 * @throws JDOException
341 * @throws DAOException
342 */
343 public void evictAll(Object[] objects) throws JDOException, DAOException;
344
345 /***
346 * Flushes all dirty, new, and deleted instances to the data store. It has
347 * no effect if a transaction is not active.
348 *
349 * @throws JDOException
350 * @throws DAOException
351 */
352 public void flush() throws JDOException, DAOException;
353
354 /***
355 * Make the transient instance persistent in this PersistenceManager.
356 *
357 * @param object - a transient instance of a Class that implements
358 * PersistenceCapable
359 * @throws JDOException
360 * @throws DAOException
361 */
362 public void makePersistent(Object object) throws JDOException, DAOException;
363
364 /***
365 * Make a Collection of instances persistent.
366 *
367 * @param coll - a Collection of transient instances
368 */
369 public void makePersistentAll(Collection coll) throws JDOException,
370 DAOException;
371
372 /***
373 * Make an array of instances persistent.
374 *
375 * @param pcs
376 */
377 public void makePersistentAll(Object[] objects) throws JDOException,
378 DAOException;
379
380 /***
381 * Delete the persistent instance from the data store.
382 *
383 * @param pc
384 * @throws JDOException
385 * @throws DAOException
386 */
387 public void deletePersistent(Object object) throws JDOException,
388 DAOException;
389
390 /***
391 * Delete a Collection of instances from the data store.
392 *
393 * @param pcs
394 * @throws JDOException
395 * @throws DAOException
396 */
397 public void deletePersistentAll(Collection coll) throws JDOException,
398 DAOException;
399
400 /***
401 * Delete an array of instances from the data store.
402 *
403 * @param pcs
404 */
405 public void deletePersistentAll(Object[] objects) throws JDOException, DAOException;
406
407 }