The Spring Framework

## org.springframework.orm.toplink
Interface TopLinkOperations

All Known Implementing Classes:
  TopLinkTemplate

    public interface TopLinkOperations

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

Defines `TopLinkTemplate`'s data access methods that mirror various TopLink `Session` / `UnitOfWork` methods. Users are strongly encouraged to read the TopLink javadocs for details on the semantics of those methods.

Since:
  1.2
Author:
  Juergen Hoeller

Method Summary
`Object` `copy(Object entity)` Create a detached copy of the given entity object, using TopLink's default ObjectCopyingPolicy.
`Object` `copy(Object entity, oracle.toplink.sessions.ObjectCopyingPolicy copyingPolicy)` Create a detached copy of the given entity object.
`List` `copyAll(Collection entities)` Create detached copies of all given entity objects, using TopLink's default ObjectCopyingPolicy.
`List` `copyAll(Collection entities, oracle.toplink.sessions.ObjectCopyingPolicy copyingPolicy)` Create detached copies of all given entity objects.
`Object` `deepMerge(Object entity)` Reassociate the given entity copy with the current UnitOfWork, using deep merging of all contained entities.
`void` `delete(Object entity)` Delete the given entity.
`void` `deleteAll(Collection entities)` Delete all given entities.
`Object` `execute(TopLinkCallback action)` Execute the action specified by the given action object within a TopLink Session.
`List` `executeFind(TopLinkCallback action)` Execute the specified action assuming that the result object is a Collection.
`Object` `executeNamedQuery(Class entityClass, String queryName)` Execute a given named query with the given arguments.
`Object` `executeNamedQuery(Class entityClass, String queryName, boolean enforceReadOnly)` Execute a given named query with the given arguments.
`Object` `executeNamedQuery(Class entityClass, String queryName, Object[] args)` Execute a given named query with the given arguments.
`Object` `executeNamedQuery(Class entityClass, String queryName, Object[] args, boolean enforceReadOnly)` Execute a given named query with the given arguments.
`Object` `executeQuery(oracle.toplink.queryframework.DatabaseQuery query)` Execute the given query object with the given arguments.
`Object` `executeQuery(oracle.toplink.queryframework.DatabaseQuery query, boolean enforceReadOnly)` Execute the given query object with the given arguments.
`Object` `executeQuery(oracle.toplink.queryframework.DatabaseQuery query, Object[] args)` Execute the given query object with the given arguments.
`Object` `executeQuery(oracle.toplink.queryframework.DatabaseQuery query, Object[] args, boolean enforceReadOnly)` Execute the given query object with the given arguments.
`Object` `merge(Object entity)` Reassociate the given entity copy with the current UnitOfWork, using simple merging.
`Object` `mergeWithReferences(Object entity)` Reassociate the given entity copy with the current UnitOfWork, using merging with all references from this clone.
`Object` `read(Class entityClass, oracle.toplink.queryframework.Call call)` Read an entity instance of the given class, as returned by the given call.
`Object` `read(Class entityClass, oracle.toplink.queryframework.Call call, boolean enforceReadOnly)` Read an entity instance of the given class, as returned by the given call.
`Object` `read(Class entityClass, oracle.toplink.expressions.Expression expression)` Read an entity instance of the given class that matches the given expression.
`Object` `read(Class entityClass, oracle.toplink.expressions.Expression expression, boolean enforceReadOnly)` Read an entity instance of the given class that matches the given expression.
`List` `readAll(Class entityClass)` Read all entity instances of the given class.
`List` `readAll(Class entityClass, boolean enforceReadOnly)` Read all entity instances of the given class.
`List` `readAll(Class entityClass, oracle.toplink.queryframework.Call call)` Read all entity instances of the given class, as returned by the given call.
`List` `readAll(Class entityClass, oracle.toplink.queryframework.Call call, boolean enforceReadOnly)` Read all entity instances of the given class, as returned by the given call.
`List` `readAll(Class entityClass, oracle.toplink.expressions.Expression expression)` Read all entity instances of the given class that match the given expression.
`List` `readAll(Class entityClass, oracle.toplink.expressions.Expression expression, boolean enforceReadOnly)` Read all entity instances of the given class that match the given expression.
`Object` `readAndCopy(Class entityClass, Object id)` Read the entity instance of the given class with the given id, throwing an exception if not found.
`Object` `readAndCopy(Class entityClass, Object[] keys)` Read the entity instance of the given class with the given composite id, throwing an exception if not found.
`Object` `readAndCopy(Class entityClass, Object[] keys, boolean enforceReadOnly)` Read the entity instance of the given class with the given composite id, throwing an exception if not found.
`Object` `readAndCopy(Class entityClass, Object id, boolean enforceReadOnly)` Read the entity instance of the given class with the given id, throwing an exception if not found.
`Object` `readById(Class entityClass, Object id)` Read the entity instance of the given class with the given id, throwing an exception if not found.
`Object` `readById(Class entityClass, Object[] keys)` Read the entity instance of the given class with the given composite id, throwing an exception if not found.
`Object` `readById(Class entityClass, Object[] keys, boolean enforceReadOnly)` Read the entity instance of the given class with the given composite id, throwing an exception if not found.
`Object` `readById(Class entityClass, Object id, boolean enforceReadOnly)` Read the entity instance of the given class with the given id, throwing an exception if not found.
`Object` `refresh(Object entity)` Refresh the given entity object, returning the refreshed object.
`Object` `refresh(Object entity, boolean enforceReadOnly)` Refresh the given entity object, returning the refreshed object.
`List` `refreshAll(Collection entities)` Refresh the given entity objects, returning the corresponding refreshed objects.
`List` `refreshAll(Collection entities, boolean enforceReadOnly)` Refresh the given entity objects, returning the corresponding refreshed objects.
`Object` `register(Object entity)` Register the given (new or existing) entity with the current UnitOfWork.
`List` `registerAll(Collection entities)` Register all given entities with the current UnitOfWork.
`Object` `registerExisting(Object entity)` Register the given existing entity with the current UnitOfWork.
`void` `registerNew(Object entity)` Register the given new entity with the current UnitOfWork.
`Object` `shallowMerge(Object entity)` Reassociate the given entity copy with the current UnitOfWork, using shallow merging of the entity instance.

