|
The Spring Framework | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.springframework.orm.jdo.JdoAccessor org.springframework.orm.jdo.JdoTemplate
public class JdoTemplate
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 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.
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 to be JDO-aware. Setting such a special
PlatformTransactionManager is a configuration issue, without introducing
code dependencies: For example, switching to JTA is just a matter of
Spring configuration (use JtaTransactionManager instead) and JDO provider
configuration, neither affecting application code.
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 is compatible with both JDO 1.0 and JDO 2.0,
as far as possible. It uses reflection to adapt to the actual API present
on the class path (concretely: for the newObjectIdInstance
,
makePersistent
and makePersistentAll
methods).
Make sure that the JDO API jar on your class path matches the one that
your JDO provider has been compiled against!
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 | |
---|---|
Object |
attachCopy(Object detachedEntity)
Reattach the given detached instance (for example, a web form object) with the current JDO transaction, merging its changes into the current persistence instance that represents the corresponding entity. |
Collection |
attachCopyAll(Collection detachedEntities)
Reattach the given detached instances (for example, web form objects) with the current JDO transaction, merging their changes into the current persistence instances that represent the corresponding entities. |
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. |
Object |
detachCopy(Object entity)
Detach a copy of the given persistent instance from the current JDO transaction, for use outside a JDO transaction (for example, as web form object). |
Collection |
detachCopyAll(Collection entities)
Detach copies of the given persistent instances from the current JDO transaction, for use outside a JDO transaction (for example, as web form objects). |
void |
evict(Object entity)
Remove the given object from the PersistenceManager cache. |
void |
evictAll()
Remove all objects from the PersistenceManager cache. |
void |
evictAll(Collection entities)
Remove all given 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)
Find all persistent instances of the given class. |
Collection |
find(Class entityClass,
String filter)
Find all persistent instances of the given class that match the given JDOQL filter. |
Collection |
find(Class entityClass,
String filter,
String ordering)
Find 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)
Find 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)
Find 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)
Find 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)
Find 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(String queryString)
Find persistent instances through the given single-string JDOQL query. |
Collection |
find(String queryString,
Map values)
Find persistent instances through the given single-string JDOQL query. |
Collection |
find(String language,
Object queryObject)
Find persistent instances through the given query object in the specified query language. |
Collection |
find(String queryString,
Object[] values)
Find persistent instances through the given single-string JDOQL query. |
Collection |
findByNamedQuery(Class entityClass,
String queryName)
Find persistent instances through the given named query. |
Collection |
findByNamedQuery(Class entityClass,
String queryName,
Map values)
Find persistent instances through the given named query. |
Collection |
findByNamedQuery(Class entityClass,
String queryName,
Object[] values)
Find persistent instances through the given named query. |
void |
flush()
Flush all transactional modifications to the database. |
Object |
getObjectById(Class entityClass,
Object idValue)
Return the persistent instance of the given entity class with the given id value, throwing an exception if not found. |
Object |
getObjectById(Object 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 |
makePersistentAll(Collection entities)
Make the given transient instances persistent. |
protected Object |
postProcessResult(Object result,
javax.jdo.PersistenceManager pm,
boolean existingTransaction)
Post-process the given result object, which might be a Collection. |
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 |
refreshAll(Collection entities)
Re-read the state of all given persistent instances. |
void |
setAllowCreate(boolean allowCreate)
Set if a new PersistenceManager should be created when no transactional PersistenceManager can be found for the current thread. |
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 |
---|
public JdoTemplate()
public JdoTemplate(javax.jdo.PersistenceManagerFactory pmf)
pmf
- PersistenceManagerFactory to create PersistenceManagerspublic JdoTemplate(javax.jdo.PersistenceManagerFactory pmf, boolean allowCreate)
pmf
- PersistenceManagerFactory to create PersistenceManagersallowCreate
- if a non-transactional PersistenceManager should be created
when no transactional PersistenceManager can be found for the current threadMethod Detail |
---|
public void setAllowCreate(boolean allowCreate)
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.
public boolean isAllowCreate()
public void setExposeNativePersistenceManager(boolean exposeNativePersistenceManager)
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 the JDO 1.0 API, for JDO 2.0 previews and other provider-specific functionality, the exposed proxy implements all interfaces implemented by the original PersistenceManager. If this is not sufficient, turn this flag to "true".
JdoCallback
,
PersistenceManager
,
prepareQuery(javax.jdo.Query)
public boolean isExposeNativePersistenceManager()
public Object execute(JdoCallback action) throws DataAccessException
JdoOperations
Note: Callback code is not supposed to handle transactions itself! Use an appropriate transaction manager like JdoTransactionManager.
execute
in interface JdoOperations
action
- callback object that specifies the JDO action
null
DataAccessException
- in case of JDO errorsJdoTransactionManager
,
org.springframework.dao
,
org.springframework.transaction
,
PersistenceManager
public Collection executeFind(JdoCallback action) throws DataAccessException
JdoOperations
executeFind
in interface JdoOperations
action
- callback object that specifies the JDO action
null
DataAccessException
- in case of JDO errorspublic Object execute(JdoCallback action, boolean exposeNativePersistenceManager) throws DataAccessException
action
- callback object that specifies the JDO actionexposeNativePersistenceManager
- whether to expose the native
JDO persistence manager to callback code
null
DataAccessException
- in case of JDO errorsprotected javax.jdo.PersistenceManager createPersistenceManagerProxy(javax.jdo.PersistenceManager pm)
execute
method.
The proxy also prepares returned JDO Query objects.
pm
- the JDO PersistenceManager to create a proxy for
PersistenceManager.close()
,
execute(JdoCallback, boolean)
,
prepareQuery(javax.jdo.Query)
protected Object postProcessResult(Object result, javax.jdo.PersistenceManager pm, boolean existingTransaction)
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.
pm
- the current JDO PersistenceManagerresult
- the result object (might be a Collection)existingTransaction
- if executing within an existing transaction
(within an existing JDO PersistenceManager that won't be closed immediately)
execute(JdoCallback, boolean)
public Object getObjectById(Object objectId) throws DataAccessException
JdoOperations
A JDO object id identifies both the persistent class and the id within the namespace of that class.
getObjectById
in interface JdoOperations
objectId
- a JDO object id of the persistent instance
ObjectRetrievalFailureException
- if not found
DataAccessException
- in case of JDO errorsPersistenceManager.getObjectById(Object, boolean)
public Object getObjectById(Class entityClass, Object idValue) throws DataAccessException
JdoOperations
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.
getObjectById
in interface JdoOperations
entityClass
- a persistent classidValue
- an id value of the persistent instance
ObjectRetrievalFailureException
- if not found
DataAccessException
- in case of JDO errorsPersistenceManager.getObjectById(Object, boolean)
,
PersistenceManager.getObjectById(Class, Object)
public void evict(Object entity) throws DataAccessException
JdoOperations
evict
in interface JdoOperations
entity
- the persistent instance to evict
DataAccessException
- in case of JDO errorsPersistenceManager.evict(Object)
public void evictAll(Collection entities) throws DataAccessException
JdoOperations
evictAll
in interface JdoOperations
entities
- the persistent instances to evict
DataAccessException
- in case of JDO errorsPersistenceManager.evictAll(java.util.Collection)
public void evictAll() throws DataAccessException
JdoOperations
evictAll
in interface JdoOperations
DataAccessException
- in case of JDO errorsPersistenceManager.evictAll()
public void refresh(Object entity) throws DataAccessException
JdoOperations
refresh
in interface JdoOperations
entity
- the persistent instance to re-read
DataAccessException
- in case of JDO errorsPersistenceManager.refresh(Object)
public void refreshAll(Collection entities) throws DataAccessException
JdoOperations
refreshAll
in interface JdoOperations
entities
- the persistent instances to re-read
DataAccessException
- in case of JDO errorsPersistenceManager.refreshAll(java.util.Collection)
public void refreshAll() throws DataAccessException
JdoOperations
refreshAll
in interface JdoOperations
DataAccessException
- in case of JDO errorsPersistenceManager.refreshAll()
public void makePersistent(Object entity) throws DataAccessException
JdoOperations
makePersistent
in interface JdoOperations
entity
- the transient instance to make persistent
DataAccessException
- in case of JDO errorsPersistenceManager.makePersistent(Object)
public void makePersistentAll(Collection entities) throws DataAccessException
JdoOperations
makePersistentAll
in interface JdoOperations
entities
- the transient instances to make persistent
DataAccessException
- in case of JDO errorsPersistenceManager.makePersistentAll(java.util.Collection)
public void deletePersistent(Object entity) throws DataAccessException
JdoOperations
deletePersistent
in interface JdoOperations
entity
- the persistent instance to delete
DataAccessException
- in case of JDO errorsPersistenceManager.deletePersistent(Object)
public void deletePersistentAll(Collection entities) throws DataAccessException
JdoOperations
This can be combined with any of the find methods to delete by query in two lines of code.
deletePersistentAll
in interface JdoOperations
entities
- the persistent instances to delete
DataAccessException
- in case of JDO errorsPersistenceManager.deletePersistentAll(java.util.Collection)
public Object detachCopy(Object entity)
JdoOperations
Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
detachCopy
in interface JdoOperations
entity
- the persistent instance to detachPersistenceManager.detachCopy(Object)
public Collection detachCopyAll(Collection entities)
JdoOperations
Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
detachCopyAll
in interface JdoOperations
entities
- the persistent instances to detachPersistenceManager.detachCopyAll(Collection)
public Object attachCopy(Object detachedEntity)
JdoOperations
Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
Note that as of JDO 2.0 final, this operation is equivalent to a
makePersistent
call. This dedicated reattach operation
now solely serves as distinction point for custom JdoDialects.
It is still recommended to call this operation for enhanced adaptability.
attachCopy
in interface JdoOperations
detachedEntity
- the detached instance to attach
PersistenceManager.makePersistent(Object)
public Collection attachCopyAll(Collection detachedEntities)
JdoOperations
Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
Note that as of JDO 2.0 final, this operation is equivalent to a
makePersistentAll
call. This dedicated reattach operation
now solely serves as distinction point for custom JdoDialects.
It is still recommended to call this operation for enhanced adaptability.
attachCopyAll
in interface JdoOperations
detachedEntities
- the detached instances to reattach
PersistenceManager.makePersistentAll(java.util.Collection)
public void flush() throws DataAccessException
JdoOperations
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.
Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
flush
in interface JdoOperations
DataAccessException
- in case of JDO errorsPersistenceManager.flush()
,
JdoDialect.flush(javax.jdo.PersistenceManager)
public Collection find(Class entityClass) throws DataAccessException
JdoOperations
find
in interface JdoOperations
entityClass
- a persistent class
DataAccessException
- in case of JDO errorsPersistenceManager.newQuery(Class)
public Collection find(Class entityClass, String filter) throws DataAccessException
JdoOperations
find
in interface JdoOperations
entityClass
- a persistent classfilter
- the JDOQL filter to match (or null
if none)
DataAccessException
- in case of JDO errorsPersistenceManager.newQuery(Class, String)
public Collection find(Class entityClass, String filter, String ordering) throws DataAccessException
JdoOperations
find
in interface JdoOperations
entityClass
- a persistent classfilter
- the JDOQL filter to match (or null
if none)ordering
- the ordering of the result (or null
if none)
DataAccessException
- in case of JDO errorsPersistenceManager.newQuery(Class, String)
,
Query.setOrdering(java.lang.String)
public Collection find(Class entityClass, String filter, String parameters, Object[] values) throws DataAccessException
JdoOperations
find
in interface JdoOperations
entityClass
- a persistent classfilter
- the JDOQL filter to matchparameters
- the JDOQL parameter declarationsvalues
- the corresponding parameter values
DataAccessException
- in case of JDO errorsPersistenceManager.newQuery(Class, String)
,
Query.declareParameters(java.lang.String)
,
Query.executeWithArray(java.lang.Object[])
public Collection find(Class entityClass, String filter, String parameters, Object[] values, String ordering) throws DataAccessException
JdoOperations
find
in interface JdoOperations
entityClass
- a persistent classfilter
- the JDOQL filter to matchparameters
- the JDOQL parameter declarationsvalues
- the corresponding parameter valuesordering
- the ordering of the result (or null
if none)
DataAccessException
- in case of JDO errorsPersistenceManager.newQuery(Class, String)
,
Query.declareParameters(java.lang.String)
,
Query.executeWithArray(java.lang.Object[])
,
Query.setOrdering(java.lang.String)
public Collection find(Class entityClass, String filter, String parameters, Map values) throws DataAccessException
JdoOperations
find
in interface JdoOperations
entityClass
- a persistent classfilter
- the JDOQL filter to matchparameters
- the JDOQL parameter declarationsvalues
- a Map with parameter names as keys and parameter values
DataAccessException
- in case of JDO errorsPersistenceManager.newQuery(Class, String)
,
Query.declareParameters(java.lang.String)
,
Query.executeWithMap(java.util.Map)
public Collection find(Class entityClass, String filter, String parameters, Map values, String ordering) throws DataAccessException
JdoOperations
find
in interface JdoOperations
entityClass
- a persistent classfilter
- the JDOQL filter to matchparameters
- the JDOQL parameter declarationsvalues
- a Map with parameter names as keys and parameter valuesordering
- the ordering of the result (or null
if none)
DataAccessException
- in case of JDO errorsPersistenceManager.newQuery(Class, String)
,
Query.declareParameters(java.lang.String)
,
Query.executeWithMap(java.util.Map)
,
Query.setOrdering(java.lang.String)
public Collection find(String language, Object queryObject) throws DataAccessException
JdoOperations
Only available on JDO 2.0 and higher.
find
in interface JdoOperations
language
- the query language (javax.jdo.Query#JDOQL
or javax.jdo.Query#SQL
, for example)queryObject
- the query object for the specified language
DataAccessException
- in case of JDO errorsPersistenceManager.newQuery(String, Object)
,
Query.JDOQL
,
Query.SQL
public Collection find(String queryString) throws DataAccessException
JdoOperations
Only available on JDO 2.0 and higher.
find
in interface JdoOperations
queryString
- the single-string JDOQL query
DataAccessException
- in case of JDO errorsPersistenceManager.newQuery(String)
public Collection find(String queryString, Object[] values) throws DataAccessException
JdoOperations
Only available on JDO 2.0 and higher.
find
in interface JdoOperations
queryString
- the single-string JDOQL queryvalues
- the corresponding parameter values
DataAccessException
- in case of JDO errorsPersistenceManager.newQuery(String)
public Collection find(String queryString, Map values) throws DataAccessException
JdoOperations
Only available on JDO 2.0 and higher.
find
in interface JdoOperations
queryString
- the single-string JDOQL queryvalues
- a Map with parameter names as keys and parameter values
DataAccessException
- in case of JDO errorsPersistenceManager.newQuery(String)
public Collection findByNamedQuery(Class entityClass, String queryName) throws DataAccessException
JdoOperations
Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
findByNamedQuery
in interface JdoOperations
entityClass
- a persistent classqueryName
- the name of the query
DataAccessException
- in case of JDO errorsPersistenceManager.newNamedQuery(Class, String)
public Collection findByNamedQuery(Class entityClass, String queryName, Object[] values) throws DataAccessException
JdoOperations
Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
findByNamedQuery
in interface JdoOperations
entityClass
- a persistent classqueryName
- the name of the queryvalues
- the corresponding parameter values
DataAccessException
- in case of JDO errorsPersistenceManager.newNamedQuery(Class, String)
public Collection findByNamedQuery(Class entityClass, String queryName, Map values) throws DataAccessException
JdoOperations
Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
findByNamedQuery
in interface JdoOperations
entityClass
- a persistent classqueryName
- the name of the queryvalues
- a Map with parameter names as keys and parameter values
DataAccessException
- in case of JDO errorsPersistenceManager.newNamedQuery(Class, String)
public void prepareQuery(javax.jdo.Query query) throws javax.jdo.JDOException
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 provider-specific JDO PersistenceManager class anymore then.
query
- the JDO query object
javax.jdo.JDOException
- if the query could not be properly preparedJdoCallback.doInJdo(javax.jdo.PersistenceManager)
,
PersistenceManagerFactoryUtils.applyTransactionTimeout(javax.jdo.Query, javax.jdo.PersistenceManagerFactory, org.springframework.orm.jdo.JdoDialect)
,
setExposeNativePersistenceManager(boolean)
|
The Spring Framework | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |