org.springframework.orm.jdo
Class JdoTemplate

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

All Implemented Interfaces:

InitializingBean, JdoOperations

public class JdoTemplate

extends JdoAccessor

implements JdoOperations

Helper class that simplifies JDO data access code, and converts JDOExceptions into Spring DataAccessExceptions, following 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 the JdoCallback 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 or 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).

Note that lazy loading will just work with an open JDO PersistenceManager, either within a Spring-driven transaction (with JdoTransactionManager or JtaTransactionManager) or within OpenPersistenceManagerInViewFilter/Interceptor. Furthermore, some operations just make sense within transactions, for example: evict, evictAll, flush.

Since:

03.06.2003

Author:

Juergen Hoeller

See Also:

JdoAccessor.setPersistenceManagerFactory(javax.jdo.PersistenceManagerFactory), JdoCallback, PersistenceManager, JdoInterceptor, LocalPersistenceManagerFactoryBean, JndiObjectFactoryBean, JdoTransactionManager, JtaTransactionManager, OpenPersistenceManagerInViewFilter, OpenPersistenceManagerInViewInterceptor

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.

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

Method Summary

protected javax.jdo.PersistenceManager	createPersistenceManagerProxy(javax.jdo.PersistenceManager pm) Create a close-suppressing proxy for the given JDO PersistenceManager.
void	deletePersistent(Object entity) Delete the given persistent instance.
void	deletePersistentAll(Collection entities) Delete all given persistent instances.
void	evict(Object entity) Remove the given object from the PersistenceManager cache.
void	evictAll() Remove all objects from the PersistenceManager cache.
Object	execute(JdoCallback action) Execute the action specified by the given action object within a PersistenceManager.
Object	execute(JdoCallback action, boolean exposeNativePersistenceManager) Execute the action specified by the given action object within a PersistenceManager.
Collection	executeFind(JdoCallback action) Execute the specified action assuming that the result object is a Collection.
Collection	find(Class entityClass) Return all persistent instances of the given class.
Collection	find(Class entityClass, String filter) Return all persistent instances of the given class that match the given JDOQL filter.
Collection	find(Class entityClass, String filter, String ordering) Return all persistent instances of the given class that match the given JDOQL filter, with the given result ordering.
Collection	find(Class entityClass, String filter, String parameters, Map values) Return all persistent instances of the given class that match the given JDOQL filter, using the given parameter declarations and parameter values.
Collection	find(Class entityClass, String filter, String parameters, Map values, String ordering) Return all persistent instances of the given class that match the given JDOQL filter, using the given parameter declarations and parameter values, with the given result ordering.
Collection	find(Class entityClass, String filter, String parameters, Object[] values) Return all persistent instances of the given class that match the given JDOQL filter, using the given parameter declarations and parameter values.
Collection	find(Class entityClass, String filter, String parameters, Object[] values, String ordering) Return all persistent instances of the given class that match the given JDOQL filter, using the given parameter declarations and parameter values, with the given result ordering.
void	flush() Flush all transactional modifications to the database.
Object	getObjectById(Class entityClass, Serializable idValue) Return the persistent instance of the given entity class with the given id value, throwing an exception if not found.
Object	getObjectById(Serializable objectId) Return the persistent instance with the given JDO object id, throwing an exception if not found.
boolean	isAllowCreate() Return if a new PersistenceManager should be created if no thread-bound found.
boolean	isExposeNativePersistenceManager() Return whether to expose the native JDO PersistenceManager to JdoCallback code, or rather a PersistenceManager proxy.
void	makePersistent(Object entity) Make the given transient instance persistent.
void	prepareQuery(javax.jdo.Query query) Prepare the given JDO query object.
void	refresh(Object entity) Re-read the state of the given persistent instance.
void	refreshAll() Re-read the state of all persistent instances.
void	setAllowCreate(boolean allowCreate) Set if a new PersistenceManager should be created if no thread-bound found.
void	setExposeNativePersistenceManager(boolean exposeNativePersistenceManager) Set whether to expose the native JDO PersistenceManager to JdoCallback code.

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

JdoTemplate

public JdoTemplate(javax.jdo.PersistenceManagerFactory pmf,
                   boolean allowCreate)

Create a new JdoTemplate instance.

Parameters:

pmf - PersistenceManagerFactory to create PersistenceManagers

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

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 PersistenceManager should be created if no thread-bound found.

setExposeNativePersistenceManager

public void setExposeNativePersistenceManager(boolean exposeNativePersistenceManager)

Set whether to expose the native JDO PersistenceManager to JdoCallback code. Default is true; if turned off, a PersistenceManager proxy will be returned, suppressing close calls and automatically applying transaction timeouts (if any).

The default is "true" for the time being, because there is often a need to cast to a vendor-specific PersistenceManager class in DAOs that use the JDO 1.0 API, for JDO 2.0 previews and other vendor-specific functionality. This is likely to change to "false" in a later Spring version.

See Also:

JdoCallback, PersistenceManager, prepareQuery(javax.jdo.Query)

isExposeNativePersistenceManager

public boolean isExposeNativePersistenceManager()