Method Detail

### execute

    Object execute(TopLinkCallback action)
                   throws DataAccessException

  Execute the action specified by the given action object within a TopLink Session. Application exceptions thrown by the action object get propagated to the caller (can only be unchecked). TopLink 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 TopLinkTransactionManager.

  Parameters:
    `action` - callback object that specifies the TopLink action
  Returns:
    a result object returned by the action, or `null`
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `TopLinkTransactionManager`, `org.springframework.dao`, `org.springframework.transaction`, `Session`

### executeFind

    List executeFind(TopLinkCallback action)
                     throws DataAccessException

  Execute the specified action assuming that the result object is a Collection. This is a convenience method for executing TopLink queries within an action.

  Parameters:
    `action` - callback object that specifies the TopLink action
  Returns:
    a Collection result returned by the action, or `null`
  Throws:
    `DataAccessException` - in case of TopLink errors

### executeNamedQuery

    Object executeNamedQuery(Class entityClass,
                             String queryName)
                             throws DataAccessException

  Execute a given named query with the given arguments.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `entityClass` - the entity class that has the named query descriptor
    `queryName` - the name of the query
  Returns:
    the result object or list of result objects for the query (can be cast to the entity class or Collection/List, respectively)
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.executeQuery(String, Class)`

### executeNamedQuery

    Object executeNamedQuery(Class entityClass,
                             String queryName,
                             boolean enforceReadOnly)
                             throws DataAccessException

  Execute a given named query with the given arguments.

  Parameters:
    `entityClass` - the entity class that has the named query descriptor
    `queryName` - the name of the query
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    the result object or list of result objects for the query (can be cast to the entity class or Collection/List, respectively)
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.executeQuery(String, Class)`

