The Spring Framework

## org.springframework.orm.hibernate3
Interface HibernateOperations

All Known Implementing Classes:
  HibernateTemplate

    public interface HibernateOperations

Interface that specifies a basic set of Hibernate operations, implemented by `HibernateTemplate`. Not often used, but a useful option to enhance testability, as it can easily be mocked or stubbed.

Defines `HibernateTemplate`'s data access methods that mirror various `Session` methods. Users are strongly encouraged to read the Hibernate `Session` javadocs for details on the semantics of those methods.

Note that operations that return an `Iterator` (i.e. `iterate(..)`) are supposed to be used within Spring-driven or JTA-driven transactions (with `HibernateTransactionManager`, `JtaTransactionManager`, or EJB CMT). Else, the `Iterator` won't be able to read results from its `ResultSet` anymore, as the underlying Hibernate `Session` will already have been closed.

Note that lazy loading will just work with an open Hibernate `Session`, either within a transaction or within `OpenSessionInViewFilter`/ `OpenSessionInViewInterceptor`. Furthermore, some operations just make sense within transactions, for example: `contains`, `evict`, `lock`, `flush`, `clear`.

Since:
  1.2
Author:
  Juergen Hoeller
See Also:
  `HibernateTemplate`, `Session`, `HibernateTransactionManager`, `JtaTransactionManager`, `OpenSessionInViewFilter`, `OpenSessionInViewInterceptor`

