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