### executeNamedQuery

    Object executeNamedQuery(Class entityClass,
                             String queryName,
                             Object[] args)
                             throws DataAccessException

  Execute a given named query with the given arguments.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `entityClass` - the entity class that has the named query descriptor
    `queryName` - the name of the query
    `args` - the arguments for the query (can be `null`)
  Returns:
    the result object or list of result objects for the query (can be cast to the entity class or Collection/List, respectively)
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.executeQuery(String, Class, java.util.Vector)`

### executeNamedQuery

    Object executeNamedQuery(Class entityClass,
                             String queryName,
                             Object[] args,
                             boolean enforceReadOnly)
                             throws DataAccessException

  Execute a given named query with the given arguments.

  Parameters:
    `entityClass` - the entity class that has the named query descriptor
    `queryName` - the name of the query
    `args` - the arguments for the query (can be `null`)
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    the result object or list of result objects for the query (can be cast to the entity class or Collection/List, respectively)
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.executeQuery(String, Class, java.util.Vector)`

### executeQuery

    Object executeQuery(oracle.toplink.queryframework.DatabaseQuery query)
                        throws DataAccessException

  Execute the given query object with the given arguments.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `query` - the query object to execute (for example, a ReadObjectQuery or ReadAllQuery instance)
  Returns:
    the result object or list of result objects for the query (can be cast to the entity class or Collection/List, respectively)
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.executeQuery(oracle.toplink.queryframework.DatabaseQuery)`

### executeQuery

    Object executeQuery(oracle.toplink.queryframework.DatabaseQuery query,
                        boolean enforceReadOnly)
                        throws DataAccessException

  Execute the given query object with the given arguments.

  Parameters:
    `query` - the query object to execute (for example, a ReadObjectQuery or ReadAllQuery instance)
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    the result object or list of result objects for the query (can be cast to the entity class or Collection/List, respectively)
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.executeQuery(oracle.toplink.queryframework.DatabaseQuery)`

### executeQuery

    Object executeQuery(oracle.toplink.queryframework.DatabaseQuery query,
                        Object[] args)
                        throws DataAccessException

  Execute the given query object with the given arguments.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `query` - the query object to execute (for example, a ReadObjectQuery or ReadAllQuery instance)
    `args` - the arguments for the query (can be `null`)
  Returns:
    the result object or list of result objects for the query (can be cast to the entity class or Collection/List, respectively)
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.executeQuery(oracle.toplink.queryframework.DatabaseQuery, java.util.Vector)`

### executeQuery

    Object executeQuery(oracle.toplink.queryframework.DatabaseQuery query,
                        Object[] args,
                        boolean enforceReadOnly)
                        throws DataAccessException

  Execute the given query object with the given arguments.

  Parameters:
    `query` - the query object to execute (for example, a ReadObjectQuery or ReadAllQuery instance)
    `args` - the arguments for the query (can be `null`)
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    the result object or list of result objects for the query (can be cast to the entity class or Collection/List, respectively)
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.executeQuery(oracle.toplink.queryframework.DatabaseQuery, java.util.Vector)`

### readAll

    List readAll(Class entityClass)
                 throws DataAccessException

  Read all entity instances of the given class.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `entityClass` - the entity class
  Returns:
    the list of entity instances
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.readAllObjects(Class)`

### readAll

    List readAll(Class entityClass,
                 boolean enforceReadOnly)
                 throws DataAccessException

  Read all entity instances of the given class.

  Parameters:
    `entityClass` - the entity class
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    the list of entity instances
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.readAllObjects(Class)`

