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