com.interface21.orm.jdo
Class JdoTemplate

java.lang.Object
  |
  +--com.interface21.orm.jdo.JdoTemplate

All Implemented Interfaces:

InitializingBean

public class JdoTemplate

extends java.lang.Object

implements InitializingBean

Helper class that simplifies JDO data access code, and converts JDOExceptions into JdoUsage/JdoSystemException, compatible to the com.interface21.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 com.interface21.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

Constructor Summary

JdoTemplate()
Create a new JdoTemplate instance.

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

Method Summary

void	afterPropertiesSet() Invoked by a BeanFactory after it has set all bean properties supplied.
java.lang.Object	execute(JdoCallback action) Executes the action specified by the given action object within a PersistenceManager.
javax.jdo.PersistenceManagerFactory	getPersistenceManagerFactory() Return the JDO PersistenceManagerFactory that should be used to create PersistenceManagers.
void	setPersistenceManagerFactory(javax.jdo.PersistenceManagerFactory pmf) Set the JDO PersistenceManagerFactory that should be used to create PersistenceManagers.

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

setPersistenceManagerFactory

public void setPersistenceManagerFactory(javax.jdo.PersistenceManagerFactory pmf)

Set the JDO PersistenceManagerFactory that should be used to create PersistenceManagers.

getPersistenceManagerFactory

public javax.jdo.PersistenceManagerFactory getPersistenceManagerFactory()

Return the JDO PersistenceManagerFactory that should be used to create PersistenceManagers.

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(JdoCallback action)
                         throws DataAccessException,
                                java.lang.RuntimeException

Executes the action specified by the given action object within a PersistenceManager. Application exceptions thrown by the action object get propagated to the caller, JDO 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 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

java.lang.RuntimeException - in case of application exceptions thrown by the action object

See Also:

JdoTransactionManager, com.interface21.dao, com.interface21.transaction