### readAll

    List readAll(Class entityClass,
                 oracle.toplink.expressions.Expression expression)
                 throws DataAccessException

  Read all entity instances of the given class that match the given expression.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `entityClass` - the entity class
    `expression` - the TopLink expression to match, usually built through the TopLink ExpressionBuilder
  Returns:
    the list of matching entity instances
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.readAllObjects(Class, oracle.toplink.expressions.Expression)`, `ExpressionBuilder`

### readAll

    List readAll(Class entityClass,
                 oracle.toplink.expressions.Expression expression,
                 boolean enforceReadOnly)
                 throws DataAccessException

  Read all entity instances of the given class that match the given expression.

  Parameters:
    `entityClass` - the entity class
    `expression` - the TopLink expression to match, usually built through the TopLink ExpressionBuilder
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    the list of matching entity instances
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.readAllObjects(Class, oracle.toplink.expressions.Expression)`, `ExpressionBuilder`

### readAll

    List readAll(Class entityClass,
                 oracle.toplink.queryframework.Call call)
                 throws DataAccessException

  Read all entity instances of the given class, as returned by the given call.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `entityClass` - the entity class
    `call` - the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
  Returns:
    the list of matching entity instances
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.readAllObjects(Class, oracle.toplink.queryframework.Call)`, `oracle.toplink.queryframework.SQLCall`, `oracle.toplink.queryframework.EJBQLCall`

### readAll

    List readAll(Class entityClass,
                 oracle.toplink.queryframework.Call call,
                 boolean enforceReadOnly)
                 throws DataAccessException

  Read all entity instances of the given class, as returned by the given call.

  Parameters:
    `entityClass` - the entity class
    `call` - the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    the list of matching entity instances
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.readAllObjects(Class, oracle.toplink.expressions.Expression)`, `oracle.toplink.queryframework.SQLCall`, `oracle.toplink.queryframework.EJBQLCall`

### read

    Object read(Class entityClass,
                oracle.toplink.expressions.Expression expression)
                throws DataAccessException

  Read an entity instance of the given class that matches the given expression.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `entityClass` - the entity class
    `expression` - the TopLink expression to match, usually built through the TopLink ExpressionBuilder
  Returns:
    the matching entity instance, or `null` if none found
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.readAllObjects(Class, oracle.toplink.expressions.Expression)`, `ExpressionBuilder`

### read

    Object read(Class entityClass,
                oracle.toplink.expressions.Expression expression,
                boolean enforceReadOnly)
                throws DataAccessException

  Read an entity instance of the given class that matches the given expression.

  Parameters:
    `entityClass` - the entity class
    `expression` - the TopLink expression to match, usually built through the TopLink ExpressionBuilder
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    a matching entity instance, or `null` if none found
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.readAllObjects(Class, oracle.toplink.expressions.Expression)`, `ExpressionBuilder`

### read

    Object read(Class entityClass,
                oracle.toplink.queryframework.Call call)
                throws DataAccessException

  Read an entity instance of the given class, as returned by the given call.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `entityClass` - the entity class
    `call` - the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
  Returns:
    a matching entity instance, or `null` if none found
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.readAllObjects(Class, oracle.toplink.queryframework.Call)`, `oracle.toplink.queryframework.SQLCall`, `oracle.toplink.queryframework.EJBQLCall`

### read

    Object read(Class entityClass,
                oracle.toplink.queryframework.Call call,
                boolean enforceReadOnly)
                throws DataAccessException

  Read an entity instance of the given class, as returned by the given call.

  Parameters:
    `entityClass` - the entity class
    `call` - the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    a matching entity instance, or `null` if none found
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.readAllObjects(Class, oracle.toplink.expressions.Expression)`, `oracle.toplink.queryframework.SQLCall`, `oracle.toplink.queryframework.EJBQLCall`

### readById

    Object readById(Class entityClass,
                    Object id)
                    throws DataAccessException

  Read the entity instance of the given class with the given id, throwing an exception if not found.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `entityClass` - the entity class
    `id` - the id of the desired object
  Returns:
    the entity instance
  Throws:
    `ObjectRetrievalFailureException` - if not found
    `DataAccessException` - in case of TopLink errors
  See Also:
    `ReadObjectQuery.setSelectionKey(java.util.Vector)`

