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