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