Method Summary
`int` `bulkUpdate(String queryString)` Update/delete all objects according to the given query.
`int` `bulkUpdate(String queryString, Object value)` Update/delete all objects according to the given query, binding one value to a "?"
`int` `bulkUpdate(String queryString, Object[] values)` Update/delete all objects according to the given query, binding a number of values to "?"
`void` `clear()` Remove all objects from the `Session` cache, and cancel all pending saves, updates and deletes.
`void` `closeIterator(Iterator it)` Immediately close an `Iterator` created by any of the various `iterate(..)`
`boolean` `contains(Object entity)` Check whether the given object is in the Session cache.
`void` `delete(Object entity)` Delete the given persistent instance.
`void` `delete(Object entity, LockMode lockMode)` Delete the given persistent instance.
`void` `delete(String entityName, Object entity)` Delete the given persistent instance.
`void` `delete(String entityName, Object entity, LockMode lockMode)` Delete the given persistent instance.
`void` `deleteAll(Collection entities)` Delete all given persistent instances.
`Filter` `enableFilter(String filterName)` Return an enabled Hibernate `Filter` for the given filter name.
`void` `evict(Object entity)` Remove the given object from the `Session` cache.
`Object` `execute(HibernateCallback action)` Execute the action specified by the given action object within a `Session`.
`List` `executeFind(HibernateCallback action)` Execute the specified action assuming that the result object is a `List`.
`List` `find(String queryString)` Execute an HQL query.
`List` `find(String queryString, Object value)` Execute an HQL query, binding one value to a "?"
`List` `find(String queryString, Object[] values)` Execute an HQL query, binding a number of values to "?"
`List` `findByCriteria(DetachedCriteria criteria)` Execute a query based on a given Hibernate criteria object.
`List` `findByCriteria(DetachedCriteria criteria, int firstResult, int maxResults)` Execute a query based on the given Hibernate criteria object.
`List` `findByExample(Object exampleEntity)` Execute a query based on the given example entity object.
`List` `findByExample(Object exampleEntity, int firstResult, int maxResults)` Execute a query based on a given example entity object.
`List` `findByExample(String entityName, Object exampleEntity)` Execute a query based on the given example entity object.
`List` `findByExample(String entityName, Object exampleEntity, int firstResult, int maxResults)` Execute a query based on a given example entity object.
`List` `findByNamedParam(String queryString, String[] paramNames, Object[] values)` Execute an HQL query, binding a number of values to ":" named parameters in the query string.
`List` `findByNamedParam(String queryString, String paramName, Object value)` Execute an HQL query, binding one value to a ":" named parameter in the query string.
`List` `findByNamedQuery(String queryName)` Execute a named query.
`List` `findByNamedQuery(String queryName, Object value)` Execute a named query, binding one value to a "?"
`List` `findByNamedQuery(String queryName, Object[] values)` Execute a named query binding a number of values to "?"
`List` `findByNamedQueryAndNamedParam(String queryName, String[] paramNames, Object[] values)` Execute a named query, binding a number of values to ":" named parameters in the query string.
`List` `findByNamedQueryAndNamedParam(String queryName, String paramName, Object value)` Execute a named query, binding one value to a ":" named parameter in the query string.
`List` `findByNamedQueryAndValueBean(String queryName, Object valueBean)` Execute a named query, binding the properties of the given bean to ":" named parameters in the query string.
`List` `findByValueBean(String queryString, Object valueBean)` Execute an HQL query, binding the properties of the given bean to named parameters in the query string.
`void` `flush()` Flush all pending saves, updates and deletes to the database.
`Object` `get(Class entityClass, Serializable id)` Return the persistent instance of the given entity class with the given identifier, or `null` if not found.
`Object` `get(Class entityClass, Serializable id, LockMode lockMode)` Return the persistent instance of the given entity class with the given identifier, or `null` if not found.
`Object` `get(String entityName, Serializable id)` Return the persistent instance of the given entity class with the given identifier, or `null` if not found.
`Object` `get(String entityName, Serializable id, LockMode lockMode)` Return the persistent instance of the given entity class with the given identifier, or `null` if not found.
`void` `initialize(Object proxy)` Force initialization of a Hibernate proxy or persistent collection.
`Iterator` `iterate(String queryString)` Execute a query for persistent instances.
`Iterator` `iterate(String queryString, Object value)` Execute a query for persistent instances, binding one value to a "?"
`Iterator` `iterate(String queryString, Object[] values)` Execute a query for persistent instances, binding a number of values to "?"
`Object` `load(Class entityClass, Serializable id)` Return the persistent instance of the given entity class with the given identifier, throwing an exception if not found.
`Object` `load(Class entityClass, Serializable id, LockMode lockMode)` Return the persistent instance of the given entity class with the given identifier, throwing an exception if not found.
`void` `load(Object entity, Serializable id)` Load the persistent instance with the given identifier into the given object, throwing an exception if not found.
`Object` `load(String entityName, Serializable id)` Return the persistent instance of the given entity class with the given identifier, throwing an exception if not found.
`Object` `load(String entityName, Serializable id, LockMode lockMode)` Return the persistent instance of the given entity class with the given identifier, throwing an exception if not found.
`List` `loadAll(Class entityClass)` Return all persistent instances of the given entity class.
`void` `lock(Object entity, LockMode lockMode)` Obtain the specified lock level upon the given object, implicitly checking whether the corresponding database entry still exists.
`void` `lock(String entityName, Object entity, LockMode lockMode)` Obtain the specified lock level upon the given object, implicitly checking whether the corresponding database entry still exists.
`Object` `merge(Object entity)` Copy the state of the given object onto the persistent object with the same identifier.
`Object` `merge(String entityName, Object entity)` Copy the state of the given object onto the persistent object with the same identifier.
`void` `persist(Object entity)` Persist the given transient instance.
`void` `persist(String entityName, Object entity)` Persist the given transient instance.
`void` `refresh(Object entity)` Re-read the state of the given persistent instance.
`void` `refresh(Object entity, LockMode lockMode)` Re-read the state of the given persistent instance.
`void` `replicate(Object entity, ReplicationMode replicationMode)` Persist the state of the given detached instance according to the given replication mode, reusing the current identifier value.
`void` `replicate(String entityName, Object entity, ReplicationMode replicationMode)` Persist the state of the given detached instance according to the given replication mode, reusing the current identifier value.
`Serializable` `save(Object entity)` Persist the given transient instance.
`Serializable` `save(String entityName, Object entity)` Persist the given transient instance.
`void` `saveOrUpdate(Object entity)` Save or update the given persistent instance, according to its id (matching the configured "unsaved-value"?).
`void` `saveOrUpdate(String entityName, Object entity)` Save or update the given persistent instance, according to its id (matching the configured "unsaved-value"?).
`void` `saveOrUpdateAll(Collection entities)` Deprecated. as of Spring 2.5, in favor of individual `saveOrUpdate` or `merge` usage
`void` `update(Object entity)` Update the given persistent instance, associating it with the current Hibernate `Session`.
`void` `update(Object entity, LockMode lockMode)` Update the given persistent instance, associating it with the current Hibernate `Session`.
`void` `update(String entityName, Object entity)` Update the given persistent instance, associating it with the current Hibernate `Session`.
`void` `update(String entityName, Object entity, LockMode lockMode)` Update the given persistent instance, associating it with the current Hibernate `Session`.

Method Detail

### execute

    Object execute(HibernateCallback action)
                   throws DataAccessException

  Execute the action specified by the given action object within a `Session`.

  Application exceptions thrown by the action object get propagated to the caller (can only be unchecked). Hibernate exceptions are transformed into appropriate DAO ones. Allows for returning a result object, that is a domain object or a collection of domain objects.

  Note: Callback code is not supposed to handle transactions itself! Use an appropriate transaction manager like `HibernateTransactionManager`. Generally, callback code must not touch any `Session` lifecycle methods, like close, disconnect, or reconnect, to let the template do its work.

  Parameters:
    `action` - callback object that specifies the Hibernate action
  Returns:
    a result object returned by the action, or `null`
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `HibernateTransactionManager`, `org.springframework.dao`, `org.springframework.transaction`, `Session`