Return whether to expose the native JDO PersistenceManager to JdoCallback code, or rather a PersistenceManager proxy.

execute

public Object execute(JdoCallback action)
               throws DataAccessException

Description copied from interface: JdoOperations

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.

Specified by:

execute in interface JdoOperations

Parameters:

action - callback 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, PersistenceManager

executeFind

public Collection executeFind(JdoCallback action)
                       throws DataAccessException

Description copied from interface: JdoOperations

Execute the specified action assuming that the result object is a Collection. This is a convenience method for executing JDO queries within an action.

Specified by:

executeFind in interface JdoOperations

Parameters:

action - callback object that specifies the JDO action

Returns:

a Collection result returned by the action, or null

Throws:

DataAccessException - in case of JDO errors

execute

public Object execute(JdoCallback action,
                      boolean exposeNativePersistenceManager)
               throws DataAccessException

Execute the action specified by the given action object within a PersistenceManager.

Parameters:

action - callback object that specifies the JDO action

exposeNativePersistenceManager - whether to expose the native JDO persistence manager to callback code

Returns:

a result object returned by the action, or null

Throws:

DataAccessException - in case of JDO errors

createPersistenceManagerProxy

protected javax.jdo.PersistenceManager createPersistenceManagerProxy(javax.jdo.PersistenceManager pm)

Create a close-suppressing proxy for the given JDO PersistenceManager. The proxy also prepares returned JDO Query objects.

Parameters:

pm - the JDO PersistenceManager to create a proxy for

Returns:

the PersistenceManager proxy

See Also:

PersistenceManager.close(), prepareQuery(javax.jdo.Query)

getObjectById

public Object getObjectById(Serializable objectId)
                     throws DataAccessException

Description copied from interface: JdoOperations

Return the persistent instance with the given JDO object id, throwing an exception if not found.

A JDO object id identifies both the persistent class and the id within the namespace of that class.

Specified by:

getObjectById in interface JdoOperations

Parameters:

objectId - a JDO object id of the persistent instance

Returns:

the persistent instance

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.getObjectById(java.lang.Object, boolean)

getObjectById

public Object getObjectById(Class entityClass,
                            Serializable idValue)
                     throws DataAccessException

Description copied from interface: JdoOperations

Return the persistent instance of the given entity class with the given id value, throwing an exception if not found.

The given id value is typically just unique within the namespace of the persistent class. Its toString value must correspond to the toString value of the corresponding JDO object id.

Usually, the passed-in value will have originated from the primary key field of a persistent object that uses JDO's application identity.

Specified by:

getObjectById in interface JdoOperations

Parameters:

entityClass - a persistent class

idValue - an id value of the persistent instance

Returns:

the persistent instance

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.getObjectById(java.lang.Object, boolean), PersistenceManager.newObjectIdInstance(java.lang.Class, java.lang.String)

evict

public void evict(Object entity)
           throws DataAccessException

Description copied from interface: JdoOperations

Remove the given object from the PersistenceManager cache.

Specified by:

evict in interface JdoOperations

Parameters:

entity - the persistent instance to evict

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.evict(java.lang.Object)

evictAll

public void evictAll()
              throws DataAccessException

Description copied from interface: JdoOperations

Remove all objects from the PersistenceManager cache.

Specified by:

evictAll in interface JdoOperations

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.evictAll(java.lang.Object[])

refresh

public void refresh(Object entity)
             throws DataAccessException

Description copied from interface: JdoOperations

Re-read the state of the given persistent instance.

Specified by:

refresh in interface JdoOperations

Parameters:

entity - the persistent instance to re-read

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.refresh(java.lang.Object)

refreshAll

public void refreshAll()
                throws DataAccessException

Description copied from interface: JdoOperations

Re-read the state of all persistent instances.

Specified by:

refreshAll in interface JdoOperations

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.refreshAll(java.lang.Object[])

makePersistent

public void makePersistent(Object entity)
                    throws DataAccessException

Description copied from interface: JdoOperations

Make the given transient instance persistent.

Specified by:

makePersistent in interface JdoOperations

Parameters:

entity - the transient instance to make persistent

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.makePersistent(java.lang.Object)

deletePersistent

public void deletePersistent(Object entity)
                      throws DataAccessException

Description copied from interface: JdoOperations

Delete the given persistent instance.

Specified by:

deletePersistent in interface JdoOperations

Parameters:

entity - the persistent instance to delete

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.deletePersistent(java.lang.Object)

deletePersistentAll

public void deletePersistentAll(Collection entities)
                         throws DataAccessException

Description copied from interface: JdoOperations

Delete all given persistent instances.

This can be combined with any of the find methods to delete by query in two lines of code.

Specified by:

deletePersistentAll in interface JdoOperations

Parameters:

entities - the persistent instances to delete

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.deletePersistentAll(java.lang.Object[])

flush

public void flush()
           throws DataAccessException

Description copied from interface: JdoOperations

Flush all transactional modifications to the database.

Only invoke this for selective eager flushing, for example when JDBC code needs to see certain changes within the same transaction. Else, it's preferable to rely on auto-flushing at transaction completion.

