org.springframework.orm.jdo.JdoTemplate Maven / Gradle / Ivy
/*
* Copyright 2002-2009 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.orm.jdo;
import java.lang.reflect.InvocationHandler;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;
import java.util.Collection;
import java.util.Map;
import javax.jdo.JDOException;
import javax.jdo.PersistenceManager;
import javax.jdo.PersistenceManagerFactory;
import javax.jdo.Query;
import org.springframework.dao.DataAccessException;
import org.springframework.dao.InvalidDataAccessApiUsageException;
import org.springframework.transaction.support.TransactionSynchronizationManager;
import org.springframework.util.Assert;
import org.springframework.util.ClassUtils;
/**
* 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 access code
* implementing the {@link 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 as direct alternative to working with the
* raw JDO PersistenceManager API (through
* PersistenceManagerFactoryUtils.getPersistenceManager()
).
* The major advantage is its automatic conversion to DataAccessExceptions, the
* major disadvantage that no checked application exceptions can get thrown from
* within data access code. Corresponding checks and the actual throwing of such
* exceptions can often be deferred to after callback execution, though.
*
*
{@link LocalPersistenceManagerFactoryBean} is the preferred way of obtaining
* a reference to a specific PersistenceManagerFactory, at least in a non-EJB
* environment. The Spring application context will manage its lifecycle,
* initializing and shutting down the factory as part of the application.
*
*
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
.
*
*
NOTE: This class requires JDO 2.0 or higher, as of Spring 2.5.
* As of Spring 3.0, it follows JDO 2.1 conventions in terms of generic
* parameter and return types, which still remaining compatible with JDO 2.0.
*
* @author Juergen Hoeller
* @since 03.06.2003
* @see #setPersistenceManagerFactory
* @see JdoCallback
* @see javax.jdo.PersistenceManager
* @see LocalPersistenceManagerFactoryBean
* @see JdoTransactionManager
* @see org.springframework.transaction.jta.JtaTransactionManager
* @see org.springframework.orm.jdo.support.OpenPersistenceManagerInViewFilter
* @see org.springframework.orm.jdo.support.OpenPersistenceManagerInViewInterceptor
*/
public class JdoTemplate extends JdoAccessor implements JdoOperations {
private boolean allowCreate = true;
private boolean exposeNativePersistenceManager = false;
/**
* Create a new JdoTemplate instance.
*/
public JdoTemplate() {
}
/**
* Create a new JdoTemplate instance.
* @param pmf PersistenceManagerFactory to create PersistenceManagers
*/
public JdoTemplate(PersistenceManagerFactory pmf) {
setPersistenceManagerFactory(pmf);
afterPropertiesSet();
}
/**
* Create a new JdoTemplate instance.
* @param pmf PersistenceManagerFactory to create PersistenceManagers
* @param allowCreate if a non-transactional PersistenceManager should be created
* when no transactional PersistenceManager can be found for the current thread
*/
public JdoTemplate(PersistenceManagerFactory pmf, boolean allowCreate) {
setPersistenceManagerFactory(pmf);
setAllowCreate(allowCreate);
afterPropertiesSet();
}
/**
* Set if a new PersistenceManager should be created when no transactional
* PersistenceManager can be found for the current thread.
*
JdoTemplate is aware of a corresponding PersistenceManager bound to the
* current thread, for example when using JdoTransactionManager.
* If allowCreate is true, a new non-transactional PersistenceManager will be
* created if none found, which needs to be closed at the end of the operation.
* If false, an IllegalStateException will get thrown in this case.
* @see PersistenceManagerFactoryUtils#getPersistenceManager(javax.jdo.PersistenceManagerFactory, boolean)
*/
public void setAllowCreate(boolean allowCreate) {
this.allowCreate = allowCreate;
}
/**
* Return if a new PersistenceManager should be created if no thread-bound found.
*/
public boolean isAllowCreate() {
return this.allowCreate;
}
/**
* Set whether to expose the native JDO PersistenceManager to JdoCallback
* code. Default is "false": a PersistenceManager 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 PersistenceManager
* class in DAOs that use provider-specific functionality, the exposed proxy
* implements all interfaces implemented by the original PersistenceManager.
* If this is not sufficient, turn this flag to "true".
* @see JdoCallback
* @see javax.jdo.PersistenceManager
* @see #prepareQuery
*/
public void setExposeNativePersistenceManager(boolean exposeNativePersistenceManager) {
this.exposeNativePersistenceManager = exposeNativePersistenceManager;
}
/**
* Return whether to expose the native JDO PersistenceManager to JdoCallback
* code, or rather a PersistenceManager proxy.
*/
public boolean isExposeNativePersistenceManager() {
return this.exposeNativePersistenceManager;
}
public T execute(JdoCallback action) throws DataAccessException {
return execute(action, isExposeNativePersistenceManager());
}
public Collection executeFind(JdoCallback action) throws DataAccessException {
Object result = execute(action, isExposeNativePersistenceManager());
if (result != null && !(result instanceof Collection)) {
throw new InvalidDataAccessApiUsageException(
"Result object returned from JdoCallback isn't a Collection: [" + result + "]");
}
return (Collection) result;
}
/**
* Execute the action specified by the given action object within a
* PersistenceManager.
* @param action callback object that specifies the JDO action
* @param exposeNativePersistenceManager whether to expose the native
* JDO persistence manager to callback code
* @return a result object returned by the action, or null
* @throws org.springframework.dao.DataAccessException in case of JDO errors
*/
public T execute(JdoCallback action, boolean exposeNativePersistenceManager) throws DataAccessException {
Assert.notNull(action, "Callback object must not be null");
PersistenceManager pm = PersistenceManagerFactoryUtils.getPersistenceManager(
getPersistenceManagerFactory(), isAllowCreate());
boolean existingTransaction =
TransactionSynchronizationManager.hasResource(getPersistenceManagerFactory());
try {
PersistenceManager pmToExpose = (exposeNativePersistenceManager ? pm : createPersistenceManagerProxy(pm));
T result = action.doInJdo(pmToExpose);
flushIfNecessary(pm, existingTransaction);
return postProcessResult(result, pm, existingTransaction);
}
catch (JDOException ex) {
throw convertJdoAccessException(ex);
}
catch (RuntimeException ex) {
// callback code threw application exception
throw ex;
}
finally {
PersistenceManagerFactoryUtils.releasePersistenceManager(pm, getPersistenceManagerFactory());
}
}
/**
* Create a close-suppressing proxy for the given JDO PersistenceManager.
* Called by the execute
method.
* The proxy also prepares returned JDO Query objects.
* @param pm the JDO PersistenceManager to create a proxy for
* @return the PersistenceManager proxy, implementing all interfaces
* implemented by the passed-in PersistenceManager object (that is,
* also implementing all provider-specific extension interfaces)
* @see javax.jdo.PersistenceManager#close()
* @see #execute(JdoCallback, boolean)
* @see #prepareQuery
*/
protected PersistenceManager createPersistenceManagerProxy(PersistenceManager pm) {
Class[] ifcs = ClassUtils.getAllInterfacesForClass(pm.getClass(), getClass().getClassLoader());
return (PersistenceManager) Proxy.newProxyInstance(
pm.getClass().getClassLoader(), ifcs, new CloseSuppressingInvocationHandler(pm));
}
/**
* Post-process the given result object, which might be a Collection.
* Called by the execute
method.
*
Default implementation always returns the passed-in Object as-is.
* Subclasses might override this to automatically detach result
* collections or even single result objects.
* @param pm the current JDO PersistenceManager
* @param result the result object (might be a Collection)
* @param existingTransaction if executing within an existing transaction
* (within an existing JDO PersistenceManager that won't be closed immediately)
* @return the post-processed result object (can be simply be the passed-in object)
* @see #execute(JdoCallback, boolean)
*/
protected T postProcessResult(T result, PersistenceManager pm, boolean existingTransaction) {
return result;
}
//-------------------------------------------------------------------------
// Convenience methods for load, save, delete
//-------------------------------------------------------------------------
public Object getObjectById(final Object objectId) throws DataAccessException {
return execute(new JdoCallback