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