### executeFind

    List executeFind(HibernateCallback action)
                     throws DataAccessException

  Execute the specified action assuming that the result object is a `List`.

  This is a convenience method for executing Hibernate find calls or queries within an action.

  Parameters:
    `action` - calback object that specifies the Hibernate action
  Returns:
    a List result returned by the action, or `null`
  Throws:
    `DataAccessException` - in case of Hibernate errors

### get

    Object get(Class entityClass,
               Serializable id)
               throws DataAccessException

  Return the persistent instance of the given entity class with the given identifier, or `null` if not found.

  This method is a thin wrapper around `Session.get(Class, java.io.Serializable)` for convenience. For an explanation of the exact semantics of this method, please do refer to the Hibernate API documentation in the first instance.

  Parameters:
    `entityClass` - a persistent class
    `id` - the identifier of the persistent instance
  Returns:
    the persistent instance, or `null` if not found
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.get(Class, java.io.Serializable)`

### get

    Object get(Class entityClass,
               Serializable id,
               LockMode lockMode)
               throws DataAccessException

  Return the persistent instance of the given entity class with the given identifier, or `null` if not found.

  Obtains the specified lock mode if the instance exists.

  This method is a thin wrapper around `Session.get(Class, java.io.Serializable, LockMode)` for convenience. For an explanation of the exact semantics of this method, please do refer to the Hibernate API documentation in the first instance.

  Parameters:
    `entityClass` - a persistent class
    `id` - the identifier of the persistent instance
    `lockMode` - the lock mode to obtain
  Returns:
    the persistent instance, or `null` if not found
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.get(Class, java.io.Serializable, org.hibernate.LockMode)`

### get

    Object get(String entityName,
               Serializable id)
               throws DataAccessException

  Return the persistent instance of the given entity class with the given identifier, or `null` if not found.

  This method is a thin wrapper around `Session.get(String, java.io.Serializable)` for convenience. For an explanation of the exact semantics of this method, please do refer to the Hibernate API documentation in the first instance.

  Parameters:
    `entityName` - the name of the persistent entity
    `id` - the identifier of the persistent instance
  Returns:
    the persistent instance, or `null` if not found
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.get(Class, java.io.Serializable)`

### get

    Object get(String entityName,
               Serializable id,
               LockMode lockMode)
               throws DataAccessException

  Return the persistent instance of the given entity class with the given identifier, or `null` if not found. Obtains the specified lock mode if the instance exists.

  This method is a thin wrapper around `Session.get(String, java.io.Serializable, LockMode)` for convenience. For an explanation of the exact semantics of this method, please do refer to the Hibernate API documentation in the first instance.

  Parameters:
    `entityName` - the name of the persistent entity
    `id` - the identifier of the persistent instance
    `lockMode` - the lock mode to obtain
  Returns:
    the persistent instance, or `null` if not found
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.get(Class, java.io.Serializable, org.hibernate.LockMode)`

### load

    Object load(Class entityClass,
                Serializable id)
                throws DataAccessException

  Return the persistent instance of the given entity class with the given identifier, throwing an exception if not found.

  This method is a thin wrapper around `Session.load(Class, java.io.Serializable)` for convenience. For an explanation of the exact semantics of this method, please do refer to the Hibernate API documentation in the first instance.

  Parameters:
    `entityClass` - a persistent class
    `id` - the identifier of the persistent instance
  Returns:
    the persistent instance
  Throws:
    `ObjectRetrievalFailureException` - if not found
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.load(Class, java.io.Serializable)`

### load

    Object load(Class entityClass,
                Serializable id,
                LockMode lockMode)
                throws DataAccessException

  Return the persistent instance of the given entity class with the given identifier, throwing an exception if not found. Obtains the specified lock mode if the instance exists.

  This method is a thin wrapper around `Session.load(Class, java.io.Serializable, LockMode)` for convenience. For an explanation of the exact semantics of this method, please do refer to the Hibernate API documentation in the first instance.

  Parameters:
    `entityClass` - a persistent class
    `id` - the identifier of the persistent instance
    `lockMode` - the lock mode to obtain
  Returns:
    the persistent instance
  Throws:
    `ObjectRetrievalFailureException` - if not found
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.load(Class, java.io.Serializable)`