Specified by:

flush in interface JdoOperations

Throws:

DataAccessException - in case of JDO errors

See Also:

JdoDialect.flush(javax.jdo.PersistenceManager)

find

public Collection find(Class entityClass)
                throws DataAccessException

Description copied from interface: JdoOperations

Return all persistent instances of the given class.

Specified by:

find in interface JdoOperations

Parameters:

entityClass - a persistent class

Returns:

the persistent instances

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.newQuery(Class)

find

public Collection find(Class entityClass,
                       String filter)
                throws DataAccessException

Description copied from interface: JdoOperations

Return all persistent instances of the given class that match the given JDOQL filter.

Specified by:

find in interface JdoOperations

Parameters:

entityClass - a persistent class

filter - the JDOQL filter to match (or null if none)

Returns:

the persistent instances

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.newQuery(Class, String)

find

public Collection find(Class entityClass,
                       String filter,
                       String ordering)
                throws DataAccessException

Description copied from interface: JdoOperations

Return all persistent instances of the given class that match the given JDOQL filter, with the given result ordering.

Specified by:

find in interface JdoOperations

Parameters:

entityClass - a persistent class

filter - the JDOQL filter to match (or null if none)

ordering - the ordering of the result (or null if none)

Returns:

the persistent instances

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.newQuery(Class, String), Query.setOrdering(java.lang.String)

find

public Collection find(Class entityClass,
                       String filter,
                       String parameters,
                       Object[] values)
                throws DataAccessException

Description copied from interface: JdoOperations

Return all persistent instances of the given class that match the given JDOQL filter, using the given parameter declarations and parameter values.

Specified by:

find in interface JdoOperations

Parameters:

entityClass - a persistent class

filter - the JDOQL filter to match

parameters - the JDOQL parameter declarations

values - the corresponding parameter values

Returns:

the persistent instances

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.newQuery(Class, String), Query.declareParameters(java.lang.String), Query.executeWithArray(java.lang.Object[])

find

public Collection find(Class entityClass,
                       String filter,
                       String parameters,
                       Object[] values,
                       String ordering)
                throws DataAccessException

Description copied from interface: JdoOperations

Return all persistent instances of the given class that match the given JDOQL filter, using the given parameter declarations and parameter values, with the given result ordering.

Specified by:

find in interface JdoOperations

Parameters:

entityClass - a persistent class

filter - the JDOQL filter to match

parameters - the JDOQL parameter declarations

values - the corresponding parameter values

ordering - the ordering of the result (or null if none)

Returns:

the persistent instances

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.newQuery(Class, String), Query.declareParameters(java.lang.String), Query.executeWithArray(java.lang.Object[]), Query.setOrdering(java.lang.String)

find

public Collection find(Class entityClass,
                       String filter,
                       String parameters,
                       Map values)
                throws DataAccessException

Description copied from interface: JdoOperations

Return all persistent instances of the given class that match the given JDOQL filter, using the given parameter declarations and parameter values.

Specified by:

find in interface JdoOperations

Parameters:

entityClass - a persistent class

filter - the JDOQL filter to match

parameters - the JDOQL parameter declarations

values - a Map with parameter names as keys and parameter values

Returns:

the persistent instances

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.newQuery(Class, String), Query.declareParameters(java.lang.String), Query.executeWithMap(java.util.Map)

find

public Collection find(Class entityClass,
                       String filter,
                       String parameters,
                       Map values,
                       String ordering)
                throws DataAccessException

Description copied from interface: JdoOperations

Return all persistent instances of the given class that match the given JDOQL filter, using the given parameter declarations and parameter values, with the given result ordering.

Specified by:

find in interface JdoOperations

Parameters:

entityClass - a persistent class

filter - the JDOQL filter to match

parameters - the JDOQL parameter declarations

values - a Map with parameter names as keys and parameter values

ordering - the ordering of the result (or null if none)

Returns:

the persistent instances

Throws:

DataAccessException - in case of JDO errors

See Also:

PersistenceManager.newQuery(Class, String), Query.declareParameters(java.lang.String), Query.executeWithMap(java.util.Map), Query.setOrdering(java.lang.String)

prepareQuery

public void prepareQuery(javax.jdo.Query query)
                  throws javax.jdo.JDOException

Prepare the given JDO query object. To be used within a JdoCallback. Applies a transaction timeout, if any. If you don't use such timeouts, the call is a no-op.

In general, prefer a proxied PersistenceManager instead, which will automatically apply the transaction timeout (through the use of a special PersistenceManager proxy). You need to set the "exposeNativePersistenceManager" property to "false" to activate this. Note that you won't be able to cast to a vendor-specific JDO PersistenceManager class anymore then.

Parameters:

query - the JDO query object

Throws:

javax.jdo.JDOException - if the query could not be properly prepared

See Also:

JdoCallback.doInJdo(javax.jdo.PersistenceManager), PersistenceManagerFactoryUtils.applyTransactionTimeout(javax.jdo.Query, javax.jdo.PersistenceManagerFactory, org.springframework.orm.jdo.JdoDialect), setExposeNativePersistenceManager(boolean)