### readById

    Object readById(Class entityClass,
                    Object id,
                    boolean enforceReadOnly)
                    throws DataAccessException

  Read the entity instance of the given class with the given id, throwing an exception if not found.

  Parameters:
    `entityClass` - the entity class
    `id` - the id of the desired object
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    the entity instance
  Throws:
    `ObjectRetrievalFailureException` - if not found
    `DataAccessException` - in case of TopLink errors
  See Also:
    `ReadObjectQuery.setSelectionKey(java.util.Vector)`

### readById

    Object readById(Class entityClass,
                    Object[] keys)
                    throws DataAccessException

  Read the entity instance of the given class with the given composite id, throwing an exception if not found.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `entityClass` - the entity class
    `keys` - the composite id elements of the desired object
  Returns:
    the entity instance
  Throws:
    `ObjectRetrievalFailureException` - if not found
    `DataAccessException` - in case of TopLink errors
  See Also:
    `ReadObjectQuery.setSelectionKey(java.util.Vector)`

### readById

    Object readById(Class entityClass,
                    Object[] keys,
                    boolean enforceReadOnly)
                    throws DataAccessException

  Read the entity instance of the given class with the given composite id, throwing an exception if not found.

  Parameters:
    `entityClass` - the entity class
    `keys` - the composite id elements of the desired object
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    the entity instance
  Throws:
    `ObjectRetrievalFailureException` - if not found
    `DataAccessException` - in case of TopLink errors
  See Also:
    `ReadObjectQuery.setSelectionKey(java.util.Vector)`

### readAndCopy

    Object readAndCopy(Class entityClass,
                       Object id)
                       throws DataAccessException

  Read the entity instance of the given class with the given id, throwing an exception if not found. A detached copy of the entity object will be returned, allowing for modifications outside the current transaction, with the changes to be merged into a later transaction.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `entityClass` - the entity class
    `id` - the id of the desired object
  Returns:
    a copy of the entity instance
  Throws:
    `ObjectRetrievalFailureException` - if not found
    `DataAccessException` - in case of TopLink errors
  See Also:
    `ReadObjectQuery.setSelectionKey(java.util.Vector)`, `Session.copyObject(Object)`

### readAndCopy

    Object readAndCopy(Class entityClass,
                       Object id,
                       boolean enforceReadOnly)
                       throws DataAccessException

  Read the entity instance of the given class with the given id, throwing an exception if not found. A detached copy of the entity object will be returned, allowing for modifications outside the current transaction, with the changes to be merged into a later transaction.

  Parameters:
    `entityClass` - the entity class
    `id` - the id of the desired object
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    a copy of the entity instance
  Throws:
    `ObjectRetrievalFailureException` - if not found
    `DataAccessException` - in case of TopLink errors
  See Also:
    `ReadObjectQuery.setSelectionKey(java.util.Vector)`, `Session.copyObject(Object)`

### readAndCopy

    Object readAndCopy(Class entityClass,
                       Object[] keys)
                       throws DataAccessException

  Read the entity instance of the given class with the given composite id, throwing an exception if not found. A detached copy of the entity object will be returned, allowing for modifications outside the current transaction, with the changes to be merged into a later transaction.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `entityClass` - the entity class
    `keys` - the composite id elements of the desired object
  Returns:
    a copy of the entity instance
  Throws:
    `ObjectRetrievalFailureException` - if not found
    `DataAccessException` - in case of TopLink errors
  See Also:
    `ReadObjectQuery.setSelectionKey(java.util.Vector)`, `Session.copyObject(Object)`

