The Spring Framework

org.springframework.orm.jpa
Class JpaTemplate

java.lang.Object
  extended by org.springframework.orm.jpa.EntityManagerFactoryAccessor
      extended by org.springframework.orm.jpa.JpaAccessor
          extended by org.springframework.orm.jpa.JpaTemplate
All Implemented Interfaces:
InitializingBean, JpaOperations

public class JpaTemplate
extends JpaAccessor
implements JpaOperations

Helper class that allows for writing JPA data access code in the same style as with Spring's well-known JdoTemplate and HibernateTemplate classes. Automatically converts PersistenceExceptions into Spring DataAccessExceptions, following the org.springframework.dao exception hierarchy.

NOTE: JpaTemplate mainly exists as a sibling of JdoTemplate and HibernateTemplate, to offer the same style for people used to it. For newly started projects, consider adopting the standard JPA style of coding data access objects instead, based on a "shared EntityManager" reference injected via a Spring bean definition or the JPA PersistenceContext annotation. (Using Spring's SharedEntityManagerBean / PersistenceAnnotationBeanPostProcessor, or using a direct JNDI lookup for an EntityManager on a Java EE 5 server.)

The central method is of this template is "execute", supporting JPA access code implementing the JpaCallback interface. It provides JPA EntityManager handling such that neither the JpaCallback implementation nor the calling code needs to explicitly care about retrieving/closing EntityManagers, or handling JPA lifecycle exceptions.

Can be used within a service implementation via direct instantiation with a EntityManagerFactory reference, or get prepared in an application context and given to services as bean reference. Note: The EntityManagerFactory 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.

JpaTemplate can be considered as direct alternative to working with the raw JPA EntityManager API (through a shared EntityManager reference, as outlined above). The major advantage is its automatic conversion to DataAccessExceptions, the major disadvantage is that it introduces another thin layer on top of the target API.

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

LocalContainerEntityManagerFactoryBean is the preferred way of obtaining a reference to an EntityManagerFactory, at least outside of a full Java EE 5 environment. The Spring application context will manage its lifecycle, initializing and shutting down the factory as part of the application. Within a Java EE 5 environment, you will typically work with a server-managed EntityManagerFactory that is exposed via JNDI, obtained through Spring's JndiObjectFactoryBean.

Since:
2.0
Author:
Juergen Hoeller
See Also:
JdoTemplate, HibernateTemplate, SharedEntityManagerBean, PersistenceAnnotationBeanPostProcessor, EntityManagerFactoryAccessor.setEntityManagerFactory(javax.persistence.EntityManagerFactory), execute(JpaCallback), EntityManager, LocalEntityManagerFactoryBean, LocalContainerEntityManagerFactoryBean, JndiObjectFactoryBean

Field Summary
 
Fields inherited from class org.springframework.orm.jpa.EntityManagerFactoryAccessor
logger
 
Constructor Summary
JpaTemplate()
          Create a new JpaTemplate instance.
JpaTemplate(javax.persistence.EntityManager em)
          Create a new JpaTemplate instance.
JpaTemplate(javax.persistence.EntityManagerFactory emf)
          Create a new JpaTemplate instance.
 
Method Summary
 boolean contains(Object entity)
           
protected  javax.persistence.EntityManager createEntityManagerProxy(javax.persistence.EntityManager em)
          Create a close-suppressing proxy for the given JPA EntityManager.
 Object execute(JpaCallback action)
           
 Object execute(JpaCallback action, boolean exposeNativeEntityManager)
          Execute the action specified by the given action object within a EntityManager.
 List executeFind(JpaCallback action)
           
<T> T
find(Class<T> entityClass, Object id)
           
 List find(String queryString)
           
 List find(String queryString, Object... values)
           
 List findByNamedParams(String queryString, Map<String,? extends Object> params)
           
 List findByNamedQuery(String queryName)
           
 List findByNamedQuery(String queryName, Object... values)
           
 List findByNamedQueryAndNamedParams(String queryName, Map<String,? extends Object> params)
           
 void flush()
           
<T> T
getReference(Class<T> entityClass, Object id)
           
 boolean isExposeNativeEntityManager()
          Return whether to expose the native JPA EntityManager to JpaCallback code, or rather an EntityManager proxy.
<T> T
merge(T entity)
           
 void persist(Object entity)
           
 void refresh(Object entity)
           
 void remove(Object entity)
           
 void setExposeNativeEntityManager(boolean exposeNativeEntityManager)
          Set whether to expose the native JPA EntityManager to JpaCallback code.
 
Methods inherited from class org.springframework.orm.jpa.JpaAccessor
afterPropertiesSet, flushIfNecessary, getEntityManager, getJpaDialect, isFlushEager, setEntityManager, setFlushEager, setJpaDialect, translateIfNecessary
 
Methods inherited from class org.springframework.orm.jpa.EntityManagerFactoryAccessor
createEntityManager, getEntityManagerFactory, getJpaPropertyMap, getTransactionalEntityManager, setEntityManagerFactory, setJpaProperties, setJpaPropertyMap
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JpaTemplate

public JpaTemplate()
Create a new JpaTemplate instance.


JpaTemplate

public JpaTemplate(javax.persistence.EntityManagerFactory emf)
Create a new JpaTemplate instance.

Parameters:
emf - EntityManagerFactory to create EntityManagers

JpaTemplate

public JpaTemplate(javax.persistence.EntityManager em)
Create a new JpaTemplate instance.

Parameters:
em - EntityManager to use
Method Detail

setExposeNativeEntityManager

public void setExposeNativeEntityManager(boolean exposeNativeEntityManager)
Set whether to expose the native JPA EntityManager to JpaCallback code. Default is "false": a EntityManager proxy will be returned, suppressing close calls and automatically applying transaction timeouts (if any).

As there is often a need to cast to a provider-specific EntityManager class in DAOs that use the JPA 1.0 API, for JPA 2.0 previews and other provider-specific functionality, the exposed proxy implements all interfaces implemented by the original EntityManager. If this is not sufficient, turn this flag to "true".

See Also:
JpaCallback, EntityManager

isExposeNativeEntityManager

public boolean isExposeNativeEntityManager()
Return whether to expose the native JPA EntityManager to JpaCallback code, or rather an EntityManager proxy.


execute

public Object execute(JpaCallback action)
               throws DataAccessException
Specified by:
execute in interface JpaOperations
Throws:
DataAccessException

executeFind

public List executeFind(JpaCallback action)
                 throws DataAccessException
Specified by:
executeFind in interface JpaOperations
Throws:
DataAccessException

execute

public Object execute(JpaCallback action,
                      boolean exposeNativeEntityManager)
               throws DataAccessException
Execute the action specified by the given action object within a EntityManager.

Parameters:
action - callback object that specifies the JPA action
exposeNativeEntityManager - whether to expose the native JPA entity manager to callback code
Returns:
a result object returned by the action, or null
Throws:
DataAccessException - in case of JPA errors

createEntityManagerProxy

protected javax.persistence.EntityManager createEntityManagerProxy(javax.persistence.EntityManager em)
Create a close-suppressing proxy for the given JPA EntityManager. The proxy also prepares returned JPA Query objects.

Parameters:
em - the JPA EntityManager to create a proxy for
Returns:
the EntityManager proxy, implementing all interfaces implemented by the passed-in EntityManager object (that is, also implementing all provider-specific extension interfaces)
See Also:
EntityManager.close()

find

public <T> T find(Class<T> entityClass,
                  Object id)
       throws DataAccessException
Specified by:
find in interface JpaOperations
Throws:
DataAccessException

getReference

public <T> T getReference(Class<T> entityClass,
                          Object id)
               throws DataAccessException
Specified by:
getReference in interface JpaOperations
Throws:
DataAccessException

contains

public boolean contains(Object entity)
                 throws DataAccessException
Specified by:
contains in interface JpaOperations
Throws:
DataAccessException

refresh

public void refresh(Object entity)
             throws DataAccessException
Specified by:
refresh in interface JpaOperations
Throws:
DataAccessException

persist

public void persist(Object entity)
             throws DataAccessException
Specified by:
persist in interface JpaOperations
Throws:
DataAccessException

merge

public <T> T merge(T entity)
        throws DataAccessException
Specified by:
merge in interface JpaOperations
Throws:
DataAccessException

remove

public void remove(Object entity)
            throws DataAccessException
Specified by:
remove in interface JpaOperations
Throws:
DataAccessException

flush

public void flush()
           throws DataAccessException
Specified by:
flush in interface JpaOperations
Throws:
DataAccessException

find

public List find(String queryString)
          throws DataAccessException
Specified by:
find in interface JpaOperations
Throws:
DataAccessException

find

public List find(String queryString,
                 Object... values)
          throws DataAccessException
Specified by:
find in interface JpaOperations
Throws:
DataAccessException

findByNamedParams

public List findByNamedParams(String queryString,
                              Map<String,? extends Object> params)
                       throws DataAccessException
Specified by:
findByNamedParams in interface JpaOperations
Throws:
DataAccessException

findByNamedQuery

public List findByNamedQuery(String queryName)
                      throws DataAccessException
Specified by:
findByNamedQuery in interface JpaOperations
Throws:
DataAccessException

findByNamedQuery

public List findByNamedQuery(String queryName,
                             Object... values)
                      throws DataAccessException
Specified by:
findByNamedQuery in interface JpaOperations
Throws:
DataAccessException

findByNamedQueryAndNamedParams

public List findByNamedQueryAndNamedParams(String queryName,
                                           Map<String,? extends Object> params)
                                    throws DataAccessException
Specified by:
findByNamedQueryAndNamedParams in interface JpaOperations
Throws:
DataAccessException

The Spring Framework

Copyright © 2002-2007 The Spring Framework.