1 /***
2 * @(#)HibernateService.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.io.Serializable;
28 import java.util.Iterator;
29 import java.util.List;
30
31 import net.sf.hibernate.HibernateException;
32 import net.sf.hibernate.LockMode;
33 import net.sf.hibernate.Session;
34 import net.sf.hibernate.SessionFactory;
35 import net.sf.hibernate.type.Type;
36
37 import org.huihoo.jfox.soaf.exception.DAOException;
38
39 /***
40 * <p>
41 * Hibernate persistence service, Wrapper service for hibernate.
42 * </p>
43 *
44 * @author <a href="mailto:founder_chen@yahoo.com.cn">Peter Cheng </a>
45 * @version $Revision: 1.6 $ $Date: 2006/02/15 08:45:45 $
46 * @version Revision: 1.0
47 */
48
49 public interface HibernateService {
50
51 /***
52 * Set SessionFactory
53 *
54 * @param sessionFactory
55 */
56 void setSessionFactory(SessionFactory sessionFactory);
57
58 /***
59 * Create database connection and open a Session on it.
60 *
61 * @return a Hibernate Session object
62 */
63 Session openSession() throws HibernateException;
64
65 /***
66 * commit transaction currently underway, and start new one ( as side effect
67 * hibernate session will be flushed )
68 */
69 void commit() throws HibernateException;
70
71 /***
72 * rollback active transaction if any was started. transaction will be reset
73 *
74 * @throws HibernateException
75 * if transaction can not be rolled back
76 */
77 void rollback() throws HibernateException;
78
79 /***
80 * normal session close. commit transaction is any
81 */
82 void closeSession() throws HibernateException;
83
84 /***
85 * reset and clean up everything. shall be used is something went wrong (
86 * for example you received hibernate exception )
87 */
88 void reset();
89
90 /***
91 * Check if this instance is associated with this Session
92 *
93 * @param object
94 * an instance of a persistent class
95 * @return true if the given instance is associated with this Session
96 * @throws HibernateException
97 * @throws DAOException
98 */
99 boolean contains(Object object) throws HibernateException, DAOException;
100
101 /***
102 * Remove a persistent instance from the datastore.
103 *
104 * @param object
105 * @throws HibernateException
106 */
107 void delete(Object object) throws HibernateException, DAOException;
108
109 /***
110 * Remove a persistent instance from the datastore with lock mode.
111 *
112 * @param object
113 * @param lockMode
114 * @throws HibernateException
115 */
116 void delete(Object object, LockMode lockMode) throws HibernateException,
117 DAOException;
118
119 /***
120 * Delete all objects returned by the query. Return the number of objects
121 * deleted.
122 *
123 * @param query
124 * @return the number of instances deleted
125 * @throws HibernateException
126 * @throws DAOException
127 */
128 int delete(String query) throws HibernateException, DAOException;
129
130 /***
131 * Delete all objects returned by the query. Return the number of objects
132 * deleted.
133 *
134 * @param query
135 * @return the number of instances deleted
136 * @throws HibernateException
137 * @throws DAOException
138 */
139 int delete(String query, Object value, Type type)
140 throws HibernateException, DAOException;
141
142 /***
143 * Delete all objects returned by the query. Return the number of objects
144 * deleted.
145 *
146 * @param query
147 * @return the number of instances deleted
148 * @throws HibernateException
149 * @throws DAOException
150 */
151 int delete(String query, Object[] values, Type[] types)
152 throws HibernateException, DAOException;
153
154 /***
155 * Remove this instance from the session cache. Changes to the instance will
156 * not be synchronized with the database. This operation cascades to
157 * associated instances if the association is mapped with cascade="all" or
158 * cascade="all-delete-orphan".
159 *
160 * @param object
161 * object - a persistent instance
162 * @throws HibernateException
163 * @throws DAOException
164 */
165 void evict(Object object) throws HibernateException, DAOException;
166
167 /***
168 * Execute a query.
169 *
170 * @param query
171 * a query expressed in Hibernate's query language
172 * @return a distinct list of instances (or arrays of instances)
173 * @throws HibernateException
174 * @throws DAOException
175 */
176 List find(String query) throws HibernateException, DAOException;
177
178 /***
179 * Execute a query with bind parameters. Bind a value to a "?" parameter in
180 * the query string.
181 *
182 * @param query
183 * @param value
184 * @param type
185 * @return a distinct list of instances (or arrays of instances)
186 * @throws HibernateException
187 * @throws DAOException
188 */
189 List find(String query, Object value, Type type) throws HibernateException,
190 DAOException;
191
192 /***
193 * Execute a query with bind parameters. Binding an array of values to "?"
194 * parameters in the query string.
195 *
196 * @param query
197 * @param values
198 * @param types
199 * @return a distinct list of instances
200 * @throws HibernateException
201 * @throws DAOException
202 */
203 List find(String query, Object[] values, Type[] types)
204 throws HibernateException, DAOException;
205
206 /***
207 * Return the persistent instance of the given entity class with the given
208 * identifier, or null if there is no such persistent instance.
209 *
210 * @param clazz
211 * @param id
212 * @return a persistent instance or null
213 * @throws HibernateException
214 * @throws DAOException
215 */
216 Object get(Class clazz, final Serializable id) throws HibernateException,
217 DAOException;
218
219 /***
220 * Return the persistent instance of the given entity class with the given
221 * identifier, or null if there is no such persistent instance. Obtain the
222 * specified lock mode if the instance exists.
223 *
224 * @param clazz
225 * @param id
226 * @param lockMode
227 * @return a persistent instance or null
228 * @throws HibernateException
229 * @throws DAOException
230 */
231 Object get(Class clazz, final Serializable id, LockMode lockMode)
232 throws HibernateException, DAOException;
233
234 /***
235 * Execute a query and return the results in an iterator. If the query has
236 * multiple return values, values will be returned in an array of type
237 * Object[]. Entities returned as results are initialized on demand. The
238 * first SQL query returns identifiers only. So iterate() is usually a less
239 * efficient way to retrieve objects than find().
240 *
241 * @param query
242 * @return an iterator
243 * @throws HibernateException
244 * @throws DAOException
245 */
246 Iterator iterate(String query) throws HibernateException, DAOException;
247
248 /***
249 * Execute a query and return the results in an iterator. Write the given
250 * value to "?" in the query string. If the query has multiple return
251 * values, values will be returned in an array of type Object[]. Entities
252 * returned as results are initialized on demand. The first SQL query
253 * returns identifiers only. So iterate() is usually a less efficient way to
254 * retrieve objects than find().
255 *
256 * @param query -
257 * the query string
258 * @param value -
259 * a value to be witten to a "?" placeholder in the query string
260 * @param type -
261 * the hibernate type of value
262 * @return an iterator
263 * @throws HibernateException
264 * @throws DAOException
265 */
266 Iterator iterate(String query, Object value, Type type)
267 throws HibernateException, DAOException;
268
269 /***
270 * Execute a query and return the results in an iterator. Write the given
271 * values to "?" in the query string. If the query has multiple return
272 * values, values will be returned in an array of type Object[]. Entities
273 * returned as results are initialized on demand. The first SQL query
274 * returns identifiers only. So iterate() is usually a less efficient way to
275 * retrieve objects than find().
276 *
277 * @param query
278 * @param values
279 * @param types
280 * @return
281 * @throws HibernateException
282 * @throws DAOException
283 */
284 Iterator iterate(String query, Object[] values, Type[] types)
285 throws HibernateException, DAOException;
286
287 /***
288 * Return the persistent instance of the given entity class with the given
289 * identifier, assuming that the instance exists. You should not use this
290 * method to determine if an instance exists (use find() instead). Use this
291 * only to retrieve an instance that you assume exists, where non-existence
292 * would be an actual error.
293 *
294 * @param clazz
295 * @param id
296 * @return the persistent instance or proxy
297 * @throws HibernateException
298 * @throws DAOException
299 */
300 Object load(Class clazz, final Serializable id) throws HibernateException,
301 DAOException;
302
303 /***
304 * Return the persistent instance of the given entity class with the given
305 * identifier, obtaining the specified lock mode, assuming the instance
306 * exists.
307 *
308 * @param clazz
309 * @param id
310 * @param lockMode
311 * @return the persistent instance or proxy
312 * @throws HibernateException
313 * @throws DAOException
314 */
315 Object load(Class clazz, final Serializable id, LockMode lockMode)
316 throws HibernateException, DAOException;
317
318 /***
319 * Read the persistent state associated with the given identifier into the
320 * given transient instance.
321 *
322 * @param object
323 * @param id
324 * @throws HibernateException
325 * @throws DAOException
326 */
327 void load(Object object, final Serializable id) throws HibernateException,
328 DAOException;
329
330 /***
331 * Obtain the specified lock level upon the given object.
332 *
333 * @param object -
334 * a persistent or transient instance
335 * @param lockMode -
336 * the lock level
337 * @throws HibernateException
338 * @throws DAOException
339 */
340 void lock(Object object, LockMode lockMode) throws HibernateException,
341 DAOException;
342
343 /***
344 * Update the persistent instance with the identifier of the given transient
345 * instance. If there is a persistent instance with the same identifier, an
346 * exception is thrown. If the given transient instance has a null
347 * identifier, an exception will be thrown.
348 *
349 * @param object -
350 * a transient instance containing updated state
351 * @throws HibernateException
352 * @throws DAOException
353 */
354 void update(Object object) throws HibernateException, DAOException;
355
356 /***
357 * Update the persistent state associated with the given identifier. An
358 * exception is thrown if there is a persistent instance with the same
359 * identifier in the current session.
360 *
361 * @param object -
362 * a transient instance containing updated state
363 * @param id -
364 * identifier of persistent instance
365 * @throws HibernateException
366 * @throws DAOException
367 */
368 void update(Object object, final Serializable id)
369 throws HibernateException, DAOException;
370
371 /***
372 * Copy the state of the given object onto the persistent object with the
373 * same identifier. If there is no persistent instance currently associated
374 * with the session, it will be loaded. Return the persistent instance. If
375 * the given instance is unsaved or does not exist in the database, save it
376 * and return it as a newly persistent instance. Otherwise, the given
377 * instance does not become associated with the session.
378 *
379 * @param object
380 * @return an updated persistent instance
381 * @throws HibernateException
382 * @throws DAOException
383 */
384 Object saveOrUpdateCopy(Object object) throws HibernateException,
385 DAOException;
386
387 /***
388 * Copy the state of the given object onto the persistent object with the
389 * given identifier. If there is no persistent instance currently associated
390 * with the session, it will be loaded. Return the persistent instance. If
391 * there is no database row with the given identifier, save the given
392 * instance and return it as a newly persistent instance. Otherwise, the
393 * given instance does not become associated with the session.
394 *
395 * @param object -
396 * a persistent or transient instance with state to be copied
397 * @param id -
398 * the identifier of the instance to copy to
399 * @return an updated persistent instance
400 * @throws HibernateException
401 * @throws DAOException
402 */
403 Object saveOrUpdateCopy(Object object, final Serializable id)
404 throws HibernateException, DAOException;
405
406 /***
407 * Re-read the state of the given instance from the underlying database. It
408 * is inadvisable to use this to implement long-running sessions that span
409 * many business tasks. This method is, however, useful in certain special
410 * circumstances.
411 *
412 * @param object
413 * a persistent or transient instance
414 * @throws HibernateException
415 * @throws DAOException
416 */
417 void refresh(Object object) throws HibernateException, DAOException;
418
419 /***
420 * Re-read the state of the given instance from the underlying database,
421 * with the given LockMode. It is inadvisable to use this to implement
422 * long-running sessions that span many business tasks. This method is,
423 * however, useful in certain special circumstances.
424 *
425 * @param object
426 * a persistent or transient instance
427 * @param lockMode
428 * the lock mode to use
429 * @throws HibernateException
430 * @throws DAOException
431 */
432 void refresh(Object object, LockMode lockMode) throws HibernateException,
433 DAOException;
434
435 /***
436 * Persist the given transient instance, first assigning a generated
437 * identifier.
438 *
439 * @param object - -
440 * a transient instance of a persistent class
441 * @return the generated identifier
442 * @throws HibernateException
443 */
444 Serializable save(Object object) throws HibernateException, DAOException;
445
446 /***
447 * Persist the given transient instance, using the given identifier.
448 *
449 * @param object -
450 * a transient instance of a persistent class
451 * @param id -
452 * an unused valid identifier
453 * @throws HibernateException
454 * @throws DAOException
455 */
456 void save(Object object, final Serializable id) throws HibernateException,
457 DAOException;
458
459 /***
460 * Either save() or update() the given instance, depending upon the value of
461 * its identifier property. By default the instance is always saved. This
462 * behaviour may be adjusted by specifying an unsaved-value attribute of the
463 * identifier property mapping.
464 *
465 * @param object -
466 * a transient instance containing new or updated state
467 * @throws HibernateException
468 * @throws DAOException
469 */
470 void saveOrUpdate(Object object) throws HibernateException, DAOException;
471
472 }