The Spring Framework

## org.springframework.orm.jpa
Class JpaTemplate

    java.lang.Object
      org.springframework.orm.jpa.EntityManagerFactoryAccessor
          org.springframework.orm.jpa.JpaAccessor
              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.

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.

NOTE: JpaTemplate mainly exists as a sibling of JdoTemplate and HibernateTemplate, offering 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.)

JpaTemplate can be considered as direct alternative to working with the native 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 native JPA API. Note that exception translation can also be achieved through AOP advice; check out `PersistenceExceptionTranslationPostProcessor`.

`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:
  `EntityManagerFactoryAccessor.setEntityManagerFactory(javax.persistence.EntityManagerFactory)`, `JpaCallback`, `EntityManager`, `LocalEntityManagerFactoryBean`, `LocalContainerEntityManagerFactoryBean`, `JpaTransactionManager`, `JtaTransactionManager`, `OpenEntityManagerInViewFilter`, `OpenEntityManagerInViewInterceptor`

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,?> params)`
`List` `findByNamedQuery(String queryName)`
`List` `findByNamedQuery(String queryName, Object... values)`
`List` `findByNamedQueryAndNamedParams(String queryName, Map<String,?> 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,?> 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,?> params)
                                        throws DataAccessException

  Specified by:
    `findByNamedQueryAndNamedParams` in interface `JpaOperations`
  Throws:
    `DataAccessException`

The Spring Framework

Copyright © 2002-2008 The Spring Framework.