java.lang.Object | ||
↳ | org.springframework.orm.jdo.JdoAccessor | |
↳ | org.springframework.orm.jdo.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.
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.
[Expand]
Inherited Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
org.springframework.orm.jdo.JdoAccessor
|
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Create a new JdoTemplate instance.
| |||||||||||
Create a new JdoTemplate instance.
| |||||||||||
Create a new JdoTemplate instance.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Delete the given persistent instance.
| |||||||||||
Delete all given persistent instances.
| |||||||||||
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).
| |||||||||||
Detach copies of the given persistent instances from the current JDO transaction,
for use outside a JDO transaction (for example, as web form objects).
| |||||||||||
Remove the given object from the PersistenceManager cache.
| |||||||||||
Remove all given objects from the PersistenceManager cache.
| |||||||||||
Remove all objects from the PersistenceManager cache.
| |||||||||||
Execute the action specified by the given action object within a
PersistenceManager.
| |||||||||||
Execute the action specified by the given action object within a
PersistenceManager.
| |||||||||||
Execute the specified action assuming that the result object is a
Collection.
| |||||||||||
Find all persistent instances of the given class that match the given
JDOQL filter, using the given parameter declarations and parameter values.
| |||||||||||
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.
| |||||||||||
Find persistent instances through the given single-string JDOQL query.
| |||||||||||
Find persistent instances through the given single-string JDOQL query.
| |||||||||||
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.
| |||||||||||
Find all persistent instances of the given class.
| |||||||||||
Find persistent instances through the given query object
in the specified query language.
| |||||||||||
Find persistent instances through the given single-string JDOQL query.
| |||||||||||
Find all persistent instances of the given class that match the given
JDOQL filter.
| |||||||||||
Find all persistent instances of the given class that match the given
JDOQL filter, using the given parameter declarations and parameter values.
| |||||||||||
Find all persistent instances of the given class that match the given
JDOQL filter, with the given result ordering.
| |||||||||||
Find persistent instances through the given named query.
| |||||||||||
Find persistent instances through the given named query.
| |||||||||||
Find persistent instances through the given named query.
| |||||||||||
Flush all transactional modifications to the database.
| |||||||||||
Return the persistent instance of the given entity class
with the given id value, throwing an exception if not found.
| |||||||||||
Return the persistent instance with the given JDO object id,
throwing an exception if not found.
| |||||||||||
Return if a new PersistenceManager should be created if no thread-bound found.
| |||||||||||
Return whether to expose the native JDO PersistenceManager to JdoCallback
code, or rather a PersistenceManager proxy.
| |||||||||||
Make the given transient instance persistent.
| |||||||||||
Make the given transient instances persistent.
| |||||||||||
Prepare the given JDO query object.
| |||||||||||
Re-read the state of the given persistent instance.
| |||||||||||
Re-read the state of all given persistent instances.
| |||||||||||
Re-read the state of all persistent instances.
| |||||||||||
Set if a new PersistenceManager should be created when no transactional
PersistenceManager can be found for the current thread.
| |||||||||||
Set whether to expose the native JDO PersistenceManager to JdoCallback
code.
|
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Create a close-suppressing proxy for the given JDO PersistenceManager.
| |||||||||||
Post-process the given result object, which might be a Collection.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
org.springframework.orm.jdo.JdoAccessor
| |||||||||||
From class
java.lang.Object
| |||||||||||
From interface
org.springframework.beans.factory.InitializingBean
| |||||||||||
From interface
org.springframework.orm.jdo.JdoOperations
|
Create a new JdoTemplate instance.
Create a new JdoTemplate instance.
pmf | PersistenceManagerFactory to create PersistenceManagers |
---|
Create a new JdoTemplate instance.
pmf | PersistenceManagerFactory to create PersistenceManagers |
---|---|
allowCreate | if a non-transactional PersistenceManager should be created when no transactional PersistenceManager can be found for the current thread |
Delete the given persistent instance.
entity | the persistent instance to delete |
---|
DataAccessException |
---|
Delete all given persistent instances.
This can be combined with any of the find methods to delete by query in two lines of code.
entities | the persistent instances to delete |
---|
DataAccessException |
---|
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).
entity | the persistent instance to detach |
---|
Detach copies of the given persistent instances from the current JDO transaction, for use outside a JDO transaction (for example, as web form objects).
entities | the persistent instances to detach |
---|
Remove the given object from the PersistenceManager cache.
entity | the persistent instance to evict |
---|
DataAccessException |
---|
Remove all given objects from the PersistenceManager cache.
entities | the persistent instances to evict |
---|
DataAccessException |
---|
Remove all objects from the PersistenceManager cache.
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.
action | callback object that specifies the JDO action |
---|
null
DataAccessException |
---|
Execute the action specified by the given action object within a PersistenceManager.
action | callback object that specifies the JDO action |
---|---|
exposeNativePersistenceManager | whether to expose the native JDO persistence manager to callback code |
null
DataAccessException | in case of JDO errors |
---|
Execute the specified action assuming that the result object is a Collection. This is a convenience method for executing JDO queries within an action.
action | callback object that specifies the JDO action |
---|
null
DataAccessException |
---|
Find all persistent instances of the given class that match the given JDOQL filter, using the given parameter declarations and parameter values.
entityClass | a persistent class |
---|---|
filter | the JDOQL filter to match |
parameters | the JDOQL parameter declarations |
values | the corresponding parameter values |
DataAccessException |
---|
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.
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) |
DataAccessException |
---|
Find persistent instances through the given single-string JDOQL query.
queryString | the single-string JDOQL query |
---|
DataAccessException |
---|
Find persistent instances through the given single-string JDOQL query.
queryString | the single-string JDOQL query |
---|---|
values | a Map with parameter names as keys and parameter values |
DataAccessException |
---|
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.
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) |
DataAccessException |
---|
Find all persistent instances of the given class.
entityClass | a persistent class |
---|
DataAccessException |
---|
Find persistent instances through the given query object in the specified query language.
language | the query language (javax.jdo.Query#JDOQL
or javax.jdo.Query#SQL , for example) |
---|---|
queryObject | the query object for the specified language |
DataAccessException |
---|
Find persistent instances through the given single-string JDOQL query.
queryString | the single-string JDOQL query |
---|---|
values | the corresponding parameter values |
DataAccessException |
---|
Find all persistent instances of the given class that match the given JDOQL filter.
entityClass | a persistent class |
---|---|
filter | the JDOQL filter to match (or null if none) |
DataAccessException |
---|
Find all persistent instances of the given class that match the given JDOQL filter, using the given parameter declarations and parameter values.
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 |
DataAccessException |
---|
Find all persistent instances of the given class that match the given JDOQL filter, with the given result ordering.
entityClass | a persistent class |
---|---|
filter | the JDOQL filter to match (or null if none) |
ordering | the ordering of the result (or null if none) |
DataAccessException |
---|
Find persistent instances through the given named query.
entityClass | a persistent class |
---|---|
queryName | the name of the query |
values | the corresponding parameter values |
DataAccessException |
---|
Find persistent instances through the given named query.
entityClass | a persistent class |
---|---|
queryName | the name of the query |
values | a Map with parameter names as keys and parameter values |
DataAccessException |
---|
Find persistent instances through the given named query.
entityClass | a persistent class |
---|---|
queryName | the name of the query |
DataAccessException |
---|
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.
DataAccessException |
---|
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.
entityClass | a persistent class |
---|---|
idValue | an id value of the persistent instance |
DataAccessException |
---|
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.
objectId | a JDO object id of the persistent instance |
---|
DataAccessException |
---|
Return if a new PersistenceManager should be created if no thread-bound found.
Return whether to expose the native JDO PersistenceManager to JdoCallback code, or rather a PersistenceManager proxy.
Make the given transient instance persistent. Attach the given entity if the instance is detached.
entity | the transient instance to make persistent |
---|
DataAccessException |
---|
Make the given transient instances persistent. Attach the given entities if the instances are detached.
entities | the transient instances to make persistent |
---|
DataAccessException |
---|
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 provider-specific JDO PersistenceManager class anymore then.
query | the JDO query object |
---|
if the query could not be properly prepared | |
JDOException |
Re-read the state of the given persistent instance.
entity | the persistent instance to re-read |
---|
DataAccessException |
---|
Re-read the state of all given persistent instances.
entities | the persistent instances to re-read |
---|
DataAccessException |
---|
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.
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".
JdoCallback
prepareQuery(Query)
Create a close-suppressing proxy for the given JDO PersistenceManager.
Called by the execute
method.
The proxy also prepares returned JDO Query objects.
pm | the JDO PersistenceManager to create a proxy for |
---|
execute(JdoCallback, boolean)
prepareQuery(Query)
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.
result | the result object (might be a Collection) |
---|---|
pm | the current JDO PersistenceManager |
existingTransaction | if executing within an existing transaction (within an existing JDO PersistenceManager that won't be closed immediately) |