com.interface21.orm.hibernate
Class HibernateTemplate

java.lang.Object
  |
  +--com.interface21.orm.hibernate.HibernateTemplate
All Implemented Interfaces:
InitializingBean

public class HibernateTemplate
extends java.lang.Object
implements InitializingBean

Helper class that simplifies Hibernate data access code, and converts checked HibernateExceptions into unchecked HibernateJdbc/SystemExceptions, compatible to the com.interface21.dao exception hierarchy.

The central method is "execute", supporting Hibernate code implementing the HibernateCallback interface. It provides Hibernate Session handling such that neither the HibernateCallback implementation nor the calling code needs to explicitly care about retrieving/closing Hibernate Sessions, or handling Session lifecycle exceptions.

Typically used to implement data access or business logic services that use Hibernate within their implementation but are Hibernate-agnostic in their interface. The latter resp. code calling the latter only have to deal with business objects, query objects, and com.interface21.dao exceptions.

Can be used within a service implementation via direct instantiation with a SessionFactory reference, or get prepared in an application context and given to services as bean reference. Note: The SessionFactory should always be configured as bean in the application context, in the first case given to the service directly, in the second case to the prepared template.

This class can be considered a programmatic alternative to HibernateInterceptor. The major advantage is its straightforwardness, the major disadvantage that no checked application exceptions can get thrown from within data access code. Respective checks and the actual throwing of such exceptions can often be deferred to after callback execution, though.

Note that even if HibernateTransactionManager is used for transaction demarcation in higher-level services, all those services above the data access layer don't need need to be Hibernate-aware. Setting such a special PlatformTransactionManager is a configuration issue, without introducing code dependencies. For example, switching to JTA is just a matter of Spring configuration (use JtaTransactionManager instead), without needing to touch application code.

LocalSessionFactoryBean is the preferred way of obtaining a reference to a specific Hibernate SessionFactory, at least in a non-EJB environment. Registering a SessionFactory with JNDI is only advisable when using Hibernate's JCA Connector, i.e. when the application server cares for initialization. Else, portability is rather limited: Manual JNDI binding isn't supported by some application servers (e.g. Tomcat).

Note: This class, like all of Spring's Hibernate support, requires Hibernate 2.0 (initially developed with RC1).

Since:
02.05.2003
Author:
Juergen Hoeller
See Also:
HibernateCallback, HibernateInterceptor, HibernateTransactionManager, LocalSessionFactoryBean, JndiObjectFactoryBean

Constructor Summary
HibernateTemplate()
          Create a new HibernateTemplate instance.
HibernateTemplate(net.sf.hibernate.SessionFactory sessionFactory)
          Create a new HibernateTemplate instance.
 
Method Summary
 void afterPropertiesSet()
          Invoked by a BeanFactory after it has set all bean properties supplied.
 java.lang.Object execute(HibernateCallback action)
          Executes the action specified by the given action object within a session.
 java.util.List executeFind(HibernateCallback action)
          Execute the specified action assuming that the result object is a List.
 net.sf.hibernate.SessionFactory getSessionFactory()
          Return the Hibernate SessionFactory that should be used to create Hibernate Sessions.
 boolean isForceFlush()
          Return if a flush should be forced after executing the callback code.
 void setForceFlush(boolean forceFlush)
          If a flush of the Hibernate Session should be forced after executing the callback code.
 void setSessionFactory(net.sf.hibernate.SessionFactory sessionFactory)
          Set the Hibernate SessionFactory that should be used to create Hibernate Sessions.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

HibernateTemplate

public HibernateTemplate()
Create a new HibernateTemplate instance.

HibernateTemplate

public HibernateTemplate(net.sf.hibernate.SessionFactory sessionFactory)
Create a new HibernateTemplate instance.
Parameters:
sessionFactory - SessionFactory to create Sessions
Method Detail

setSessionFactory

public void setSessionFactory(net.sf.hibernate.SessionFactory sessionFactory)
Set the Hibernate SessionFactory that should be used to create Hibernate Sessions.

getSessionFactory

public net.sf.hibernate.SessionFactory getSessionFactory()
Return the Hibernate SessionFactory that should be used to create Hibernate Sessions.

setForceFlush

public void setForceFlush(boolean forceFlush)
If a flush of the Hibernate Session should be forced after executing the callback code. By default, the template will only trigger a flush if not in a Hibernate transaction, as a final flush will occur on commit anyway.

A forced flush leads to immediate synchronization with the database, even if in a Hibernate transaction. This causes inconsistencies to show up and throw a respective exception immediately. But the drawbacks are:


isForceFlush

public boolean isForceFlush()
Return if a flush should be forced after executing the callback code.

executeFind

public java.util.List executeFind(HibernateCallback action)
                           throws DataAccessException,
                                  java.lang.RuntimeException
Execute the specified action assuming that the result object is a List. This is a convenience method for executing Hibernate find calls within an action.
Parameters:
action - action object that specifies the Hibernate action
Returns:
a result object returned by the action, or null
Throws:
DataAccessException - in case of Hibernate errors
java.lang.RuntimeException - in case of application exceptions thrown by the action object

afterPropertiesSet

public void afterPropertiesSet()
Description copied from interface: InitializingBean
Invoked by a BeanFactory after it has set all bean properties supplied.
This method allows the bean instance to perform initialization only possible when all bean properties have been set and to throw an exception in the event of misconfiguration.
Specified by:
afterPropertiesSet in interface InitializingBean
Following copied from interface: com.interface21.beans.factory.InitializingBean
Throws:
java.lang.Exception - in the event of misconfiguration (such as failure to set an essential property) or if initialization fails.

execute

public java.lang.Object execute(HibernateCallback action)
                         throws DataAccessException,
                                java.lang.RuntimeException
Executes the action specified by the given action object within a session. Application exceptions thrown by the action object get propagated to the caller, Hibernate exceptions are transformed into appropriate DAO ones. Allows for returning a result object, i.e. a business object or a collection of business objects.

Note: Callback code is not supposed to handle transactions itself! Use an appropriate transaction manager like HibernateTransactionManager.

Parameters:
action - action object that specifies the Hibernate action
Returns:
a result object returned by the action, or null
Throws:
DataAccessException - in case of Hibernate errors
java.lang.RuntimeException - in case of application exceptions thrown by the action object
See Also:
HibernateTransactionManager, com.interface21.dao, com.interface21.transaction


Rod Johnson and Spring contributors 2001-2003.