The Spring Framework

org.springframework.orm.jdo
Interface JdoOperations

All Known Implementing Classes:
JdoTemplate

public interface JdoOperations

Interface that specifies a basic set of JDO operations, implemented by JdoTemplate. Not often used, but a useful option to enhance testability, as it can easily be mocked or stubbed.

Defines JdoTemplate's data access methods that mirror various JDO PersistenceManager methods. Users are strongly encouraged to read the JDO PersistenceManager javadocs for details on the semantics of those methods.

Note that lazy loading will just work with an open JDO PersistenceManager, either within a managed transaction or within OpenPersistenceManagerInViewFilter/ OpenPersistenceManagerInViewInterceptor. Furthermore, some operations just make sense within transactions, for example: evict, evictAll, flush.

Updated to expose JDO 2.0 functionality, as of Spring 1.2: detachCopy, attachCopy, findByNamedQuery, etc. Those operations will by default only work on top of the standard JDO 2.0 API. Since Spring 1.2.2, the execution of those operations can also be adapted through the JdoDialect mechanism (for example, for vendor-specific pre-JDO2 methods).

Since:
1.1
Author:
Juergen Hoeller
See Also:
JdoTemplate, PersistenceManager, JdoTransactionManager, JdoDialect, OpenPersistenceManagerInViewFilter, OpenPersistenceManagerInViewInterceptor

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.
 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.
 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.
 void makePersistent(Object entity)
          Make the given transient instance persistent.
 void makePersistentAll(Collection entities)
          Make the given transient instances persistent.
 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.
 

Method Detail

execute

Object execute(JdoCallback action)
               throws 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.

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

Collection executeFind(JdoCallback action)
                       throws DataAccessException
Execute the specified action assuming that the result object is a Collection. This is a convenience method for executing JDO queries within an action.

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

getObjectById

Object getObjectById(Object objectId)
                     throws 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.

Parameters:
objectId - a JDO object id of the persistent instance
Returns:
the persistent instance
Throws:
ObjectRetrievalFailureException - if not found
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.getObjectById(Object, boolean)

getObjectById

Object getObjectById(Class entityClass,
                     Object idValue)
                     throws 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.

Parameters:
entityClass - a persistent class
idValue - an id value of the persistent instance
Returns:
the persistent instance
Throws:
ObjectRetrievalFailureException - if not found
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.getObjectById(Object, boolean), PersistenceManager.getObjectById(Class, Object)

evict

void evict(Object entity)
           throws DataAccessException
Remove the given object from the PersistenceManager cache.

Parameters:
entity - the persistent instance to evict
Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.evict(Object)

evictAll

void evictAll(Collection entities)
              throws DataAccessException
Remove all given objects from the PersistenceManager cache.

Parameters:
entities - the persistent instances to evict
Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.evictAll(java.util.Collection)

evictAll

void evictAll()
              throws DataAccessException
Remove all objects from the PersistenceManager cache.

Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.evictAll()

refresh

void refresh(Object entity)
             throws DataAccessException
Re-read the state of the given persistent instance.

Parameters:
entity - the persistent instance to re-read
Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.refresh(Object)

refreshAll

void refreshAll(Collection entities)
                throws DataAccessException
Re-read the state of all given persistent instances.

Parameters:
entities - the persistent instances to re-read
Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.refreshAll(java.util.Collection)

refreshAll

void refreshAll()
                throws DataAccessException
Re-read the state of all persistent instances.

Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.refreshAll()

makePersistent

void makePersistent(Object entity)
                    throws DataAccessException
Make the given transient instance persistent.

Parameters:
entity - the transient instance to make persistent
Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.makePersistent(Object)

makePersistentAll

void makePersistentAll(Collection entities)
                       throws DataAccessException
Make the given transient instances persistent.

Parameters:
entities - the transient instances to make persistent
Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.makePersistentAll(java.util.Collection)

deletePersistent

void deletePersistent(Object entity)
                      throws DataAccessException
Delete the given persistent instance.

Parameters:
entity - the persistent instance to delete
Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.deletePersistent(Object)

deletePersistentAll

void deletePersistentAll(Collection entities)
                         throws 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.

Parameters:
entities - the persistent instances to delete
Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.deletePersistentAll(java.util.Collection)

detachCopy

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).

Only available on JDO 2.0+ or through a vendor-specific JdoDialect.

Parameters:
entity - the persistent instance to detach
See Also:
PersistenceManager.detachCopy(Object)

detachCopyAll

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).

