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.hibernate3.support.OpenSessionInViewFilter}/
052: * {@link org.springframework.orm.hibernate3.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 the 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 the 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 the 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 the 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 the 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 the 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 the 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 the 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 the 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: * @deprecated as of Spring 2.5, in favor of individual
458: * <code>saveOrUpdate</code> or <code>merge</code> usage
459: */
460: void saveOrUpdateAll(Collection entities)
461: throws DataAccessException;
462:
463: /**
464: * Persist the state of the given detached instance according to the
465: * given replication mode, reusing the current identifier value.
466: * @param entity the persistent object to replicate
467: * @param replicationMode the Hibernate ReplicationMode
468: * @throws DataAccessException in case of Hibernate errors
469: * @see org.hibernate.Session#replicate(Object, org.hibernate.ReplicationMode)
470: */
471: void replicate(Object entity, ReplicationMode replicationMode)
472: throws DataAccessException;
473:
474: /**
475: * Persist the state of the given detached instance according to the
476: * given replication mode, reusing the current identifier value.
477: * @param entityName the name of the persistent entity
478: * @param entity the persistent object to replicate
479: * @param replicationMode the Hibernate ReplicationMode
480: * @throws DataAccessException in case of Hibernate errors
481: * @see org.hibernate.Session#replicate(String, Object, org.hibernate.ReplicationMode)
482: */
483: void replicate(String entityName, Object entity,
484: ReplicationMode replicationMode) throws DataAccessException;
485:
486: /**
487: * Persist the given transient instance. Follows JSR-220 semantics.
488: * <p>Similar to <code>save</code>, associating the given object
489: * with the current Hibernate {@link org.hibernate.Session}.
490: * @param entity the persistent instance to persist
491: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
492: * @see org.hibernate.Session#persist(Object)
493: * @see #save
494: */
495: void persist(Object entity) throws DataAccessException;
496:
497: /**
498: * Persist the given transient instance. Follows JSR-220 semantics.
499: * <p>Similar to <code>save</code>, associating the given object
500: * with the current Hibernate {@link org.hibernate.Session}.
501: * @param entityName the name of the persistent entity
502: * @param entity the persistent instance to persist
503: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
504: * @see org.hibernate.Session#persist(String, Object)
505: * @see #save
506: */
507: void persist(String entityName, Object entity)
508: throws DataAccessException;
509:
510: /**
511: * Copy the state of the given object onto the persistent object
512: * with the same identifier. Follows JSR-220 semantics.
513: * <p>Similar to <code>saveOrUpdate</code>, but never associates the given
514: * object with the current Hibernate Session. In case of a new entity,
515: * the state will be copied over as well.
516: * <p>Note that <code>merge</code> will <i>not</i> update the identifiers
517: * in the passed-in object graph (in contrast to TopLink)! Consider
518: * registering Spring's <code>IdTransferringMergeEventListener</code> if
519: * you would like to have newly assigned ids transferred to the original
520: * object graph too.
521: * @param entity the object to merge with the corresponding persistence instance
522: * @return the updated, registered persistent instance
523: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
524: * @see org.hibernate.Session#merge(Object)
525: * @see #saveOrUpdate
526: * @see org.springframework.orm.hibernate3.support.IdTransferringMergeEventListener
527: */
528: Object merge(Object entity) throws DataAccessException;
529:
530: /**
531: * Copy the state of the given object onto the persistent object
532: * with the same identifier. Follows JSR-220 semantics.
533: * <p>Similar to <code>saveOrUpdate</code>, but never associates the given
534: * object with the current Hibernate {@link org.hibernate.Session}. In
535: * the case of a new entity, the state will be copied over as well.
536: * <p>Note that <code>merge</code> will <i>not</i> update the identifiers
537: * in the passed-in object graph (in contrast to TopLink)! Consider
538: * registering Spring's <code>IdTransferringMergeEventListener</code>
539: * if you would like to have newly assigned ids transferred to the
540: * original object graph too.
541: * @param entityName the name of the persistent entity
542: * @param entity the object to merge with the corresponding persistence instance
543: * @return the updated, registered persistent instance
544: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
545: * @see org.hibernate.Session#merge(String, Object)
546: * @see #saveOrUpdate
547: */
548: Object merge(String entityName, Object entity)
549: throws DataAccessException;
550:
551: /**
552: * Delete the given persistent instance.
553: * @param entity the persistent instance to delete
554: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
555: * @see org.hibernate.Session#delete(Object)
556: */
557: void delete(Object entity) throws DataAccessException;
558:
559: /**
560: * Delete the given persistent instance.
561: * <p>Obtains the specified lock mode if the instance exists, implicitly
562: * checking whether the corresponding database entry still exists.
563: * @param entity the persistent instance to delete
564: * @param lockMode the lock mode to obtain
565: * @throws org.springframework.orm.ObjectOptimisticLockingFailureException if not found
566: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
567: * @see org.hibernate.Session#delete(Object)
568: */
569: void delete(Object entity, LockMode lockMode)
570: throws DataAccessException;
571:
572: /**
573: * Delete all given persistent instances.
574: * <p>This can be combined with any of the find methods to delete by query
575: * in two lines of code.
576: * @param entities the persistent instances to delete
577: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
578: * @see org.hibernate.Session#delete(Object)
579: */
580: void deleteAll(Collection entities) throws DataAccessException;
581:
582: /**
583: * Flush all pending saves, updates and deletes to the database.
584: * <p>Only invoke this for selective eager flushing, for example when
585: * JDBC code needs to see certain changes within the same transaction.
586: * Else, it is preferable to rely on auto-flushing at transaction
587: * completion.
588: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
589: * @see org.hibernate.Session#flush
590: */
591: void flush() throws DataAccessException;
592:
593: /**
594: * Remove all objects from the {@link org.hibernate.Session} cache, and
595: * cancel all pending saves, updates and deletes.
596: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
597: * @see org.hibernate.Session#clear
598: */
599: void clear() throws DataAccessException;
600:
601: //-------------------------------------------------------------------------
602: // Convenience finder methods for HQL strings
603: //-------------------------------------------------------------------------
604:
605: /**
606: * Execute an HQL query.
607: * @param queryString a query expressed in Hibernate's query language
608: * @return a {@link List} containing the results of the query execution
609: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
610: * @see org.hibernate.Session#createQuery
611: */
612: List find(String queryString) throws DataAccessException;
613:
614: /**
615: * Execute an HQL query, binding one value to a "?" parameter in the
616: * query string.
617: * @param queryString a query expressed in Hibernate's query language
618: * @param value the value of the parameter
619: * @return a {@link List} containing the results of the query execution
620: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
621: * @see org.hibernate.Session#createQuery
622: */
623: List find(String queryString, Object value)
624: throws DataAccessException;
625:
626: /**
627: * Execute an HQL query, binding a number of values to "?" parameters
628: * in the query string.
629: * @param queryString a query expressed in Hibernate's query language
630: * @param values the values of the parameters
631: * @return a {@link List} containing the results of the query execution
632: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
633: * @see org.hibernate.Session#createQuery
634: */
635: List find(String queryString, Object[] values)
636: throws DataAccessException;
637:
638: /**
639: * Execute an HQL query, binding one value to a ":" named parameter
640: * in the query string.
641: * @param queryString a query expressed in Hibernate's query language
642: * @param paramName the name of the parameter
643: * @param value the value of the parameter
644: * @return a {@link List} containing the results of the query execution
645: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
646: * @see org.hibernate.Session#getNamedQuery(String)
647: */
648: List findByNamedParam(String queryString, String paramName,
649: Object value) throws DataAccessException;
650:
651: /**
652: * Execute an HQL query, binding a number of values to ":" named
653: * parameters in the query string.
654: * @param queryString a query expressed in Hibernate's query language
655: * @param paramNames the names of the parameters
656: * @param values the values of the parameters
657: * @return a {@link List} containing the results of the query execution
658: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
659: * @see org.hibernate.Session#getNamedQuery(String)
660: */
661: List findByNamedParam(String queryString, String[] paramNames,
662: Object[] values) throws DataAccessException;
663:
664: /**
665: * Execute an HQL query, binding the properties of the given bean to
666: * <i>named</i> parameters in the query string.
667: * @param queryString a query expressed in Hibernate's query language
668: * @param valueBean the values of the parameters
669: * @return a {@link List} containing the results of the query execution
670: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
671: * @see org.hibernate.Query#setProperties
672: * @see org.hibernate.Session#createQuery
673: */
674: List findByValueBean(String queryString, Object valueBean)
675: throws DataAccessException;
676:
677: //-------------------------------------------------------------------------
678: // Convenience finder methods for named queries
679: //-------------------------------------------------------------------------
680:
681: /**
682: * Execute a named query.
683: * <p>A named query is defined in a Hibernate mapping file.
684: * @param queryName the name of a Hibernate query in a mapping file
685: * @return a {@link List} containing the results of the query execution
686: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
687: * @see org.hibernate.Session#getNamedQuery(String)
688: */
689: List findByNamedQuery(String queryName) throws DataAccessException;
690:
691: /**
692: * Execute a named query, binding one value to a "?" parameter in
693: * the query string.
694: * <p>A named query is defined in a Hibernate mapping file.
695: * @param queryName the name of a Hibernate query in a mapping file
696: * @param value the value of the parameter
697: * @return a {@link List} containing the results of the query execution
698: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
699: * @see org.hibernate.Session#getNamedQuery(String)
700: */
701: List findByNamedQuery(String queryName, Object value)
702: throws DataAccessException;
703:
704: /**
705: * Execute a named query binding a number of values to "?" parameters
706: * in the query string.
707: * <p>A named query is defined in a Hibernate mapping file.
708: * @param queryName the name of a Hibernate query in a mapping file
709: * @param values the values of the parameters
710: * @return a {@link List} containing the results of the query execution
711: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
712: * @see org.hibernate.Session#getNamedQuery(String)
713: */
714: List findByNamedQuery(String queryName, Object[] values)
715: throws DataAccessException;
716:
717: /**
718: * Execute a named query, binding one value to a ":" named parameter
719: * in the query string.
720: * <p>A named query is defined in a Hibernate mapping file.
721: * @param queryName the name of a Hibernate query in a mapping file
722: * @param paramName the name of parameter
723: * @param value the value of the parameter
724: * @return a {@link List} containing the results of the query execution
725: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
726: * @see org.hibernate.Session#getNamedQuery(String)
727: */
728: List findByNamedQueryAndNamedParam(String queryName,
729: String paramName, Object value) throws DataAccessException;
730:
731: /**
732: * Execute a named query, binding a number of values to ":" named
733: * parameters in the query string.
734: * <p>A named query is defined in a Hibernate mapping file.
735: * @param queryName the name of a Hibernate query in a mapping file
736: * @param paramNames the names of the parameters
737: * @param values the values of the parameters
738: * @return a {@link List} containing the results of the query execution
739: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
740: * @see org.hibernate.Session#getNamedQuery(String)
741: */
742: List findByNamedQueryAndNamedParam(String queryName,
743: String[] paramNames, Object[] values)
744: throws DataAccessException;
745:
746: /**
747: * Execute a named query, binding the properties of the given bean to
748: * ":" named parameters in the query string.
749: * <p>A named query is defined in a Hibernate mapping file.
750: * @param queryName the name of a Hibernate query in a mapping file
751: * @param valueBean the values of the parameters
752: * @return a {@link List} containing the results of the query execution
753: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
754: * @see org.hibernate.Query#setProperties
755: * @see org.hibernate.Session#getNamedQuery(String)
756: */
757: List findByNamedQueryAndValueBean(String queryName, Object valueBean)
758: throws DataAccessException;
759:
760: //-------------------------------------------------------------------------
761: // Convenience finder methods for detached criteria
762: //-------------------------------------------------------------------------
763:
764: /**
765: * Execute a query based on a given Hibernate criteria object.
766: * @param criteria the detached Hibernate criteria object,
767: * which can for example be held in an instance variable of a DAO
768: * @return a {@link List} containing 0 or more persistent instances
769: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
770: * @see org.hibernate.criterion.DetachedCriteria#getExecutableCriteria(org.hibernate.Session)
771: */
772: List findByCriteria(DetachedCriteria criteria)
773: throws DataAccessException;
774:
775: /**
776: * Execute a query based on the given Hibernate criteria object.
777: * @param criteria the detached Hibernate criteria object,
778: * which can for example be held in an instance variable of a DAO
779: * @param firstResult the index of the first result object to be retrieved
780: * (numbered from 0)
781: * @param maxResults the maximum number of result objects to retrieve
782: * (or <=0 for no limit)
783: * @return a {@link List} containing 0 or more persistent instances
784: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
785: * @see org.hibernate.criterion.DetachedCriteria#getExecutableCriteria(org.hibernate.Session)
786: * @see org.hibernate.Criteria#setFirstResult(int)
787: * @see org.hibernate.Criteria#setMaxResults(int)
788: */
789: List findByCriteria(DetachedCriteria criteria, int firstResult,
790: int maxResults) throws DataAccessException;
791:
792: /**
793: * Execute a query based on the given example entity object.
794: * @param exampleEntity an instance of the desired entity,
795: * serving as example for "query-by-example"
796: * @return a {@link List} containing 0 or more persistent instances
797: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
798: * @see org.hibernate.criterion.Example#create(Object)
799: */
800: List findByExample(Object exampleEntity) throws DataAccessException;
801:
802: /**
803: * Execute a query based on the given example entity object.
804: * @param entityName the name of the persistent entity
805: * @param exampleEntity an instance of the desired entity,
806: * serving as example for "query-by-example"
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: */
811: List findByExample(String entityName, Object exampleEntity)
812: throws DataAccessException;
813:
814: /**
815: * Execute a query based on a given example entity object.
816: * @param exampleEntity an instance of the desired entity,
817: * serving as example for "query-by-example"
818: * @param firstResult the index of the first result object to be retrieved
819: * (numbered from 0)
820: * @param maxResults the maximum number of result objects to retrieve
821: * (or <=0 for no limit)
822: * @return a {@link List} containing 0 or more persistent instances
823: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
824: * @see org.hibernate.criterion.Example#create(Object)
825: * @see org.hibernate.Criteria#setFirstResult(int)
826: * @see org.hibernate.Criteria#setMaxResults(int)
827: */
828: List findByExample(Object exampleEntity, int firstResult,
829: int maxResults) throws DataAccessException;
830:
831: /**
832: * Execute a query based on a given example entity object.
833: * @param entityName the name of the persistent entity
834: * @param exampleEntity an instance of the desired entity,
835: * serving as example for "query-by-example"
836: * @param firstResult the index of the first result object to be retrieved
837: * (numbered from 0)
838: * @param maxResults the maximum number of result objects to retrieve
839: * (or <=0 for no limit)
840: * @return a {@link List} containing 0 or more persistent instances
841: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
842: * @see org.hibernate.criterion.Example#create(Object)
843: * @see org.hibernate.Criteria#setFirstResult(int)
844: * @see org.hibernate.Criteria#setMaxResults(int)
845: */
846: List findByExample(String entityName, Object exampleEntity,
847: int firstResult, int maxResults) throws DataAccessException;
848:
849: //-------------------------------------------------------------------------
850: // Convenience query methods for iteration and bulk updates/deletes
851: //-------------------------------------------------------------------------
852:
853: /**
854: * Execute a query for persistent instances.
855: * <p>Returns the results as an {@link Iterator}. Entities returned are
856: * initialized on demand. See the Hibernate API documentation for details.
857: * @param queryString a query expressed in Hibernate's query language
858: * @return an {@link Iterator} containing 0 or more persistent instances
859: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
860: * @see org.hibernate.Session#createQuery
861: * @see org.hibernate.Query#iterate
862: */
863: Iterator iterate(String queryString) throws DataAccessException;
864:
865: /**
866: * Execute a query for persistent instances, binding one value
867: * to a "?" parameter in the query string.
868: * <p>Returns the results as an {@link Iterator}. Entities returned are
869: * initialized on demand. See the Hibernate API documentation for details.
870: * @param queryString a query expressed in Hibernate's query language
871: * @param value the value of the parameter
872: * @return an {@link Iterator} containing 0 or more persistent instances
873: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
874: * @see org.hibernate.Session#createQuery
875: * @see org.hibernate.Query#iterate
876: */
877: Iterator iterate(String queryString, Object value)
878: throws DataAccessException;
879:
880: /**
881: * Execute a query for persistent instances, binding a number of
882: * values to "?" parameters in the query string.
883: * <p>Returns the results as an {@link Iterator}. Entities returned are
884: * initialized on demand. See the Hibernate API documentation for details.
885: * @param queryString a query expressed in Hibernate's query language
886: * @param values the values of the parameters
887: * @return an {@link Iterator} containing 0 or more persistent instances
888: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
889: * @see org.hibernate.Session#createQuery
890: * @see org.hibernate.Query#iterate
891: */
892: Iterator iterate(String queryString, Object[] values)
893: throws DataAccessException;
894:
895: /**
896: * Immediately close an {@link Iterator} created by any of the various
897: * <code>iterate(..)</code> operations, instead of waiting until the
898: * session is closed or disconnected.
899: * @param it the <code>Iterator</code> to close
900: * @throws DataAccessException if the <code>Iterator</code> could not be closed
901: * @see org.hibernate.Hibernate#close
902: */
903: void closeIterator(Iterator it) throws DataAccessException;
904:
905: /**
906: * Update/delete all objects according to the given query.
907: * @param queryString an update/delete query expressed in Hibernate's query language
908: * @return the number of instances updated/deleted
909: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
910: * @see org.hibernate.Session#createQuery
911: * @see org.hibernate.Query#executeUpdate
912: */
913: int bulkUpdate(String queryString) throws DataAccessException;
914:
915: /**
916: * Update/delete all objects according to the given query, binding one value
917: * to a "?" parameter in the query string.
918: * @param queryString an update/delete query expressed in Hibernate's query language
919: * @param value the value of the parameter
920: * @return the number of instances updated/deleted
921: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
922: * @see org.hibernate.Session#createQuery
923: * @see org.hibernate.Query#executeUpdate
924: */
925: int bulkUpdate(String queryString, Object value)
926: throws DataAccessException;
927:
928: /**
929: * Update/delete all objects according to the given query, binding a number of
930: * values to "?" parameters in the query string.
931: * @param queryString an update/delete query expressed in Hibernate's query language
932: * @param values the values of the parameters
933: * @return the number of instances updated/deleted
934: * @throws org.springframework.dao.DataAccessException in case of Hibernate errors
935: * @see org.hibernate.Session#createQuery
936: * @see org.hibernate.Query#executeUpdate
937: */
938: int bulkUpdate(String queryString, Object[] values)
939: throws DataAccessException;
940:
941: }
|