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 build on JDO 2.0 or higher, as of Spring 2.5.

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

Method Summary
`Object` `attachCopy(Object detachedEntity)` Deprecated. in favor of `makePersistent(Object)`. To be removed in Spring 3.0.
`Collection` `attachCopyAll(Collection detachedEntities)` Deprecated. in favor of `makePersistentAll(java.util.Collection)`. To be removed in Spring 3.0.
`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.
`Object` `makePersistent(Object entity)` Make the given transient instance persistent.
`Collection` `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

    Object makePersistent(Object entity)
                          throws DataAccessException

  Make the given transient instance persistent. Attach the given entity if the instance is detached.

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

### makePersistentAll

    Collection makePersistentAll(Collection entities)
                                 throws DataAccessException

  Make the given transient instances persistent. Attach the given entities if the instances are detached.

  Parameters:
    `entities` - the transient instances to make persistent
  Returns:
    the persistent instances
  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).

  Parameters:
    `entity` - the persistent instance to detach
  Returns:
    the corresponding detached instance
  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).

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

### attachCopy

    Object attachCopy(Object detachedEntity)

  Deprecated. in favor of `makePersistent(Object)`. To be removed in Spring 3.0.

  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.

  Note that as of JDO 2.0 final, this operation is equivalent to a `makePersistent` call, with the latter method returning the persistence instance.

  Parameters:
    `detachedEntity` - the detached instance to attach
  Returns:
    the corresponding persistent instance

### attachCopyAll

    Collection attachCopyAll(Collection detachedEntities)

  Deprecated. in favor of `makePersistentAll(java.util.Collection)`. To be removed in Spring 3.0.

  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.

  Note that as of JDO 2.0 final, this operation is equivalent to a `makePersistentAll` call, with the latter method returning the persistence instance.

  Parameters:
    `detachedEntities` - the detached instances to reattach
  Returns:
    the corresponding persistent instances

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

  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.

  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.

  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.

  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.

  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.

  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.

  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.

  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-2008 The Spring Framework.