### load

    Object load(String entityName,
                Serializable id)
                throws DataAccessException

  Return the persistent instance of the given entity class with the given identifier, throwing an exception if not found.

  This method is a thin wrapper around `Session.load(String, java.io.Serializable)` for convenience. For an explanation of the exact semantics of this method, please do refer to the Hibernate API documentation in the first instance.

  Parameters:
    `entityName` - the name of the persistent entity
    `id` - the identifier of the persistent instance
  Returns:
    the persistent instance
  Throws:
    `ObjectRetrievalFailureException` - if not found
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.load(Class, java.io.Serializable)`

### load

    Object load(String entityName,
                Serializable id,
                LockMode lockMode)
                throws DataAccessException

  Return the persistent instance of the given entity class with the given identifier, throwing an exception if not found.

  Obtains the specified lock mode if the instance exists.

  This method is a thin wrapper around `Session.load(String, java.io.Serializable, LockMode)` for convenience. For an explanation of the exact semantics of this method, please do refer to the Hibernate API documentation in the first instance.

  Parameters:
    `entityName` - the name of the persistent entity
    `id` - the identifier of the persistent instance
    `lockMode` - the lock mode to obtain
  Returns:
    the persistent instance
  Throws:
    `ObjectRetrievalFailureException` - if not found
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.load(Class, java.io.Serializable)`

### loadAll

    List loadAll(Class entityClass)
                 throws DataAccessException

  Return all persistent instances of the given entity class. Note: Use queries or criteria for retrieving a specific subset.

  Parameters:
    `entityClass` - a persistent class
  Returns:
    a `List` containing 0 or more persistent instances
  Throws:
    `DataAccessException` - if there is a Hibernate error
  See Also:
    `Session.createCriteria(java.lang.Class)`

### load

    void load(Object entity,
              Serializable id)
              throws DataAccessException

  Load the persistent instance with the given identifier into the given object, throwing an exception if not found.

  This method is a thin wrapper around `Session.load(Object, java.io.Serializable)` for convenience. For an explanation of the exact semantics of this method, please do refer to the Hibernate API documentation in the first instance.

  Parameters:
    `entity` - the object (of the target class) to load into
    `id` - the identifier of the persistent instance
  Throws:
    `ObjectRetrievalFailureException` - if not found
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.load(Object, java.io.Serializable)`

### refresh

    void refresh(Object entity)
                 throws DataAccessException

  Re-read the state of the given persistent instance.

  Parameters:
    `entity` - the persistent instance to re-read
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.refresh(Object)`

### refresh

    void refresh(Object entity,
                 LockMode lockMode)
                 throws DataAccessException

  Re-read the state of the given persistent instance. Obtains the specified lock mode for the instance.

  Parameters:
    `entity` - the persistent instance to re-read
    `lockMode` - the lock mode to obtain
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.refresh(Object, org.hibernate.LockMode)`

### contains

    boolean contains(Object entity)
                     throws DataAccessException

  Check whether the given object is in the Session cache.

  Parameters:
    `entity` - the persistence instance to check
  Returns:
    whether the given object is in the Session cache
  Throws:
    `DataAccessException` - if there is a Hibernate error
  See Also:
    `Session.contains(java.lang.Object)`

### evict

    void evict(Object entity)
               throws DataAccessException

  Remove the given object from the `Session` cache.

  Parameters:
    `entity` - the persistent instance to evict
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.evict(java.lang.Object)`

### initialize

    void initialize(Object proxy)
                    throws DataAccessException

  Force initialization of a Hibernate proxy or persistent collection.

  Parameters:
    `proxy` - a proxy for a persistent object or a persistent collection
  Throws:
    `DataAccessException` - if we can't initialize the proxy, for example because it is not associated with an active Session
  See Also:
    `Hibernate.initialize(java.lang.Object)`

### enableFilter

    Filter enableFilter(String filterName)
                        throws IllegalStateException

  Return an enabled Hibernate `Filter` for the given filter name. The returned `Filter` instance can be used to set filter parameters.

  Parameters:
    `filterName` - the name of the filter
  Returns:
    the enabled Hibernate `Filter` (either already enabled or enabled on the fly by this operation)
  Throws:
    `IllegalStateException` - if we are not running within a transactional Session (in which case this operation does not make sense)

### lock

    void lock(Object entity,
              LockMode lockMode)
              throws DataAccessException

  Obtain the specified lock level upon the given object, implicitly checking whether the corresponding database entry still exists.

  Parameters:
    `entity` - the persistent instance to lock
    `lockMode` - the lock mode to obtain
  Throws:
    `ObjectOptimisticLockingFailureException` - if not found
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.lock(Object, org.hibernate.LockMode)`

### lock

    void lock(String entityName,
              Object entity,
              LockMode lockMode)
              throws DataAccessException

  Obtain the specified lock level upon the given object, implicitly checking whether the corresponding database entry still exists.

  Parameters:
    `entityName` - the name of the persistent entity
    `entity` - the persistent instance to lock
    `lockMode` - the lock mode to obtain
  Throws:
    `ObjectOptimisticLockingFailureException` - if not found
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.lock(String, Object, org.hibernate.LockMode)`

### save

    Serializable save(Object entity)
                      throws DataAccessException

  Persist the given transient instance.

  Parameters:
    `entity` - the transient instance to persist
  Returns:
    the generated identifier
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.save(Object)`

### save

    Serializable save(String entityName,
                      Object entity)
                      throws DataAccessException

  Persist the given transient instance.

  Parameters:
    `entityName` - the name of the persistent entity
    `entity` - the transient instance to persist
  Returns:
    the generated identifier
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.save(String, Object)`