Only available on JDO 2.0+ or through a vendor-specific JdoDialect.

Parameters:
entities - the persistent instances to detach
See Also:
PersistenceManager.detachCopyAll(Collection)

attachCopy

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.

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.

Parameters:
detachedEntity - the detached instance to attach
Returns:
the corresponding persistent instance
See Also:
PersistenceManager.makePersistent(Object)

attachCopyAll

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.

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.

Parameters:
detachedEntities - the detached instances to reattach
Returns:
the corresponding persistent instances
See Also:
PersistenceManager.makePersistentAll(java.util.Collection)

flush

void flush()
           throws 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.

Only available on JDO 2.0+ or through a vendor-specific JdoDialect.

Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.flush(), JdoDialect.flush(javax.jdo.PersistenceManager)

find

Collection find(Class entityClass)
                throws DataAccessException
Find all persistent instances of the given class.

Parameters:
entityClass - a persistent class
Returns:
the persistent instances
Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.newQuery(Class)

find

Collection find(Class entityClass,
                String filter)
                throws DataAccessException
Find all persistent instances of the given class that match the given JDOQL filter.

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

Collection find(Class entityClass,
                String filter,
                String ordering)
                throws DataAccessException
Find all persistent instances of the given class that match the given JDOQL filter, with the given result ordering.

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

Collection find(Class entityClass,
                String filter,
                String parameters,
                Object[] values)
                throws DataAccessException
Find all persistent instances of the given class that match the given JDOQL filter, using the given parameter declarations and parameter values.

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

Collection find(Class entityClass,
                String filter,
                String parameters,
                Object[] values,
                String ordering)
                throws 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.

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

Collection find(Class entityClass,
                String filter,
                String parameters,
                Map values)
                throws DataAccessException
Find all persistent instances of the given class that match the given JDOQL filter, using the given parameter declarations and parameter values.

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

Collection find(Class entityClass,
                String filter,
                String parameters,
                Map values,
                String ordering)
                throws 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.

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)

find

Collection find(String language,
                Object queryObject)
                throws DataAccessException
Find persistent instances through the given query object in the specified query language.

Only available on JDO 2.0 and higher.

Parameters:
language - the query language (javax.jdo.Query#JDOQL or javax.jdo.Query#SQL, for example)
queryObject - the query object for the specified language
Returns:
the persistent instances
Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.newQuery(String, Object), Query.JDOQL, Query.SQL

find

Collection find(String queryString)
                throws DataAccessException
Find persistent instances through the given single-string JDOQL query.

Only available on JDO 2.0 and higher.

Parameters:
queryString - the single-string JDOQL query
Returns:
the persistent instances
Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.newQuery(String)

find

Collection find(String queryString,
                Object[] values)
                throws DataAccessException
Find persistent instances through the given single-string JDOQL query.

Only available on JDO 2.0 and higher.

Parameters:
queryString - the single-string JDOQL query
values - the corresponding parameter values
Returns:
the persistent instances
Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.newQuery(String)

find

Collection find(String queryString,
                Map values)
                throws DataAccessException
Find persistent instances through the given single-string JDOQL query.

Only available on JDO 2.0 and higher.

Parameters:
queryString - the single-string JDOQL query
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(String)

findByNamedQuery

Collection findByNamedQuery(Class entityClass,
                            String queryName)
                            throws DataAccessException
Find persistent instances through the given named query.

Only available on JDO 2.0+ or through a vendor-specific JdoDialect.

Parameters:
entityClass - a persistent class
queryName - the name of the query
Returns:
the persistent instances
Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.newNamedQuery(Class, String)

findByNamedQuery

Collection findByNamedQuery(Class entityClass,
                            String queryName,
                            Object[] values)
                            throws DataAccessException
Find persistent instances through the given named query.

Only available on JDO 2.0+ or through a vendor-specific JdoDialect.

Parameters:
entityClass - a persistent class
queryName - the name of the query
values - the corresponding parameter values
Returns:
the persistent instances
Throws:
DataAccessException - in case of JDO errors
See Also:
PersistenceManager.newNamedQuery(Class, String)

findByNamedQuery

Collection findByNamedQuery(Class entityClass,
                            String queryName,
                            Map values)
                            throws DataAccessException
Find persistent instances through the given named query.

Only available on JDO 2.0+ or through a vendor-specific JdoDialect.

Parameters:
entityClass - a persistent class
queryName - the name of the query
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.newNamedQuery(Class, String)

The Spring Framework

Copyright © 2002-2007 The Spring Framework.