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