### update

    void update(Object entity)
                throws DataAccessException

  Update the given persistent instance, associating it with the current Hibernate `Session`.

  Parameters:
    `entity` - the persistent instance to update
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.update(Object)`

### update

    void update(Object entity,
                LockMode lockMode)
                throws DataAccessException

  Update the given persistent instance, associating it with the current Hibernate `Session`.

  Obtains the specified lock mode if the instance exists, implicitly checking whether the corresponding database entry still exists.

  Parameters:
    `entity` - the persistent instance to update
    `lockMode` - the lock mode to obtain
  Throws:
    `ObjectOptimisticLockingFailureException` - if not found
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.update(Object)`

### update

    void update(String entityName,
                Object entity)
                throws DataAccessException

  Update the given persistent instance, associating it with the current Hibernate `Session`.

  Parameters:
    `entityName` - the name of the persistent entity
    `entity` - the persistent instance to update
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.update(String, Object)`

### update

    void update(String entityName,
                Object entity,
                LockMode lockMode)
                throws DataAccessException

  Update the given persistent instance, associating it with the current Hibernate `Session`.

  Obtains the specified lock mode if the instance exists, implicitly checking whether the corresponding database entry still exists.

  Parameters:
    `entityName` - the name of the persistent entity
    `entity` - the persistent instance to update
    `lockMode` - the lock mode to obtain
  Throws:
    `ObjectOptimisticLockingFailureException` - if not found
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.update(String, Object)`

### saveOrUpdate

    void saveOrUpdate(Object entity)
                      throws DataAccessException

  Save or update the given persistent instance, according to its id (matching the configured "unsaved-value"?). Associates the instance with the current Hibernate `Session`.

  Parameters:
    `entity` - the persistent instance to save or update (to be associated with the Hibernate `Session`)
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.saveOrUpdate(Object)`

### saveOrUpdate

    void saveOrUpdate(String entityName,
                      Object entity)
                      throws DataAccessException

  Save or update the given persistent instance, according to its id (matching the configured "unsaved-value"?). Associates the instance with the current Hibernate `Session`.

  Parameters:
    `entityName` - the name of the persistent entity
    `entity` - the persistent instance to save or update (to be associated with the Hibernate `Session`)
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.saveOrUpdate(String, Object)`

### saveOrUpdateAll

    void saveOrUpdateAll(Collection entities)
                         throws DataAccessException

  Deprecated. as of Spring 2.5, in favor of individual `saveOrUpdate` or `merge` usage

  Save or update all given persistent instances, according to its id (matching the configured "unsaved-value"?). Associates the instances with the current Hibernate `Session`.

  Parameters:
    `entities` - the persistent instances to save or update (to be associated with the Hibernate `Session`)
  Throws:
    `DataAccessException` - in case of Hibernate errors

### replicate

    void replicate(Object entity,
                   ReplicationMode replicationMode)
                   throws DataAccessException

  Persist the state of the given detached instance according to the given replication mode, reusing the current identifier value.

  Parameters:
    `entity` - the persistent object to replicate
    `replicationMode` - the Hibernate ReplicationMode
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.replicate(Object, org.hibernate.ReplicationMode)`

### replicate

    void replicate(String entityName,
                   Object entity,
                   ReplicationMode replicationMode)
                   throws DataAccessException

  Persist the state of the given detached instance according to the given replication mode, reusing the current identifier value.

  Parameters:
    `entityName` - the name of the persistent entity
    `entity` - the persistent object to replicate
    `replicationMode` - the Hibernate ReplicationMode
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.replicate(String, Object, org.hibernate.ReplicationMode)`

### persist

    void persist(Object entity)
                 throws DataAccessException

  Persist the given transient instance. Follows JSR-220 semantics.

  Similar to `save`, associating the given object with the current Hibernate `Session`.

  Parameters:
    `entity` - the persistent instance to persist
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.persist(Object)`, `save(java.lang.Object)`

### persist

    void persist(String entityName,
                 Object entity)
                 throws DataAccessException

  Persist the given transient instance. Follows JSR-220 semantics.

  Similar to `save`, associating the given object with the current Hibernate `Session`.

  Parameters:
    `entityName` - the name of the persistent entity
    `entity` - the persistent instance to persist
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.persist(String, Object)`, `save(java.lang.Object)`