### readAndCopy

    Object readAndCopy(Class entityClass,
                       Object[] keys,
                       boolean enforceReadOnly)
                       throws DataAccessException

  Read the entity instance of the given class with the given composite id, throwing an exception if not found. A detached copy of the entity object will be returned, allowing for modifications outside the current transaction, with the changes to be merged into a later transaction.

  Parameters:
    `entityClass` - the entity class
    `keys` - the composite id elements of the desired object
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    a copy of the entity instance
  Throws:
    `ObjectRetrievalFailureException` - if not found
    `DataAccessException` - in case of TopLink errors
  See Also:
    `ReadObjectQuery.setSelectionKey(java.util.Vector)`, `Session.copyObject(Object)`

### copy

    Object copy(Object entity)
                throws DataAccessException

  Create a detached copy of the given entity object, using TopLink's default ObjectCopyingPolicy.

  Parameters:
    `entity` - the entity object to copy
  Returns:
    the copy of the entity object
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.copyObject(Object)`

### copy

    Object copy(Object entity,
                oracle.toplink.sessions.ObjectCopyingPolicy copyingPolicy)
                throws DataAccessException

  Create a detached copy of the given entity object.

  Parameters:
    `entity` - the entity object to copy
    `copyingPolicy` - the TopLink ObjectCopyingPolicy to apply
  Returns:
    the copy of the entity object
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.copyObject(Object, oracle.toplink.sessions.ObjectCopyingPolicy)`

### copyAll

    List copyAll(Collection entities)
                 throws DataAccessException

  Create detached copies of all given entity objects, using TopLink's default ObjectCopyingPolicy.

  Parameters:
    `entities` - the entity objects to copy
  Returns:
    the copies of the entity objects
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.copyObject(Object)`

### copyAll

    List copyAll(Collection entities,
                 oracle.toplink.sessions.ObjectCopyingPolicy copyingPolicy)
                 throws DataAccessException

  Create detached copies of all given entity objects.

  Parameters:
    `entities` - the entity objects to copy
    `copyingPolicy` - the TopLink ObjectCopyingPolicy to apply
  Returns:
    the copies of the entity objects
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.copyObject(Object)`

### refresh

    Object refresh(Object entity)
                   throws DataAccessException

  Refresh the given entity object, returning the refreshed object.

  The returned object will only be different from the passed-in object if the passed-in object is not the currently registered version of the corresponding entity.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `entity` - the entity object to refresh
  Returns:
    the refreshed version of the entity object
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.refreshObject(Object)`

### refresh

    Object refresh(Object entity,
                   boolean enforceReadOnly)
                   throws DataAccessException

  Refresh the given entity object, returning the refreshed object.

  The returned object will only be different from the passed-in object if the passed-in object is not the currently registered version of the corresponding entity.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `entity` - the entity object to refresh
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    the refreshed version of the entity object
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.refreshObject(Object)`

