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