### merge

    Object merge(Object entity)
                 throws DataAccessException

  Copy the state of the given object onto the persistent object with the same identifier. Follows JSR-220 semantics.

  Similar to `saveOrUpdate`, but never associates the given object with the current Hibernate Session. In case of a new entity, the state will be copied over as well.

  Note that `merge` will not update the identifiers in the passed-in object graph (in contrast to TopLink)! Consider registering Spring's `IdTransferringMergeEventListener` if you would like to have newly assigned ids transferred to the original object graph too.

  Parameters:
    `entity` - the object to merge with the corresponding persistence instance
  Returns:
    the updated, registered persistent instance
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.merge(Object)`, `saveOrUpdate(java.lang.Object)`, `IdTransferringMergeEventListener`

### merge

    Object merge(String entityName,
                 Object entity)
                 throws DataAccessException

  Copy the state of the given object onto the persistent object with the same identifier. Follows JSR-220 semantics.

  Similar to `saveOrUpdate`, but never associates the given object with the current Hibernate `Session`. In the case of a new entity, the state will be copied over as well.

  Note that `merge` will not update the identifiers in the passed-in object graph (in contrast to TopLink)! Consider registering Spring's `IdTransferringMergeEventListener` if you would like to have newly assigned ids transferred to the original object graph too.

  Parameters:
    `entityName` - the name of the persistent entity
    `entity` - the object to merge with the corresponding persistence instance
  Returns:
    the updated, registered persistent instance
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.merge(String, Object)`, `saveOrUpdate(java.lang.Object)`

### delete

    void delete(Object entity)
                throws DataAccessException

  Delete the given persistent instance.

  Parameters:
    `entity` - the persistent instance to delete
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.delete(Object)`

### delete

    void delete(Object entity,
                LockMode lockMode)
                throws DataAccessException

  Delete the given persistent instance.

  Obtains the specified lock mode if the instance exists, implicitly checking whether the corresponding database entry still exists.

  Parameters:
    `entity` - the persistent instance to delete
    `lockMode` - the lock mode to obtain
  Throws:
    `ObjectOptimisticLockingFailureException` - if not found
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.delete(Object)`

### delete

    void delete(String entityName,
                Object entity)
                throws DataAccessException

  Delete the given persistent instance.

  Parameters:
    `entityName` - the name of the persistent entity
    `entity` - the persistent instance to delete
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.delete(Object)`

### delete

    void delete(String entityName,
                Object entity,
                LockMode lockMode)
                throws DataAccessException

  Delete the given persistent instance.

  Obtains the specified lock mode if the instance exists, implicitly checking whether the corresponding database entry still exists.

  Parameters:
    `entityName` - the name of the persistent entity
    `entity` - the persistent instance to delete
    `lockMode` - the lock mode to obtain
  Throws:
    `ObjectOptimisticLockingFailureException` - if not found
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.delete(Object)`

### deleteAll

    void deleteAll(Collection entities)
                   throws DataAccessException

  Delete all given persistent instances.

  This can be combined with any of the find methods to delete by query in two lines of code.

  Parameters:
    `entities` - the persistent instances to delete
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.delete(Object)`

### flush

    void flush()
               throws DataAccessException

  Flush all pending saves, updates and deletes to the database.

  Only invoke this for selective eager flushing, for example when JDBC code needs to see certain changes within the same transaction. Else, it is preferable to rely on auto-flushing at transaction completion.

  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.flush()`

### clear

    void clear()
               throws DataAccessException

  Remove all objects from the `Session` cache, and cancel all pending saves, updates and deletes.

  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.clear()`

### find

    List find(String queryString)
              throws DataAccessException

  Execute an HQL query.

  Parameters:
    `queryString` - a query expressed in Hibernate's query language
  Returns:
    a `List` containing the results of the query execution
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.createQuery(java.lang.String)`

### find

    List find(String queryString,
              Object value)
              throws DataAccessException

  Execute an HQL query, binding one value to a "?" parameter in the query string.

  Parameters:
    `queryString` - a query expressed in Hibernate's query language
    `value` - the value of the parameter
  Returns:
    a `List` containing the results of the query execution
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.createQuery(java.lang.String)`

### find

    List find(String queryString,
              Object[] values)
              throws DataAccessException

  Execute an HQL query, binding a number of values to "?" parameters in the query string.

  Parameters:
    `queryString` - a query expressed in Hibernate's query language
    `values` - the values of the parameters
  Returns:
    a `List` containing the results of the query execution
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.createQuery(java.lang.String)`

### findByNamedParam

    List findByNamedParam(String queryString,
                          String paramName,
                          Object value)
                          throws DataAccessException

  Execute an HQL query, binding one value to a ":" named parameter in the query string.

  Parameters:
    `queryString` - a query expressed in Hibernate's query language
    `paramName` - the name of the parameter
    `value` - the value of the parameter
  Returns:
    a `List` containing the results of the query execution
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.getNamedQuery(String)`

### findByNamedParam

    List findByNamedParam(String queryString,
                          String[] paramNames,
                          Object[] values)
                          throws DataAccessException

  Execute an HQL query, binding a number of values to ":" named parameters in the query string.

  Parameters:
    `queryString` - a query expressed in Hibernate's query language
    `paramNames` - the names of the parameters
    `values` - the values of the parameters
  Returns:
    a `List` containing the results of the query execution
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.getNamedQuery(String)`