### refreshAll

    List refreshAll(Collection entities)
                    throws DataAccessException

  Refresh the given entity objects, returning the corresponding refreshed objects.

  A returned object will only be different from the corresponding passed-in object if the passed-in object is not the currently registered version of the corresponding entity.

  Retrieves read-write objects from the TopLink UnitOfWork in case of a non-read-only transaction, and read-only objects else.

  Parameters:
    `entities` - the entity objects to refresh
  Returns:
    the refreshed versions of the entity objects
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.refreshObject(Object)`

### refreshAll

    List refreshAll(Collection entities,
                    boolean enforceReadOnly)
                    throws DataAccessException

  Refresh the given entity objects, returning the corresponding refreshed objects.

  A returned object will only be different from the corresponding passed-in object if the passed-in object is not the currently registered version of the corresponding entity.

  Parameters:
    `entities` - the entity objects to refresh
    `enforceReadOnly` - whether to always retrieve read-only objects from the plain TopLink Session (else, read-write objects will be retrieved from the TopLink UnitOfWork in case of a non-read-only transaction)
  Returns:
    the refreshed versions of the entity objects
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `Session.refreshObject(Object)`

### register

    Object register(Object entity)

  Register the given (new or existing) entity with the current UnitOfWork.

  The entity will be checked for existence, according to TopLink's configured existence checking policy. To avoid the (potentially costly) existence check, consider using the specific `registerNew` or `registerExisting` method. Do not edit the passed-in object any further afterwards.

  Parameters:
    `entity` - the entity to register
  Returns:
    the registered clone of the original object, which needs to be used for further editing
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `UnitOfWork.registerObject(Object)`, `registerNew(Object)`, `registerExisting(Object)`

### registerAll

    List registerAll(Collection entities)

  Register all given entities with the current UnitOfWork. Do not edit the passed-in objects any further afterwards.

  Parameters:
    `entities` - the entities to register
  Returns:
    the registered clones of the original objects, which need to be used for further editing
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `UnitOfWork.registerAllObjects(java.util.Collection)`

### registerNew

    void registerNew(Object entity)

  Register the given new entity with the current UnitOfWork. The passed-in object can be edited further afterwards.

  Parameters:
    `entity` - the new entity to register
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `UnitOfWork.registerNewObject(Object)`

### registerExisting

    Object registerExisting(Object entity)

  Register the given existing entity with the current UnitOfWork. Do not edit the passed-in object any further afterwards.

  Parameters:
    `entity` - the existing entity to register
  Returns:
    the registered clone of the original object, which needs to be used for further editing
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `UnitOfWork.registerExistingObject(Object)`

### merge

    Object merge(Object entity)
                 throws DataAccessException

  Reassociate the given entity copy with the current UnitOfWork, using simple merging.

  The given object will not be reassociated itself: instead, the state will be copied onto the persistent object with the same identifier. In case of a new entity, merge will copy to a registered object as well, but will also update the identifier of the passed-in object.

  Parameters:
    `entity` - the updated copy to merge
  Returns:
    the updated, registered persistent instance
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `UnitOfWork.mergeClone(Object)`

### deepMerge

    Object deepMerge(Object entity)
                     throws DataAccessException

  Reassociate the given entity copy with the current UnitOfWork, using deep merging of all contained entities.

  The given object will not be reassociated itself: instead, the state will be copied onto the persistent object with the same identifier. In case of a new entity, merge will register a copy as well, but will also update the identifier of the passed-in object.

  Parameters:
    `entity` - the updated copy to merge
  Returns:
    the updated, registered persistent instance
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `UnitOfWork.deepMergeClone(Object)`

### shallowMerge

    Object shallowMerge(Object entity)
                        throws DataAccessException

  Reassociate the given entity copy with the current UnitOfWork, using shallow merging of the entity instance.

  The given object will not be reassociated itself: instead, the state will be copied onto the persistent object with the same identifier. In case of a new entity, merge will register a copy as well, but will also update the identifier of the passed-in object.

  Parameters:
    `entity` - the updated copy to merge
  Returns:
    the updated, registered persistent instance
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `UnitOfWork.shallowMergeClone(Object)`

### mergeWithReferences

    Object mergeWithReferences(Object entity)
                               throws DataAccessException

  Reassociate the given entity copy with the current UnitOfWork, using merging with all references from this clone.

  The given object will not be reassociated itself: instead, the state will be copied onto the persistent object with the same identifier. In case of a new entity, merge will register a copy as well, but will also update the identifier of the passed-in object.

  Parameters:
    `entity` - the updated copy to merge
  Returns:
    the updated, registered persistent instance
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `UnitOfWork.mergeCloneWithReferences(Object)`

### delete

    void delete(Object entity)
                throws DataAccessException

  Delete the given entity.

  Parameters:
    `entity` - the entity to delete
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `UnitOfWork.deleteObject(Object)`

### deleteAll

    void deleteAll(Collection entities)
                   throws DataAccessException

  Delete all given entities.

  Parameters:
    `entities` - the entities to delete
  Throws:
    `DataAccessException` - in case of TopLink errors
  See Also:
    `UnitOfWork.deleteAllObjects(java.util.Collection)`

The Spring Framework

Copyright © 2002-2008 The Spring Framework.