toplinkoperations.java

spring的源代码

/*
 * Copyright 2002-2005 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 TopLinkTemplate. Not often used, but a useful option
 * to enhance testability, as it can easily be mocked or stubbed.
 *
 * <p>Provides TopLinkTemplate's data access methods that mirror various
 * TopLink Session/UnitOfWork methods. See the TopLink javadocs for
 * details on 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</code>
	 * @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</code>
	 * @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</code>)
	 * @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</code>)
	 * @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</code>)
	 * @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</code>)
	 * @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.