### findByValueBean

    List findByValueBean(String queryString,
                         Object valueBean)
                         throws DataAccessException

  Execute an HQL query, binding the properties of the given bean to named parameters in the query string.

  Parameters:
    `queryString` - a query expressed in Hibernate's query language
    `valueBean` - the values of the parameters
  Returns:
    a `List` containing the results of the query execution
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Query.setProperties(java.lang.Object)`, `Session.createQuery(java.lang.String)`

### findByNamedQuery

    List findByNamedQuery(String queryName)
                          throws DataAccessException

  Execute a named query.

  A named query is defined in a Hibernate mapping file.

  Parameters:
    `queryName` - the name of a Hibernate query in a mapping file
  Returns:
    a `List` containing the results of the query execution
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.getNamedQuery(String)`

### findByNamedQuery

    List findByNamedQuery(String queryName,
                          Object value)
                          throws DataAccessException

  Execute a named query, binding one value to a "?" parameter in the query string.

  A named query is defined in a Hibernate mapping file.

  Parameters:
    `queryName` - the name of a Hibernate query in a mapping file
    `value` - the value of the parameter
  Returns:
    a `List` containing the results of the query execution
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.getNamedQuery(String)`

### findByNamedQuery

    List findByNamedQuery(String queryName,
                          Object[] values)
                          throws DataAccessException

  Execute a named query binding a number of values to "?" parameters in the query string.

  A named query is defined in a Hibernate mapping file.

  Parameters:
    `queryName` - the name of a Hibernate query in a mapping file
    `values` - the values of the parameters
  Returns:
    a `List` containing the results of the query execution
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.getNamedQuery(String)`

### findByNamedQueryAndNamedParam

    List findByNamedQueryAndNamedParam(String queryName,
                                       String paramName,
                                       Object value)
                                       throws DataAccessException

  Execute a named query, binding one value to a ":" named parameter in the query string.

  A named query is defined in a Hibernate mapping file.

  Parameters:
    `queryName` - the name of a Hibernate query in a mapping file
    `paramName` - the name of parameter
    `value` - the value of the parameter
  Returns:
    a `List` containing the results of the query execution
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.getNamedQuery(String)`

### findByNamedQueryAndNamedParam

    List findByNamedQueryAndNamedParam(String queryName,
                                       String[] paramNames,
                                       Object[] values)
                                       throws DataAccessException

  Execute a named query, binding a number of values to ":" named parameters in the query string.

  A named query is defined in a Hibernate mapping file.

  Parameters:
    `queryName` - the name of a Hibernate query in a mapping file
    `paramNames` - the names of the parameters
    `values` - the values of the parameters
  Returns:
    a `List` containing the results of the query execution
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.getNamedQuery(String)`

### findByNamedQueryAndValueBean

    List findByNamedQueryAndValueBean(String queryName,
                                      Object valueBean)
                                      throws DataAccessException

  Execute a named query, binding the properties of the given bean to ":" named parameters in the query string.

  A named query is defined in a Hibernate mapping file.

  Parameters:
    `queryName` - the name of a Hibernate query in a mapping file
    `valueBean` - the values of the parameters
  Returns:
    a `List` containing the results of the query execution
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Query.setProperties(java.lang.Object)`, `Session.getNamedQuery(String)`

### findByCriteria

    List findByCriteria(DetachedCriteria criteria)
                        throws DataAccessException

  Execute a query based on a given Hibernate criteria object.

  Parameters:
    `criteria` - the detached Hibernate criteria object, which can for example be held in an instance variable of a DAO
  Returns:
    a `List` containing 0 or more persistent instances
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `DetachedCriteria.getExecutableCriteria(org.hibernate.Session)`

### findByCriteria

    List findByCriteria(DetachedCriteria criteria,
                        int firstResult,
                        int maxResults)
                        throws DataAccessException

  Execute a query based on the given Hibernate criteria object.

  Parameters:
    `criteria` - the detached Hibernate criteria object, which can for example be held in an instance variable of a DAO
    `firstResult` - the index of the first result object to be retrieved (numbered from 0)
    `maxResults` - the maximum number of result objects to retrieve (or <=0 for no limit)
  Returns:
    a `List` containing 0 or more persistent instances
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `DetachedCriteria.getExecutableCriteria(org.hibernate.Session)`, `Criteria.setFirstResult(int)`, `Criteria.setMaxResults(int)`

### findByExample

    List findByExample(Object exampleEntity)
                       throws DataAccessException

  Execute a query based on the given example entity object.

  Parameters:
    `exampleEntity` - an instance of the desired entity, serving as example for "query-by-example"
  Returns:
    a `List` containing 0 or more persistent instances
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Example.create(Object)`

