Spring Framework example source code file (TopLinkOperations.java)

This example Spring Framework source code file (TopLinkOperations.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Spring Framework tags/keywords

call, dataaccessexception, dataaccessexception, expression, expression, list, list, object, object, objectcopyingpolicy, string, toplinkoperations, util

The Spring Framework TopLinkOperations.java source code

/*
 * Copyright 2002-2006 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.orm.toplink;

import java.util.Collection;
import java.util.List;

import oracle.toplink.expressions.Expression;
import oracle.toplink.queryframework.Call;
import oracle.toplink.queryframework.DatabaseQuery;
import oracle.toplink.sessions.ObjectCopyingPolicy;

import org.springframework.dao.DataAccessException;

/**
 * Interface that specifies a basic set of TopLink operations,
 * implemented by {@link TopLinkTemplate}. Not often used, but a useful
 * option to enhance testability, as it can easily be mocked or stubbed.
 *
 * <p>Defines TopLinkTemplate's data access methods that
 * mirror various TopLink {@link oracle.toplink.sessions.Session} /
 * {@link oracle.toplink.sessions.UnitOfWork} methods. Users are
 * strongly encouraged to read the TopLink javadocs for details
 * on the semantics of those methods.
 *
 * @author Juergen Hoeller
 * @since 1.2
 */
public interface TopLinkOperations {

	/**
	 * 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.
	 * <p>Note: Callback code is not supposed to handle transactions itself!
	 * Use an appropriate transaction manager like TopLinkTransactionManager.
	 * @param action callback object that specifies the TopLink action
	 * @return a result object returned by the action, or <code>null
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see TopLinkTransactionManager
	 * @see org.springframework.dao
	 * @see org.springframework.transaction
	 * @see oracle.toplink.sessions.Session
	 */
	Object execute(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.
	 * @param action callback object that specifies the TopLink action
	 * @return a Collection result returned by the action, or <code>null
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 */
	List executeFind(TopLinkCallback action) throws DataAccessException;


	//-------------------------------------------------------------------------
	// Convenience methods for executing generic queries
	//-------------------------------------------------------------------------

	/**
	 * Execute a given named query with the given arguments.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param entityClass the entity class that has the named query descriptor
	 * @param queryName the name of the query
	 * @return the result object or list of result objects for the query
	 * (can be cast to the entity class or Collection/List, respectively)
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#executeQuery(String, Class)
	 */
	Object executeNamedQuery(Class entityClass, String queryName) throws DataAccessException;

	/**
	 * Execute a given named query with the given arguments.
	 * @param entityClass the entity class that has the named query descriptor
	 * @param queryName the name of the query
	 * @param 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)
	 * @return the result object or list of result objects for the query
	 * (can be cast to the entity class or Collection/List, respectively)
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#executeQuery(String, Class)
	 */
	Object executeNamedQuery(Class entityClass, String queryName, boolean enforceReadOnly)
			throws DataAccessException;

	/**
	 * Execute a given named query with the given arguments.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param entityClass the entity class that has the named query descriptor
	 * @param queryName the name of the query
	 * @param args the arguments for the query (can be <code>null)
	 * @return the result object or list of result objects for the query
	 * (can be cast to the entity class or Collection/List, respectively)
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#executeQuery(String, Class, java.util.Vector)
	 */
	Object executeNamedQuery(Class entityClass, String queryName, Object[] args) throws DataAccessException;

	/**
	 * Execute a given named query with the given arguments.
	 * @param entityClass the entity class that has the named query descriptor
	 * @param queryName the name of the query
	 * @param args the arguments for the query (can be <code>null)
	 * @param 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)
	 * @return the result object or list of result objects for the query
	 * (can be cast to the entity class or Collection/List, respectively)
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#executeQuery(String, Class, java.util.Vector)
	 */
	Object executeNamedQuery(Class entityClass, String queryName, Object[] args, boolean enforceReadOnly)
			throws DataAccessException;

	/**
	 * Execute the given query object with the given arguments.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param query the query object to execute (for example,
	 * a ReadObjectQuery or ReadAllQuery instance)
	 * @return the result object or list of result objects for the query
	 * (can be cast to the entity class or Collection/List, respectively)
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#executeQuery(oracle.toplink.queryframework.DatabaseQuery)
	 */
	Object executeQuery(DatabaseQuery query) throws DataAccessException;

	/**
	 * Execute the given query object with the given arguments.
	 * @param query the query object to execute (for example,
	 * a ReadObjectQuery or ReadAllQuery instance)
	 * @param 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)
	 * @return the result object or list of result objects for the query
	 * (can be cast to the entity class or Collection/List, respectively)
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#executeQuery(oracle.toplink.queryframework.DatabaseQuery)
	 */
	Object executeQuery(DatabaseQuery query, boolean enforceReadOnly) throws DataAccessException;

	/**
	 * Execute the given query object with the given arguments.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param query the query object to execute (for example,
	 * a ReadObjectQuery or ReadAllQuery instance)
	 * @param args the arguments for the query (can be <code>null)
	 * @return the result object or list of result objects for the query
	 * (can be cast to the entity class or Collection/List, respectively)
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#executeQuery(oracle.toplink.queryframework.DatabaseQuery, java.util.Vector)
	 */
	Object executeQuery(DatabaseQuery query, Object[] args) throws DataAccessException;

	/**
	 * Execute the given query object with the given arguments.
	 * @param query the query object to execute (for example,
	 * a ReadObjectQuery or ReadAllQuery instance)
	 * @param args the arguments for the query (can be <code>null)
	 * @param 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)
	 * @return the result object or list of result objects for the query
	 * (can be cast to the entity class or Collection/List, respectively)
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#executeQuery(oracle.toplink.queryframework.DatabaseQuery, java.util.Vector)
	 */
	Object executeQuery(DatabaseQuery query, Object[] args, boolean enforceReadOnly)
			throws DataAccessException;


	//-------------------------------------------------------------------------
	// Convenience methods for reading a specific set of objects
	//-------------------------------------------------------------------------

	/**
	 * Read all entity instances of the given class.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param entityClass the entity class
	 * @return the list of entity instances
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#readAllObjects(Class)
	 */
	List readAll(Class entityClass) throws DataAccessException;

	/**
	 * Read all entity instances of the given class.
	 * @param entityClass the entity class
	 * @param 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)
	 * @return the list of entity instances
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#readAllObjects(Class)
	 */
	List readAll(Class entityClass, boolean enforceReadOnly) throws DataAccessException;

	/**
	 * Read all entity instances of the given class that match the given expression.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param entityClass the entity class
	 * @param expression the TopLink expression to match,
	 * usually built through the TopLink ExpressionBuilder
	 * @return the list of matching entity instances
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
	 * @see oracle.toplink.expressions.ExpressionBuilder
	 */
	List readAll(Class entityClass, Expression expression) throws DataAccessException;

	/**
	 * Read all entity instances of the given class that match the given expression.
	 * @param entityClass the entity class
	 * @param expression the TopLink expression to match,
	 * usually built through the TopLink ExpressionBuilder
	 * @param 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)
	 * @return the list of matching entity instances
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
	 * @see oracle.toplink.expressions.ExpressionBuilder
	 */
	List readAll(Class entityClass, Expression expression, boolean enforceReadOnly)
			throws DataAccessException;

	/**
	 * Read all entity instances of the given class, as returned by the given call.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param entityClass the entity class
	 * @param call the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
	 * @return the list of matching entity instances
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.queryframework.Call)
	 * @see oracle.toplink.queryframework.SQLCall
	 * @see oracle.toplink.queryframework.EJBQLCall
	 */
	List readAll(Class entityClass, Call call) throws DataAccessException;

	/**
	 * Read all entity instances of the given class, as returned by the given call.
	 * @param entityClass the entity class
	 * @param call the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
	 * @param 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)
	 * @return the list of matching entity instances
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
	 * @see oracle.toplink.queryframework.SQLCall
	 * @see oracle.toplink.queryframework.EJBQLCall
	 */
	List readAll(Class entityClass, Call call, boolean enforceReadOnly) throws DataAccessException;

	/**
	 * Read an entity instance of the given class that matches the given expression.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param entityClass the entity class
	 * @param expression the TopLink expression to match,
	 * usually built through the TopLink ExpressionBuilder
	 * @return the matching entity instance, or <code>null if none found
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
	 * @see oracle.toplink.expressions.ExpressionBuilder
	 */
	Object read(Class entityClass, Expression expression) throws DataAccessException;

	/**
	 * Read an entity instance of the given class that matches the given expression.
	 * @param entityClass the entity class
	 * @param expression the TopLink expression to match,
	 * usually built through the TopLink ExpressionBuilder
	 * @param 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)
	 * @return a matching entity instance, or <code>null if none found
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
	 * @see oracle.toplink.expressions.ExpressionBuilder
	 */
	Object read(Class entityClass, Expression expression, boolean enforceReadOnly)
			throws DataAccessException;

	/**
	 * Read an entity instance of the given class, as returned by the given call.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param entityClass the entity class
	 * @param call the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
	 * @return a matching entity instance, or <code>null if none found
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.queryframework.Call)
	 * @see oracle.toplink.queryframework.SQLCall
	 * @see oracle.toplink.queryframework.EJBQLCall
	 */
	Object read(Class entityClass, Call call) throws DataAccessException;

	/**
	 * Read an entity instance of the given class, as returned by the given call.
	 * @param entityClass the entity class
	 * @param call the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
	 * @param 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)
	 * @return a matching entity instance, or <code>null if none found
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
	 * @see oracle.toplink.queryframework.SQLCall
	 * @see oracle.toplink.queryframework.EJBQLCall
	 */
	Object read(Class entityClass, Call call, boolean enforceReadOnly)
			throws DataAccessException;


	//-------------------------------------------------------------------------
	// Convenience methods for reading an individual object by id
	//-------------------------------------------------------------------------

	/**
	 * Read the entity instance of the given class with the given id,
	 * throwing an exception if not found.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param entityClass the entity class
	 * @param id the id of the desired object
	 * @return the entity instance
	 * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
	 */
	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.
	 * @param entityClass the entity class
	 * @param id the id of the desired object
	 * @return the entity instance
	 * @param 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)
	 * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
	 */
	Object readById(Class entityClass, Object id, boolean enforceReadOnly) throws DataAccessException;

	/**
	 * Read the entity instance of the given class with the given composite id,
	 * throwing an exception if not found.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param entityClass the entity class
	 * @param keys the composite id elements of the desired object
	 * @return the entity instance
	 * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
	 */
	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.
	 * @param entityClass the entity class
	 * @param keys the composite id elements of the desired object
	 * @param 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)
	 * @return the entity instance
	 * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
	 */
	Object readById(Class entityClass, Object[] keys, 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.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param entityClass the entity class
	 * @param id the id of the desired object
	 * @return a copy of the entity instance
	 * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
	 * @see oracle.toplink.sessions.Session#copyObject(Object)
	 */
	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.
	 * @param entityClass the entity class
	 * @param id the id of the desired object
	 * @param 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)
	 * @return a copy of the entity instance
	 * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
	 * @see oracle.toplink.sessions.Session#copyObject(Object)
	 */
	Object readAndCopy(Class entityClass, Object id, 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.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param entityClass the entity class
	 * @param keys the composite id elements of the desired object
	 * @return a copy of the entity instance
	 * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
	 * @see oracle.toplink.sessions.Session#copyObject(Object)
	 */
	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.
	 * @param entityClass the entity class
	 * @param keys the composite id elements of the desired object
	 * @param 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)
	 * @return a copy of the entity instance
	 * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
	 * @see oracle.toplink.sessions.Session#copyObject(Object)
	 */
	Object readAndCopy(Class entityClass, Object[] keys, boolean enforceReadOnly) throws DataAccessException;


	//-------------------------------------------------------------------------
	// Convenience methods for copying and refreshing objects
	//-------------------------------------------------------------------------

	/**
	 * Create a detached copy of the given entity object,
	 * using TopLink's default ObjectCopyingPolicy.
	 * @param entity the entity object to copy
	 * @return the copy of the entity object
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#copyObject(Object)
	 */
	Object copy(Object entity) throws DataAccessException;

	/**
	 * Create a detached copy of the given entity object.
	 * @param entity the entity object to copy
	 * @param copyingPolicy the TopLink ObjectCopyingPolicy to apply
	 * @return the copy of the entity object
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#copyObject(Object, oracle.toplink.sessions.ObjectCopyingPolicy)
	 */
	Object copy(Object entity, ObjectCopyingPolicy copyingPolicy) throws DataAccessException;

	/**
	 * Create detached copies of all given entity objects,
	 * using TopLink's default ObjectCopyingPolicy.
	 * @param entities the entity objects to copy
	 * @return the copies of the entity objects
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#copyObject(Object)
	 */
	List copyAll(Collection entities) throws DataAccessException;

	/**
	 * Create detached copies of all given entity objects.
	 * @param entities the entity objects to copy
	 * @param copyingPolicy the TopLink ObjectCopyingPolicy to apply
	 * @return the copies of the entity objects
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#copyObject(Object)
	 */
	List copyAll(Collection entities, ObjectCopyingPolicy copyingPolicy) throws DataAccessException;

	/**
	 * Refresh the given entity object, returning the refreshed object.
	 * <p>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.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param entity the entity object to refresh
	 * @return the refreshed version of the entity object
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#refreshObject(Object)
	 */
	Object refresh(Object entity) throws DataAccessException;

	/**
	 * Refresh the given entity object, returning the refreshed object.
	 * <p>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.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param entity the entity object to refresh
	 * @param 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)
	 * @return the refreshed version of the entity object
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#refreshObject(Object)
	 */
	Object refresh(Object entity, boolean enforceReadOnly) throws DataAccessException;

	/**
	 * Refresh the given entity objects, returning the corresponding refreshed objects.
	 * <p>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.
	 * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
	 * non-read-only transaction, and read-only objects else.
	 * @param entities the entity objects to refresh
	 * @return the refreshed versions of the entity objects
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#refreshObject(Object)
	 */
	List refreshAll(Collection entities) throws DataAccessException;

	/**
	 * Refresh the given entity objects, returning the corresponding refreshed objects.
	 * <p>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.
	 * @param entities the entity objects to refresh
	 * @param 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)
	 * @return the refreshed versions of the entity objects
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.Session#refreshObject(Object)
	 */
	List refreshAll(Collection entities, boolean enforceReadOnly) throws DataAccessException;


	//-------------------------------------------------------------------------
	// Convenience methods for persisting and deleting objects
	//-------------------------------------------------------------------------

	/**
	 * Register the given (new or existing) entity with the current UnitOfWork.
	 * <p>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 <code>registerNew
	 * or <code>registerExisting method.
	 * <b>Do not edit the passed-in object any further afterwards.
	 * @param entity the entity to register
	 * @return the registered clone of the original object,
	 * which needs to be used for further editing
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.UnitOfWork#registerObject(Object)
	 * @see #registerNew(Object)
	 * @see #registerExisting(Object)
	 */
	Object register(Object entity);

	/**
	 * Register all given entities with the current UnitOfWork.
	 * <b>Do not edit the passed-in objects any further afterwards.
	 * @param entities the entities to register
	 * @return the registered clones of the original objects,
	 * which need to be used for further editing
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.UnitOfWork#registerAllObjects(java.util.Collection)
	 */
	List registerAll(Collection entities);

	/**
	 * Register the given new entity with the current UnitOfWork.
	 * The passed-in object can be edited further afterwards.
	 * @param entity the new entity to register
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.UnitOfWork#registerNewObject(Object)
	 */
	void registerNew(Object entity);

	/**
	 * Register the given existing entity with the current UnitOfWork.
	 * <b>Do not edit the passed-in object any further afterwards.
	 * @param entity the existing entity to register
	 * @return the registered clone of the original object,
	 * which needs to be used for further editing
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.UnitOfWork#registerExistingObject(Object)
	 */
	Object registerExisting(Object entity);

	/**
	 * Reassociate the given entity copy with the current UnitOfWork,
	 * using simple merging.
	 * <p>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.
	 * @param entity the updated copy to merge
	 * @return the updated, registered persistent instance
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.UnitOfWork#mergeClone(Object)
	 */
	Object merge(Object entity) throws DataAccessException;

	/**
	 * Reassociate the given entity copy with the current UnitOfWork,
	 * using deep merging of all contained entities.
	 * <p>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.
	 * @param entity the updated copy to merge
	 * @return the updated, registered persistent instance
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.UnitOfWork#deepMergeClone(Object)
	 */
	Object deepMerge(Object entity) throws DataAccessException;

	/**
	 * Reassociate the given entity copy with the current UnitOfWork,
	 * using shallow merging of the entity instance.
	 * <p>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.
	 * @param entity the updated copy to merge
	 * @return the updated, registered persistent instance
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.UnitOfWork#shallowMergeClone(Object)
	 */
	Object shallowMerge(Object entity) throws DataAccessException;

	/**
	 * Reassociate the given entity copy with the current UnitOfWork,
	 * using merging with all references from this clone.
	 * <p>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.
	 * @param entity the updated copy to merge
	 * @return the updated, registered persistent instance
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.UnitOfWork#mergeCloneWithReferences(Object)
	 */
	Object mergeWithReferences(Object entity) throws DataAccessException;

	/**
	 * Delete the given entity.
	 * @param entity the entity to delete
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.UnitOfWork#deleteObject(Object)
	 */
	void delete(Object entity) throws DataAccessException;

	/**
	 * Delete all given entities.
	 * @param entities the entities to delete
	 * @throws org.springframework.dao.DataAccessException in case of TopLink errors
	 * @see oracle.toplink.sessions.UnitOfWork#deleteAllObjects(java.util.Collection)
	 */
	void deleteAll(Collection entities) throws DataAccessException;

}