org.springframework.orm.jdo
Class JdoTemplate

java.lang.Object
  org.springframework.orm.jdo.JdoAccessor
      org.springframework.orm.jdo.JdoTemplate

All Implemented Interfaces:

InitializingBean

public class JdoTemplate

extends JdoAccessor

Helper class that simplifies JDO data access code, and converts JDOExceptions into JdoUsage/JdoSystemException, compatible to the org.springframework.dao exception hierarchy.

The central method is "execute", supporting JDO code implementing the JdoCallback interface. It provides JDO PersistenceManager handling such that neither theJdoCallback implementation nor the calling code needs to explicitly care about retrieving/closing PersistenceManagers, or handling JDO lifecycle exceptions.

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

Can be used within a service implementation via direct instantiation with a PersistenceManagerFactory reference, or get prepared in an application context and given to services as bean reference. Note: The PersistenceManagerFactory 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 JdoInterceptor. 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 JdoTransactionManager is used for transaction demarcation in higher-level services, all those services above the data access layer don't need need to be JDO-aware. Setting such a special PlatformTransactionManager is a configuration issue, without introducing code dependencies.

LocalPersistenceManagerFactoryBean is the preferred way of obtaining a reference to a specific PersistenceManagerFactory, at least in a non-EJB environment. Registering a PersistenceManagerFactory with JNDI is only advisable when using a 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).

Since:

03.06.2003

Author:

Juergen Hoeller

See Also:

JdoCallback, JdoTransactionManager

Field Summary

Fields inherited from class org.springframework.orm.jdo.JdoAccessor

logger

Constructor Summary

JdoTemplate()
Create a new JdoTemplate instance.

JdoTemplate(javax.jdo.PersistenceManagerFactory pmf)
Create a new JdoTemplate instance.

Method Summary

java.lang.Object	execute(JdoCallback action) Execute the action specified by the given action object within a PersistenceManager.
boolean	isAllowCreate() Return if a new Session should be created if no thread-bound found.
void	setAllowCreate(boolean allowCreate) Set if a new PersistenceManager should be created if no thread-bound found.

Methods inherited from class org.springframework.orm.jdo.JdoAccessor

afterPropertiesSet, convertJdoAccessException, flushIfNecessary, getJdoDialect, getPersistenceManagerFactory, isFlushEager, setFlushEager, setJdoDialect, setPersistenceManagerFactory

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JdoTemplate

public JdoTemplate()

Create a new JdoTemplate instance.

JdoTemplate

public JdoTemplate(javax.jdo.PersistenceManagerFactory pmf)

Create a new JdoTemplate instance.

Parameters:

pmf - PersistenceManagerFactory to create PersistenceManagers

Method Detail

setAllowCreate

public void setAllowCreate(boolean allowCreate)

Set if a new PersistenceManager should be created if no thread-bound found.

JdoTemplate is aware of a respective PersistenceManager bound to the current thread, for example when using JdoTransactionManager. If allowCreate is true, a new PersistenceManager will be created if none found. If false, an IllegalStateException will get thrown in this case.

See Also:

PersistenceManagerFactoryUtils.getPersistenceManager(javax.jdo.PersistenceManagerFactory, boolean)

isAllowCreate

public boolean isAllowCreate()

Return if a new Session should be created if no thread-bound found.

execute

public java.lang.Object execute(JdoCallback action)
                         throws DataAccessException

Execute the action specified by the given action object within a PersistenceManager. Application exceptions thrown by the action object get propagated to the caller (can only be unchecked). JDO exceptions are transformed into appropriate DAO ones. Allows for returning a result object, i.e. 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 JdoTransactionManager.

Parameters:

action - action object that specifies the JDO action

Returns:

a result object returned by the action, or null

Throws:

DataAccessException - in case of JDO errors

See Also:

JdoTransactionManager, org.springframework.dao, org.springframework.transaction