### findByExample

    List findByExample(String entityName,
                       Object exampleEntity)
                       throws DataAccessException

  Execute a query based on the given example entity object.

  Parameters:
    `entityName` - the name of the persistent entity
    `exampleEntity` - an instance of the desired entity, serving as example for "query-by-example"
  Returns:
    a `List` containing 0 or more persistent instances
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Example.create(Object)`

### findByExample

    List findByExample(Object exampleEntity,
                       int firstResult,
                       int maxResults)
                       throws DataAccessException

  Execute a query based on a given example entity object.

  Parameters:
    `exampleEntity` - an instance of the desired entity, serving as example for "query-by-example"
    `firstResult` - the index of the first result object to be retrieved (numbered from 0)
    `maxResults` - the maximum number of result objects to retrieve (or <=0 for no limit)
  Returns:
    a `List` containing 0 or more persistent instances
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Example.create(Object)`, `Criteria.setFirstResult(int)`, `Criteria.setMaxResults(int)`

### findByExample

    List findByExample(String entityName,
                       Object exampleEntity,
                       int firstResult,
                       int maxResults)
                       throws DataAccessException

  Execute a query based on a given example entity object.

  Parameters:
    `entityName` - the name of the persistent entity
    `exampleEntity` - an instance of the desired entity, serving as example for "query-by-example"
    `firstResult` - the index of the first result object to be retrieved (numbered from 0)
    `maxResults` - the maximum number of result objects to retrieve (or <=0 for no limit)
  Returns:
    a `List` containing 0 or more persistent instances
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Example.create(Object)`, `Criteria.setFirstResult(int)`, `Criteria.setMaxResults(int)`

### iterate

    Iterator iterate(String queryString)
                     throws DataAccessException

  Execute a query for persistent instances.

  Returns the results as an `Iterator`. Entities returned are initialized on demand. See the Hibernate API documentation for details.

  Parameters:
    `queryString` - a query expressed in Hibernate's query language
  Returns:
    an `Iterator` containing 0 or more persistent instances
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.createQuery(java.lang.String)`, `Query.iterate()`

### iterate

    Iterator iterate(String queryString,
                     Object value)
                     throws DataAccessException

  Execute a query for persistent instances, binding one value to a "?" parameter in the query string.

  Returns the results as an `Iterator`. Entities returned are initialized on demand. See the Hibernate API documentation for details.

  Parameters:
    `queryString` - a query expressed in Hibernate's query language
    `value` - the value of the parameter
  Returns:
    an `Iterator` containing 0 or more persistent instances
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.createQuery(java.lang.String)`, `Query.iterate()`

### iterate

    Iterator iterate(String queryString,
                     Object[] values)
                     throws DataAccessException

  Execute a query for persistent instances, binding a number of values to "?" parameters in the query string.

  Returns the results as an `Iterator`. Entities returned are initialized on demand. See the Hibernate API documentation for details.

  Parameters:
    `queryString` - a query expressed in Hibernate's query language
    `values` - the values of the parameters
  Returns:
    an `Iterator` containing 0 or more persistent instances
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.createQuery(java.lang.String)`, `Query.iterate()`

### closeIterator

    void closeIterator(Iterator it)
                       throws DataAccessException

  Immediately close an `Iterator` created by any of the various `iterate(..)` operations, instead of waiting until the session is closed or disconnected.

  Parameters:
    `it` - the `Iterator` to close
  Throws:
    `DataAccessException` - if the `Iterator` could not be closed
  See Also:
    `Hibernate.close(java.util.Iterator)`

### bulkUpdate

    int bulkUpdate(String queryString)
                   throws DataAccessException

  Update/delete all objects according to the given query.

  Parameters:
    `queryString` - an update/delete query expressed in Hibernate's query language
  Returns:
    the number of instances updated/deleted
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.createQuery(java.lang.String)`, `Query.executeUpdate()`

### bulkUpdate

    int bulkUpdate(String queryString,
                   Object value)
                   throws DataAccessException

  Update/delete all objects according to the given query, binding one value to a "?" parameter in the query string.

  Parameters:
    `queryString` - an update/delete query expressed in Hibernate's query language
    `value` - the value of the parameter
  Returns:
    the number of instances updated/deleted
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.createQuery(java.lang.String)`, `Query.executeUpdate()`

### bulkUpdate

    int bulkUpdate(String queryString,
                   Object[] values)
                   throws DataAccessException

  Update/delete all objects according to the given query, binding a number of values to "?" parameters in the query string.

  Parameters:
    `queryString` - an update/delete query expressed in Hibernate's query language
    `values` - the values of the parameters
  Returns:
    the number of instances updated/deleted
  Throws:
    `DataAccessException` - in case of Hibernate errors
  See Also:
    `Session.createQuery(java.lang.String)`, `Query.executeUpdate()`

The Spring Framework

Copyright © 2002-2008 The Spring Framework.