Java > Open Source Codes > org > springframework > orm > hibernate3 > HibernateOperations


1 /*
2  * Copyright 2002-2006 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.springframework.orm.hibernate3;
18
19 import java.io.Serializable ;
20 import java.util.Collection ;
21 import java.util.Iterator ;
22 import java.util.List ;
23
24 import org.hibernate.Filter;
25 import org.hibernate.LockMode;
26 import org.hibernate.ReplicationMode;
27 import org.hibernate.criterion.DetachedCriteria;
28
29 import org.springframework.dao.DataAccessException;
30
31 /**
32  * Interface that specifies a basic set of Hibernate operations,
33  * implemented by {@link HibernateTemplate}. Not often used, but a useful
34  * option to enhance testability, as it can easily be mocked or stubbed.
35  *
36  * <p>Defines <code>HibernateTemplate</code>'s data access methods that
37  * mirror various {@link org.hibernate.Session} methods. Users are
38  * strongly encouraged to read the Hibernate <code>Session</code> javadocs
39  * for details on the semantics of those methods.
40  *
41  * <p>Note that operations that return an {@link java.util.Iterator} (i.e.
42  * <code>iterate(..)</code>) are supposed to be used within Spring-driven
43  * or JTA-driven transactions (with {@link HibernateTransactionManager},
44  * {@link org.springframework.transaction.jta.JtaTransactionManager},
45  * or EJB CMT). Else, the <code>Iterator</code> won't be able to read
46  * results from its {@link java.sql.ResultSet} anymore, as the underlying
47  * Hibernate <code>Session</code> will already have been closed.
48  *
49  * <p>Note that lazy loading will just work with an open Hibernate
50  * <code>Session</code>, either within a transaction or within
51  * {@link org.springframework.orm.hibernate.support.OpenSessionInViewFilter}/
52  * {@link org.springframework.orm.hibernate.support.OpenSessionInViewInterceptor}.
53  * Furthermore, some operations just make sense within transactions,
54  * for example: <code>contains</code>, <code>evict</code>, <code>lock</code>,
55  * <code>flush</code>, <code>clear</code>.
56  *
57  * @author Juergen Hoeller
58  * @since 1.2
59  * @see HibernateTemplate
60  * @see org.hibernate.Session
61  * @see HibernateTransactionManager
62  * @see org.springframework.transaction.jta.JtaTransactionManager
63  * @see org.springframework.orm.hibernate3.support.OpenSessionInViewFilter
64  * @see org.springframework.orm.hibernate3.support.OpenSessionInViewInterceptor
65  */
66 public interface HibernateOperations {
67
68     /**
69      * Execute the action specified by the given action object within a
70      * {@link org.hibernate.Session}.
71      * <p>Application exceptions thrown by the action object get propagated
72      * to the caller (can only be unchecked). Hibernate exceptions are
73      * transformed into appropriate DAO ones. Allows for returning a result
74      * object, that is a domain object or a collection of domain objects.
75      * <p>Note: Callback code is not supposed to handle transactions itself!
76      * Use an appropriate transaction manager like
77      * {@link HibernateTransactionManager}. Generally, callback code must not
78      * touch any <code>Session</code> lifecycle methods, like close,
79      * disconnect, or reconnect, to let the template do its work.
80      * @param action callback object that specifies the Hibernate action
81      * @return a result object returned by the action, or <code>null</code>
82      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
83      * @see HibernateTransactionManager
84      * @see org.springframework.dao
85      * @see org.springframework.transaction
86      * @see org.hibernate.Session
87      */
88     Object execute(HibernateCallback action) throws DataAccessException;
89
90     /**
91      * Execute the specified action assuming that the result object is a
92      * {@link List}.
93      * <p>This is a convenience method for executing Hibernate find calls or
94      * queries within an action.
95      * @param action calback object that specifies the Hibernate action
96      * @return a List result returned by the action, or <code>null</code>
97      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
98      */
99     List executeFind(HibernateCallback action) throws DataAccessException;
100
101
102     //-------------------------------------------------------------------------
103 // Convenience methods for loading individual objects
104 //-------------------------------------------------------------------------
105
106     /**
107      * Return the persistent instance of the given entity class
108      * with the given identifier, or <code>null</code> if not found.
109      * <p>This method is a thin wrapper around
110      * {@link org.hibernate.Session#get(Class, java.io.Serializable)} for convenience.
111      * For an explanation of the exact semantics of this method, please do refer to
112      * the Hibernate API documentation in the first instance.
113      * @param entityClass a persistent class
114      * @param id the identifier of the persistent instance
115      * @return the persistent instance, or <code>null</code> if not found
116      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
117      * @see org.hibernate.Session#get(Class, java.io.Serializable)
118      */
119     Object get(Class entityClass, Serializable id) throws DataAccessException;
120
121     /**
122      * Return the persistent instance of the given entity class
123      * with the given identifier, or <code>null</code> if not found.
124      * <p>Obtains the specified lock mode if the instance exists.
125      * <p>This method is a thin wrapper around
126      * {@link org.hibernate.Session#get(Class, java.io.Serializable, LockMode)} for convenience.
127      * For an explanation of the exact semantics of this method, please do refer to
128      * the Hibernate API documentation in the first instance.
129      * @param entityClass a persistent class
130      * @param id the identifier of the persistent instance
131      * @param lockMode the lock mode to obtain
132      * @return the persistent instance, or <code>null</code> if not found
133      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
134      * @see org.hibernate.Session#get(Class, java.io.Serializable, org.hibernate.LockMode)
135      */
136     Object get(Class entityClass, Serializable id, LockMode lockMode)
137             throws DataAccessException;
138
139     /**
140      * Return the persistent instance of the given entity class
141      * with the given identifier, or <code>null</code> if not found.
142      * <p>This method is a thin wrapper around
143      * {@link org.hibernate.Session#get(String, java.io.Serializable)} for convenience.
144      * For an explanation of the exact semantics of this method, please do refer to
145      * the Hibernate API documentation in the first instance.
146      * @param entityName the name of a persistent entity
147      * @param id the identifier of the persistent instance
148      * @return the persistent instance, or <code>null</code> if not found
149      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
150      * @see org.hibernate.Session#get(Class, java.io.Serializable)
151      */
152     Object get(String entityName, Serializable id) throws DataAccessException;
153
154     /**
155      * Return the persistent instance of the given entity class
156      * with the given identifier, or <code>null</code> if not found.
157      * Obtains the specified lock mode if the instance exists.
158      * <p>This method is a thin wrapper around
159      * {@link org.hibernate.Session#get(String, java.io.Serializable, LockMode)} for convenience.
160      * For an explanation of the exact semantics of this method, please do refer to
161      * the Hibernate API documentation in the first instance.
162      * @param entityName the name of a persistent entity
163      * @param id the identifier of the persistent instance
164      * @param lockMode the lock mode to obtain
165      * @return the persistent instance, or <code>null</code> if not found
166      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
167      * @see org.hibernate.Session#get(Class, java.io.Serializable, org.hibernate.LockMode)
168      */
169     Object get(String entityName, Serializable id, LockMode lockMode)
170             throws DataAccessException;
171
172     /**
173      * Return the persistent instance of the given entity class
174      * with the given identifier, throwing an exception if not found.
175      * <p>This method is a thin wrapper around
176      * {@link org.hibernate.Session#load(Class, java.io.Serializable)} for convenience.
177      * For an explanation of the exact semantics of this method, please do refer to
178      * the Hibernate API documentation in the first instance.
179      * @param entityClass a persistent class
180      * @param id the identifier of the persistent instance
181      * @return the persistent instance
182      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
183      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
184      * @see org.hibernate.Session#load(Class, java.io.Serializable)
185      */
186     Object load(Class entityClass, Serializable id) throws DataAccessException;
187
188     /**
189      * Return the persistent instance of the given entity class
190      * with the given identifier, throwing an exception if not found.
191      * Obtains the specified lock mode if the instance exists.
192      * <p>This method is a thin wrapper around
193      * {@link org.hibernate.Session#load(Class, java.io.Serializable, LockMode)} for convenience.
194      * For an explanation of the exact semantics of this method, please do refer to
195      * the Hibernate API documentation in the first instance.
196      * @param entityClass a persistent class
197      * @param id the identifier of the persistent instance
198      * @param lockMode the lock mode to obtain
199      * @return the persistent instance
200      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
201      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
202      * @see org.hibernate.Session#load(Class, java.io.Serializable)
203      */
204     Object load(Class entityClass, Serializable id, LockMode lockMode)
205             throws DataAccessException;
206
207     /**
208      * Return the persistent instance of the given entity class
209      * with the given identifier, throwing an exception if not found.
210      * <p>This method is a thin wrapper around
211      * {@link org.hibernate.Session#load(String, java.io.Serializable)} for convenience.
212      * For an explanation of the exact semantics of this method, please do refer to
213      * the Hibernate API documentation in the first instance.
214      * @param entityName the name of a persistent entity
215      * @param id the identifier of the persistent instance
216      * @return the persistent instance
217      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
218      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
219      * @see org.hibernate.Session#load(Class, java.io.Serializable)
220      */
221     Object load(String entityName, Serializable id) throws DataAccessException;
222
223     /**
224      * Return the persistent instance of the given entity class
225      * with the given identifier, throwing an exception if not found.
226      * <p>Obtains the specified lock mode if the instance exists.
227      * <p>This method is a thin wrapper around
228      * {@link org.hibernate.Session#load(String, java.io.Serializable, LockMode)} for convenience.
229      * For an explanation of the exact semantics of this method, please do refer to
230      * the Hibernate API documentation in the first instance.
231      * @param entityName the name of a persistent entity
232      * @param id the identifier of the persistent instance
233      * @param lockMode the lock mode to obtain
234      * @return the persistent instance
235      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
236      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
237      * @see org.hibernate.Session#load(Class, java.io.Serializable)
238      */
239     Object load(String entityName, Serializable id, LockMode lockMode)
240             throws DataAccessException;
241
242     /**
243      * Return all persistent instances of the given entity class.
244      * Note: Use queries or criteria for retrieving a specific subset.
245      * @param entityClass a persistent class
246      * @return a {@link List} containing 0 or more persistent instances
247      * @throws org.springframework.dao.DataAccessException if there is a Hibernate error
248      * @see org.hibernate.Session#createCriteria
249      */
250     List loadAll(Class entityClass) throws DataAccessException;
251
252     /**
253      * Load the persistent instance with the given identifier
254      * into the given object, throwing an exception if not found.
255      * <p>This method is a thin wrapper around
256      * {@link org.hibernate.Session#load(Object, java.io.Serializable)} for convenience.
257      * For an explanation of the exact semantics of this method, please do refer to
258      * the Hibernate API documentation in the first instance.
259      * @param entity the object (of the target class) to load into
260      * @param id the identifier of the persistent instance
261      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
262      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
263      * @see org.hibernate.Session#load(Object, java.io.Serializable)
264      */
265     void load(Object entity, Serializable id) throws DataAccessException;
266
267     /**
268      * Re-read the state of the given persistent instance.
269      * @param entity the persistent instance to re-read
270      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
271      * @see org.hibernate.Session#refresh(Object)
272      */
273     void refresh(Object entity) throws DataAccessException;
274
275     /**
276      * Re-read the state of the given persistent instance.
277      * Obtains the specified lock mode for the instance.
278      * @param entity the persistent instance to re-read
279      * @param lockMode the lock mode to obtain
280      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
281      * @see org.hibernate.Session#refresh(Object, org.hibernate.LockMode)
282      */
283     void refresh(Object entity, LockMode lockMode) throws DataAccessException;
284
285     /**
286      * Check whether the given object is in the Session cache.
287      * @param entity the persistence instance to check
288      * @return whether the given object is in the Session cache
289      * @throws org.springframework.dao.DataAccessException if there is a Hibernate error
290      * @see org.hibernate.Session#contains
291      */
292     boolean contains(Object entity) throws DataAccessException;
293
294     /**
295      * Remove the given object from the {@link org.hibernate.Session} cache.
296      * @param entity the persistent instance to evict
297      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
298      * @see org.hibernate.Session#evict
299      */
300     void evict(Object entity) throws DataAccessException;
301
302     /**
303      * Force initialization of a Hibernate proxy or persistent collection.
304      * @param proxy a proxy for a persistent object or a persistent collection
305      * @throws DataAccessException if we can't initialize the proxy, for example
306      * because it is not associated with an active Session
307      * @see org.hibernate.Hibernate#initialize
308      */
309     void initialize(Object proxy) throws DataAccessException;
310
311     /**
312      * Return an enabled Hibernate {@link Filter} for the given filter name.
313      * The returned <code>Filter</code> instance can be used to set filter parameters.
314      * @param filterName the name of the filter
315      * @return the enabled Hibernate <code>Filter</code> (either already
316      * enabled or enabled on the fly by this operation)
317      * @throws IllegalStateException if we are not running within a
318      * transactional Session (in which case this operation does not make sense)
319      */
320     Filter enableFilter(String filterName) throws IllegalStateException ;
321
322
323     //-------------------------------------------------------------------------
324 // Convenience methods for storing individual objects
325 //-------------------------------------------------------------------------
326
327     /**
328      * Obtain the specified lock level upon the given object, implicitly
329      * checking whether the corresponding database entry still exists.
330      * @param entity the persistent instance to lock
331      * @param lockMode the lock mode to obtain
332      * @throws org.springframework.orm.ObjectOptimisticLockingFailureException if not found
333      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
334      * @see org.hibernate.Session#lock(Object, org.hibernate.LockMode)
335      */
336     void lock(Object entity, LockMode lockMode) throws DataAccessException;
337
338     /**
339      * Obtain the specified lock level upon the given object, implicitly
340      * checking whether the corresponding database entry still exists.
341      * @param entityName the name of a persistent entity
342      * @param entity the persistent instance to lock
343      * @param lockMode the lock mode to obtain
344      * @throws org.springframework.orm.ObjectOptimisticLockingFailureException if not found
345      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
346      * @see org.hibernate.Session#lock(String, Object, org.hibernate.LockMode)
347      */
348     void lock(String entityName, Object entity, LockMode lockMode) throws DataAccessException;
349
350     /**
351      * Persist the given transient instance.
352      * @param entity the transient instance to persist
353      * @return the generated identifier
354      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
355      * @see org.hibernate.Session#save(Object)
356      */
357     Serializable save(Object entity) throws DataAccessException;
358
359     /**
360      * Persist the given transient instance.
361      * @param entityName the name of a persistent entity
362      * @param entity the transient instance to persist
363      * @return the generated identifier
364      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
365      * @see org.hibernate.Session#save(String, Object)
366      */
367     Serializable save(String entityName, Object entity) throws DataAccessException;
368
369     /**
370      * Update the given persistent instance,
371      * associating it with the current Hibernate {@link org.hibernate.Session}.
372      * @param entity the persistent instance to update
373      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
374      * @see org.hibernate.Session#update(Object)
375      */
376     void update(Object entity) throws DataAccessException;
377
378     /**
379      * Update the given persistent instance,
380      * associating it with the current Hibernate {@link org.hibernate.Session}.
381      * <p>Obtains the specified lock mode if the instance exists, implicitly
382      * checking whether the corresponding database entry still exists.
383      * @param entity the persistent instance to update
384      * @param lockMode the lock mode to obtain
385      * @throws org.springframework.orm.ObjectOptimisticLockingFailureException if not found
386      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
387      * @see org.hibernate.Session#update(Object)
388      */
389     void update(Object entity, LockMode lockMode) throws DataAccessException;
390
391     /**
392      * Update the given persistent instance,
393      * associating it with the current Hibernate {@link org.hibernate.Session}.
394      * @param entityName the name of a persistent entity
395      * @param entity the persistent instance to update
396      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
397      * @see org.hibernate.Session#update(String, Object)
398      */
399     void update(String entityName, Object entity) throws DataAccessException;
400
401     /**
402      * Update the given persistent instance,
403      * associating it with the current Hibernate {@link org.hibernate.Session}.
404      * <p>Obtains the specified lock mode if the instance exists, implicitly
405      * checking whether the corresponding database entry still exists.
406      * @param entityName the name of a persistent entity
407      * @param entity the persistent instance to update
408      * @param lockMode the lock mode to obtain
409      * @throws org.springframework.orm.ObjectOptimisticLockingFailureException if not found
410      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
411      * @see org.hibernate.Session#update(String, Object)
412      */
413     void update(String entityName, Object entity, LockMode lockMode) throws DataAccessException;
414
415     /**
416      * Save or update the given persistent instance,
417      * according to its id (matching the configured "unsaved-value"?).
418      * Associates the instance with the current Hibernate {@link org.hibernate.Session}.
419      * @param entity the persistent instance to save or update
420      * (to be associated with the Hibernate <code>Session</code>)
421      * @throws DataAccessException in case of Hibernate errors
422      * @see org.hibernate.Session#saveOrUpdate(Object)
423      */
424     void saveOrUpdate(Object entity) throws DataAccessException;
425
426     /**
427      * Save or update the given persistent instance,
428      * according to its id (matching the configured "unsaved-value"?).
429      * Associates the instance with the current Hibernate <code>Session</code>.
430      * @param entityName the name of a persistent entity
431      * @param entity the persistent instance to save or update
432      * (to be associated with the Hibernate <code>Session</code>)
433      * @throws DataAccessException in case of Hibernate errors
434      * @see org.hibernate.Session#saveOrUpdate(String, Object)
435      */
436     void saveOrUpdate(String entityName, Object entity) throws DataAccessException;
437
438     /**
439      * Save or update all given persistent instances,
440      * according to its id (matching the configured "unsaved-value"?).
441      * Associates the instances with the current Hibernate <code>Session</code>.
442      * @param entities the persistent instances to save or update
443      * (to be associated with the Hibernate <code>Session</code>)
444      * @throws DataAccessException in case of Hibernate errors
445      * @see org.hibernate.Session#saveOrUpdate(Object)
446      */
447     void saveOrUpdateAll(Collection entities) throws DataAccessException;
448
449     /**
450      * Persist the state of the given detached instance according to the
451      * given replication mode, reusing the current identifier value.
452      * @param entity the persistent object to replicate
453      * @throws DataAccessException in case of Hibernate errors
454      * @see org.hibernate.Session#replicate(Object, org.hibernate.ReplicationMode)
455      */
456     void replicate(Object entity, ReplicationMode replicationMode) throws DataAccessException;
457
458     /**
459      * Persist the state of the given detached instance according to the
460      * given replication mode, reusing the current identifier value.
461      * @param entityName the name of a persistent entity
462      * @param entity the persistent object to replicate
463      * @throws DataAccessException in case of Hibernate errors
464      * @see org.hibernate.Session#replicate(String, Object, org.hibernate.ReplicationMode)
465      */
466     void replicate(String entityName, Object entity, ReplicationMode replicationMode) throws DataAccessException;
467
468     /**
469      * Persist the given transient instance. Follows JSR-220 semantics.
470      * <p>Similar to <code>save</code>, associating the given object
471      * with the current Hibernate {@link org.hibernate.Session}.
472      * @param entity the persistent instance to persist
473      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
474      * @see org.hibernate.Session#persist(Object)
475      * @see #save
476      */
477     void persist(Object entity) throws DataAccessException;
478
479     /**
480      * Persist the given transient instance. Follows JSR-220 semantics.
481      * <p>Similar to <code>save</code>, associating the given object
482      * with the current Hibernate {@link org.hibernate.Session}.
483      * @param entityName the name of a persistent entity
484      * @param entity the persistent instance to persist
485      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
486      * @see org.hibernate.Session#persist(String, Object)
487      * @see #save
488      */
489     void persist(String entityName, Object entity) throws DataAccessException;
490
491     /**
492      * Copy the state of the given object onto the persistent object
493      * with the same identifier. Follows JSR-220 semantics.
494      * <p>Similar to <code>saveOrUpdate</code>, but never associates the given
495      * object with the current Hibernate Session. In case of a new entity,
496      * the state will be copied over as well.
497      * <p>Note that <code>merge</code> will <i>not</i> update the identifiers
498      * in the passed-in object graph (in contrast to TopLink)! Consider
499      * registering Spring's <code>IdTransferringMergeEventListener</code> if
500      * you would like to have newly assigned ids transferred to the original
501      * object graph too.
502      * @param entity the object to merge with the corresponding persistence instance
503      * @return the updated, registered persistent instance
504      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
505      * @see org.hibernate.Session#merge(Object)
506      * @see #saveOrUpdate
507      * @see org.springframework.orm.hibernate3.support.IdTransferringMergeEventListener
508      */
509     Object merge(Object entity) throws DataAccessException;
510
511     /**
512      * Copy the state of the given object onto the persistent object
513      * with the same identifier. Follows JSR-220 semantics.
514      * <p>Similar to <code>saveOrUpdate</code>, but never associates the given
515      * object with the current Hibernate {@link org.hibernate.Session}. In
516      * the case of a new entity, the state will be copied over as well.
517      * <p>Note that <code>merge</code> will <i>not</i> update the identifiers
518      * in the passed-in object graph (in contrast to TopLink)! Consider
519      * registering Spring's <code>IdTransferringMergeEventListener</code>
520      * if you would like to have newly assigned ids transferred to the
521      * original object graph too.
522      * @param entityName the name of a persistent entity
523      * @param entity the object to merge with the corresponding persistence instance
524      * @return the updated, registered persistent instance
525      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
526      * @see org.hibernate.Session#merge(String, Object)
527      * @see #saveOrUpdate
528      */
529     Object merge(String entityName, Object entity) throws DataAccessException;
530
531     /**
532      * Delete the given persistent instance.
533      * @param entity the persistent instance to delete
534      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
535      * @see org.hibernate.Session#delete(Object)
536      */
537     void delete(Object entity) throws DataAccessException;
538
539     /**
540      * Delete the given persistent instance.
541      * <p>Obtains the specified lock mode if the instance exists, implicitly
542      * checking whether the corresponding database entry still exists.
543      * @param entity the persistent instance to delete
544      * @param lockMode the lock mode to obtain
545      * @throws org.springframework.orm.ObjectOptimisticLockingFailureException if not found
546      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
547      * @see org.hibernate.Session#delete(Object)
548      */
549     void delete(Object entity, LockMode lockMode) throws DataAccessException;
550
551     /**
552      * Delete all given persistent instances.
553      * <p>This can be combined with any of the find methods to delete by query
554      * in two lines of code.
555      * @param entities the persistent instances to delete
556      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
557      * @see org.hibernate.Session#delete(Object)
558      */
559     void deleteAll(Collection entities) throws DataAccessException;
560
561     /**
562      * Flush all pending saves, updates and deletes to the database.
563      * <p>Only invoke this for selective eager flushing, for example when
564      * JDBC code needs to see certain changes within the same transaction.
565      * Else, it is preferable to rely on auto-flushing at transaction
566      * completion.
567      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
568      * @see org.hibernate.Session#flush
569      */
570     void flush() throws DataAccessException;
571
572     /**
573      * Remove all objects from the {@link org.hibernate.Session} cache, and
574      * cancel all pending saves, updates and deletes.
575      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
576      * @see org.hibernate.Session#clear
577      */
578     void clear() throws DataAccessException;
579
580
581     //-------------------------------------------------------------------------
582 // Convenience finder methods for HQL strings
583 //-------------------------------------------------------------------------
584
585     /**
586      * Execute an HQL query.
587      * @param queryString a query expressed in Hibernate's query language
588      * @return a {@link List} containing the results of the query execution
589      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
590      * @see org.hibernate.Session#createQuery
591      */
592     List find(String queryString) throws DataAccessException;
593
594     /**
595      * Execute an HQL query, binding one value to a "?" parameter in the
596      * query string.
597      * @param queryString a query expressed in Hibernate's query language
598      * @param value the value of the parameter
599      * @return a {@link List} containing the results of the query execution
600      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
601      * @see org.hibernate.Session#createQuery
602      */
603     List find(String queryString, Object value) throws DataAccessException;
604
605     /**
606      * Execute an HQL query, binding a number of values to "?" parameters
607      * in the query string.
608      * @param queryString a query expressed in Hibernate's query language
609      * @param values the values of the parameters
610      * @return a {@link List} containing the results of the query execution
611      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
612      * @see org.hibernate.Session#createQuery
613      */
614     List find(String queryString, Object [] values) throws DataAccessException;
615
616     /**
617      * Execute an HQL query, binding one value to a ":" named parameter
618      * in the query string.
619      * @param queryName the name of a Hibernate query in a mapping file
620      * @param paramName the name of the parameter
621      * @param value the value of the parameter
622      * @return a {@link List} containing the results of the query execution
623      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
624      * @see org.hibernate.Session#getNamedQuery(String)
625      */
626     List findByNamedParam(String queryName, String paramName, Object value)
627             throws DataAccessException;
628
629     /**
630      * Execute an HQL query, binding a number of values to ":" named
631      * parameters in the query string.
632      * @param queryString a query expressed in Hibernate's query language
633      * @param paramNames the names of the parameters
634      * @param values the values of the parameters
635      * @return a {@link List} containing the results of the query execution
636      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
637      * @see org.hibernate.Session#getNamedQuery(String)
638      */
639     List findByNamedParam(String queryString, String [] paramNames, Object [] values)
640             throws DataAccessException;
641
642     /**
643      * Execute an HQL query, binding the properties of the given bean to
644      * <i>named</i> parameters in the query string.
645      * @param queryString a query expressed in Hibernate's query language
646      * @param valueBean the values of the parameters
647      * @return a {@link List} containing the results of the query execution
648      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
649      * @see org.hibernate.Query#setProperties
650      * @see org.hibernate.Session#createQuery
651      */
652     List findByValueBean(String queryString, Object valueBean) throws DataAccessException;
653
654
655     //-------------------------------------------------------------------------
656 // Convenience finder methods for named queries
657 //-------------------------------------------------------------------------
658
659     /**
660      * Execute a named query.
661      * <p>A named query is defined in a Hibernate mapping file.
662      * @param queryName the name of a Hibernate query in a mapping file
663      * @return a {@link List} containing the results of the query execution
664      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
665      * @see org.hibernate.Session#getNamedQuery(String)
666      */
667     List findByNamedQuery(String queryName) throws DataAccessException;
668
669     /**
670      * Execute a named query, binding one value to a "?" parameter in
671      * the query string.
672      * <p>A named query is defined in a Hibernate mapping file.
673      * @param queryName the name of a Hibernate query in a mapping file
674      * @param value the value of the parameter
675      * @return a {@link List} containing the results of the query execution
676      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
677      * @see org.hibernate.Session#getNamedQuery(String)
678      */
679     List findByNamedQuery(String queryName, Object value) throws DataAccessException;
680
681     /**
682      * Execute a named query binding a number of values to "?" parameters
683      * in the query string.
684      * <p>A named query is defined in a Hibernate mapping file.
685      * @param queryName the name of a Hibernate query in a mapping file
686      * @param values the values of the parameters
687      * @return a {@link List} containing the results of the query execution
688      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
689      * @see org.hibernate.Session#getNamedQuery(String)
690      */
691     List findByNamedQuery(String queryName, Object [] values) throws DataAccessException;
692
693     /**
694      * Execute a named query, binding one value to a ":" named parameter
695      * in the query string.
696      * <p>A named query is defined in a Hibernate mapping file.
697      * @param queryName the name of a Hibernate query in a mapping file
698      * @param paramName the name of parameter
699      * @param value the value of the parameter
700      * @return a {@link List} containing the results of the query execution
701      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
702      * @see org.hibernate.Session#getNamedQuery(String)
703      */
704     List findByNamedQueryAndNamedParam(String queryName, String paramName, Object value)
705             throws DataAccessException;
706
707     /**
708      * Execute a named query, binding a number of values to ":" named
709      * parameters in the query string.
710      * <p>A named query is defined in a Hibernate mapping file.
711      * @param queryName the name of a Hibernate query in a mapping file
712      * @param paramNames the names of the parameters
713      * @param values the values of the parameters
714      * @return a {@link List} containing the results of the query execution
715      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
716      * @see org.hibernate.Session#getNamedQuery(String)
717      */
718     List findByNamedQueryAndNamedParam(String queryName, String [] paramNames, Object [] values)
719             throws DataAccessException;
720
721     /**
722      * Execute a named query, binding the properties of the given bean to
723      * ":" named parameters in the query string.
724      * <p>A named query is defined in a Hibernate mapping file.
725      * @param queryName the name of a Hibernate query in a mapping file
726      * @param valueBean the values of the parameters
727      * @return a {@link List} containing the results of the query execution
728      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
729      * @see org.hibernate.Query#setProperties
730      * @see org.hibernate.Session#getNamedQuery(String)
731      */
732     List findByNamedQueryAndValueBean(String queryName, Object valueBean)
733             throws DataAccessException;
734
735
736     //-------------------------------------------------------------------------
737 // Convenience finder methods for detached criteria
738 //-------------------------------------------------------------------------
739
740     /**
741      * Execute a query based on a given Hibernate criteria object.
742      * @param criteria the detached Hibernate criteria object,
743      * which can for example be held in an instance variable of a DAO
744      * @return a {@link List} containing 0 or more persistent instances
745      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
746      * @see org.hibernate.criterion.DetachedCriteria#getExecutableCriteria(org.hibernate.Session)
747      */
748     List findByCriteria(DetachedCriteria criteria) throws DataAccessException;
749
750     /**
751      * Execute a query based on the given Hibernate criteria object.
752      * @param criteria the detached Hibernate criteria object,
753      * which can for example be held in an instance variable of a DAO
754      * @param firstResult the index of the first result object to be retrieved
755      * (numbered from 0)
756      * @param maxResults the maximum number of result objects to retrieve
757      * (or <=0 for no limit)
758      * @return a {@link List} containing 0 or more persistent instances
759      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
760      * @see org.hibernate.criterion.DetachedCriteria#getExecutableCriteria(org.hibernate.Session)
761      * @see org.hibernate.Criteria#setFirstResult(int)
762      * @see org.hibernate.Criteria#setMaxResults(int)
763      */
764     List findByCriteria(DetachedCriteria criteria, int firstResult, int maxResults) throws DataAccessException;
765
766     /**
767      * Execute a query based on the given example entity object.
768      * @param exampleEntity an instance of the desired entity,
769      * serving as example for "query-by-example"
770      * @return a {@link List} containing 0 or more persistent instances
771      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
772      * @see org.hibernate.criterion.Example#create(Object)
773      */
774     List findByExample(Object exampleEntity) throws DataAccessException;
775
776     /**
777      * Execute a query based on a given example entity object.
778      * @param exampleEntity an instance of the desired entity,
779      * serving as example for "query-by-example"
780      * @param firstResult the index of the first result object to be retrieved
781      * (numbered from 0)
782      * @param maxResults the maximum number of result objects to retrieve
783      * (or <=0 for no limit)
784      * @return a {@link List} containing 0 or more persistent instances
785      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
786      * @see org.hibernate.criterion.Example#create(Object)
787      * @see org.hibernate.Criteria#setFirstResult(int)
788      * @see org.hibernate.Criteria#setMaxResults(int)
789      */
790     List findByExample(Object exampleEntity, int firstResult, int maxResults) throws DataAccessException;
791
792
793     //-------------------------------------------------------------------------
794 // Convenience query methods for iteration and bulk updates/deletes
795 //-------------------------------------------------------------------------
796
797     /**
798      * Execute a query for persistent instances.
799      * <p>Returns the results as an {@link Iterator}. Entities returned are
800      * initialized on demand. See the Hibernate API documentation for details.
801      * @param queryString a query expressed in Hibernate's query language
802      * @return an {@link Iterator} containing 0 or more persistent instances
803      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
804      * @see org.hibernate.Session#createQuery
805      * @see org.hibernate.Query#iterate
806      */
807     Iterator iterate(String queryString) throws DataAccessException;
808
809     /**
810      * Execute a query for persistent instances, binding one value
811      * to a "?" parameter in the query string.
812      * <p>Returns the results as an {@link Iterator}. Entities returned are
813      * initialized on demand. See the Hibernate API documentation for details.
814      * @param queryString a query expressed in Hibernate's query language
815      * @param value the value of the parameter
816      * @return an {@link Iterator} containing 0 or more persistent instances
817      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
818      * @see org.hibernate.Session#createQuery
819      * @see org.hibernate.Query#iterate
820      */
821     Iterator iterate(String queryString, Object value) throws DataAccessException;
822
823     /**
824      * Execute a query for persistent instances, binding a number of
825      * values to "?" parameters in the query string.
826      * <p>Returns the results as an {@link Iterator}. Entities returned are
827      * initialized on demand. See the Hibernate API documentation for details.
828      * @param queryString a query expressed in Hibernate's query language
829      * @param values the values of the parameters
830      * @return an {@link Iterator} containing 0 or more persistent instances
831      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
832      * @see org.hibernate.Session#createQuery
833      * @see org.hibernate.Query#iterate
834      */
835     Iterator iterate(String queryString, Object [] values) throws DataAccessException;
836
837     /**
838      * Immediately close an {@link Iterator} created by any of the various
839      * <code>iterate(..)</code> operations, instead of waiting until the
840      * session is closed or disconnected.
841      * @param it the <code>Iterator</code> to close
842      * @throws DataAccessException if the <code>Iterator</code> could not be closed
843      * @see org.hibernate.Hibernate#close
844      */
845     void closeIterator(Iterator it) throws DataAccessException;
846
847     /**
848      * Update/delete all objects according to the given query.
849      * @param queryString an update/delete query expressed in Hibernate's query language
850      * @return the number of instances updated/deleted
851      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
852      * @see org.hibernate.Session#createQuery
853      * @see org.hibernate.Query#executeUpdate
854      */
855     int bulkUpdate(String queryString) throws DataAccessException;
856
857     /**
858      * Update/delete all objects according to the given query, binding one value
859      * to a "?" parameter in the query string.
860      * @param queryString an update/delete query expressed in Hibernate's query language
861      * @param value the value of the parameter
862      * @return the number of instances updated/deleted
863      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
864      * @see org.hibernate.Session#createQuery
865      * @see org.hibernate.Query#executeUpdate
866      */
867     int bulkUpdate(String queryString, Object value) throws DataAccessException;
868
869     /**
870      * Update/delete all objects according to the given query, binding a number of
871      * values to "?" parameters in the query string.
872      * @param queryString an update/delete query expressed in Hibernate's query language
873      * @param values the values of the parameters
874      * @return the number of instances updated/deleted
875      * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
876      * @see org.hibernate.Session#createQuery
877      * @see org.hibernate.Query#executeUpdate
878      */
879     int bulkUpdate(String queryString, Object [] values) throws DataAccessException;
880
881 }
882

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags