/*
 * Copyright 2002-2007 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.jdo;

import java.util.Collection;
import java.util.Map;

import org.springframework.dao.DataAccessException;

/**
 * Interface that specifies a basic set of JDO operations,
 * implemented by {@link JdoTemplate}. Not often used, but a useful
 * option to enhance testability, as it can easily be mocked or stubbed.
 *
 * <p>Defines <code>JdoTemplate</code>'s data access methods that mirror
 * various JDO {@link javax.jdo.PersistenceManager} methods. Users are
 * strongly encouraged to read the JDO <code>PersistenceManager</code>
 * javadocs for details on the semantics of those methods.
 *
 * <p>Note that lazy loading will just work with an open JDO
 * <code>PersistenceManager</code>, either within a managed transaction or within
 * {@link org.springframework.orm.jdo.support.OpenPersistenceManagerInViewFilter}/
 * {@link org.springframework.orm.jdo.support.OpenPersistenceManagerInViewInterceptor}.
 * Furthermore, some operations just make sense within transactions,
 * for example: <code>evict</code>, <code>evictAll</code>, <code>flush</code>.
 *
 * <p>Updated to build on JDO 2.0 or higher, as of Spring 2.5.
 *
 * @author Juergen Hoeller
 * @since 1.1
 * @see JdoTemplate
 * @see javax.jdo.PersistenceManager
 * @see JdoTransactionManager
 * @see JdoDialect
 * @see org.springframework.orm.jdo.support.OpenPersistenceManagerInViewFilter
 * @see org.springframework.orm.jdo.support.OpenPersistenceManagerInViewInterceptor
 */
public interface JdoOperations {

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


	//-------------------------------------------------------------------------
	// Convenience methods for load, save, delete
	//-------------------------------------------------------------------------

	/**
	 * Return the persistent instance with the given JDO object id,
	 * throwing an exception if not found.
	 * <p>A JDO object id identifies both the persistent class and the id
	 * within the namespace of that class.
	 * @param objectId a JDO object id of the persistent instance
	 * @return the persistent instance
	 * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#getObjectById(Object, boolean)
	 */
	Object getObjectById(Object objectId) throws DataAccessException;

	/**
	 * Return the persistent instance of the given entity class
	 * with the given id value, throwing an exception if not found.
	 * <p>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.
	 * <p>Usually, the passed-in value will have originated from the primary
	 * key field of a persistent object that uses JDO's application identity.
	 * @param entityClass a persistent class
	 * @param idValue an id value of the persistent instance
	 * @return the persistent instance
	 * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#getObjectById(Object, boolean)
	 * @see javax.jdo.PersistenceManager#getObjectById(Class, Object)
	 */
	Object getObjectById(Class entityClass, Object idValue) throws DataAccessException;

	/**
	 * Remove the given object from the PersistenceManager cache.
	 * @param entity the persistent instance to evict
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#evict(Object)
	 */
	void evict(Object entity) throws DataAccessException;

	/**
	 * Remove all given objects from the PersistenceManager cache.
	 * @param entities the persistent instances to evict
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#evictAll(java.util.Collection)
	 */
	void evictAll(Collection entities) throws DataAccessException;

	/**
	 * Remove all objects from the PersistenceManager cache.
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#evictAll()
	 */
	void evictAll() throws DataAccessException;

	/**
	 * Re-read the state of the given persistent instance.
	 * @param entity the persistent instance to re-read
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#refresh(Object)
	 */
	void refresh(Object entity) throws DataAccessException;

	/**
	 * Re-read the state of all given persistent instances.
	 * @param entities the persistent instances to re-read
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#refreshAll(java.util.Collection)
	 */
	void refreshAll(Collection entities) throws DataAccessException;

	/**
	 * Re-read the state of all persistent instances.
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#refreshAll()
	 */
	void refreshAll() throws DataAccessException;

	/**
	 * Make the given transient instance persistent.
	 * Attach the given entity if the instance is detached.
	 * @param entity the transient instance to make persistent
	 * @return the persistent instance
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#makePersistent(Object)
	 */
	Object makePersistent(Object entity) throws DataAccessException;

	/**
	 * Make the given transient instances persistent.
	 * Attach the given entities if the instances are detached.
	 * @param entities the transient instances to make persistent
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#makePersistentAll(java.util.Collection)
	 */
	Collection makePersistentAll(Collection entities) throws DataAccessException;

	/**
	 * Delete the given persistent instance.
	 * @param entity the persistent instance to delete
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#deletePersistent(Object)
	 */
	void deletePersistent(Object entity) throws DataAccessException;

	/**
	 * Delete all given persistent instances.
	 * <p>This can be combined with any of the find methods to delete by query
	 * in two lines of code.
	 * @param entities the persistent instances to delete
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#deletePersistentAll(java.util.Collection)
	 */
	void deletePersistentAll(Collection entities) throws DataAccessException;

	/**
	 * 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).
	 * @param entity the persistent instance to detach
	 * @return the corresponding detached instance
	 * @see javax.jdo.PersistenceManager#detachCopy(Object)
	 */
	Object detachCopy(Object entity);

	/**
	 * Detach copies of the given persistent instances from the current JDO transaction,
	 * for use outside a JDO transaction (for example, as web form objects).
	 * @param entities the persistent instances to detach
	 * @return the corresponding detached instances
	 * @see javax.jdo.PersistenceManager#detachCopyAll(Collection)
	 */
	Collection detachCopyAll(Collection entities);

	/**
	 * 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.
	 * <p>Note that as of JDO 2.0 final, this operation is equivalent to a
	 * <code>makePersistent</code> call, with the latter method returning the
	 * persistence instance.
	 * @param detachedEntity the detached instance to attach
	 * @return the corresponding persistent instance
	 * @deprecated in favor of {@link #makePersistent(Object)}.
	 * To be removed in Spring 3.0.
	 */
	Object attachCopy(Object detachedEntity);

	/**
	 * 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.
	 * <p>Note that as of JDO 2.0 final, this operation is equivalent to a
	 * <code>makePersistentAll</code> call, with the latter method returning the
	 * persistence instance.
	 * @param detachedEntities the detached instances to reattach
	 * @return the corresponding persistent instances
	 * @deprecated in favor of {@link #makePersistentAll(java.util.Collection)}.
	 * To be removed in Spring 3.0.
	 */
	Collection attachCopyAll(Collection detachedEntities);

	/**
	 * Flush all transactional modifications to the database.
	 * <p>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 org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#flush()
	 * @see JdoDialect#flush(javax.jdo.PersistenceManager)
	 */
	void flush() throws DataAccessException;


	//-------------------------------------------------------------------------
	// Convenience finder methods
	//-------------------------------------------------------------------------

	/**
	 * Find all persistent instances of the given class.
	 * @param entityClass a persistent class
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#newQuery(Class)
	 */
	Collection find(Class entityClass) throws DataAccessException;

	/**
	 * Find all persistent instances of the given class that match the given
	 * JDOQL filter.
	 * @param entityClass a persistent class
	 * @param filter the JDOQL filter to match (or <code>null</code> if none)
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#newQuery(Class, String)
	 */
	Collection find(Class entityClass, String filter) throws DataAccessException;

	/**
	 * Find all persistent instances of the given class that match the given
	 * JDOQL filter, with the given result ordering.
	 * @param entityClass a persistent class
	 * @param filter the JDOQL filter to match (or <code>null</code> if none)
	 * @param ordering the ordering of the result (or <code>null</code> if none)
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#newQuery(Class, String)
	 * @see javax.jdo.Query#setOrdering
	 */
	Collection find(Class entityClass, String filter, 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.
	 * @param entityClass a persistent class
	 * @param filter the JDOQL filter to match
	 * @param parameters the JDOQL parameter declarations
	 * @param values the corresponding parameter values
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#newQuery(Class, String)
	 * @see javax.jdo.Query#declareParameters
	 * @see javax.jdo.Query#executeWithArray
	 */
	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,
	 * with the given result ordering.
	 * @param entityClass a persistent class
	 * @param filter the JDOQL filter to match
	 * @param parameters the JDOQL parameter declarations
	 * @param values the corresponding parameter values
	 * @param ordering the ordering of the result (or <code>null</code> if none)
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#newQuery(Class, String)
	 * @see javax.jdo.Query#declareParameters
	 * @see javax.jdo.Query#executeWithArray
	 * @see javax.jdo.Query#setOrdering
	 */
	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.
	 * @param entityClass a persistent class
	 * @param filter the JDOQL filter to match
	 * @param parameters the JDOQL parameter declarations
	 * @param values a Map with parameter names as keys and parameter values
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#newQuery(Class, String)
	 * @see javax.jdo.Query#declareParameters
	 * @see javax.jdo.Query#executeWithMap
	 */
	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,
	 * with the given result ordering.
	 * @param entityClass a persistent class
	 * @param filter the JDOQL filter to match
	 * @param parameters the JDOQL parameter declarations
	 * @param values a Map with parameter names as keys and parameter values
	 * @param ordering the ordering of the result (or <code>null</code> if none)
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#newQuery(Class, String)
	 * @see javax.jdo.Query#declareParameters
	 * @see javax.jdo.Query#executeWithMap
	 * @see javax.jdo.Query#setOrdering
	 */
	Collection find(Class entityClass, String filter, String parameters, Map values, String ordering)
			throws DataAccessException;

	/**
	 * Find persistent instances through the given query object
	 * in the specified query language.
	 * @param language the query language (<code>javax.jdo.Query#JDOQL</code>
	 * or <code>javax.jdo.Query#SQL</code>, for example)
	 * @param queryObject the query object for the specified language
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#newQuery(String, Object)
	 * @see javax.jdo.Query#JDOQL
	 * @see javax.jdo.Query#SQL
	 */
	Collection find(String language, Object queryObject) throws DataAccessException;

	/**
	 * Find persistent instances through the given single-string JDOQL query.
	 * @param queryString the single-string JDOQL query
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#newQuery(String)
	 */
	Collection find(String queryString) throws DataAccessException;

	/**
	 * Find persistent instances through the given single-string JDOQL query.
	 * @param queryString the single-string JDOQL query
	 * @param values the corresponding parameter values
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#newQuery(String)
	 */
	Collection find(String queryString, Object[] values) throws DataAccessException;

	/**
	 * Find persistent instances through the given single-string JDOQL query.
	 * @param queryString the single-string JDOQL query
	 * @param values a Map with parameter names as keys and parameter values
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#newQuery(String)
	 */
	Collection find(String queryString, Map values) throws DataAccessException;

	/**
	 * Find persistent instances through the given named query.
	 * @param entityClass a persistent class
	 * @param queryName the name of the query
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#newNamedQuery(Class, String)
	 */
	Collection findByNamedQuery(Class entityClass, String queryName) throws DataAccessException;

	/**
	 * Find persistent instances through the given named query.
	 * @param entityClass a persistent class
	 * @param queryName the name of the query
	 * @param values the corresponding parameter values
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#newNamedQuery(Class, String)
	 */
	Collection findByNamedQuery(Class entityClass, String queryName, Object[] values) throws DataAccessException;

	/**
	 * Find persistent instances through the given named query.
	 * @param entityClass a persistent class
	 * @param queryName the name of the query
	 * @param values a Map with parameter names as keys and parameter values
	 * @return the persistent instances
	 * @throws org.springframework.dao.DataAccessException in case of JDO errors
	 * @see javax.jdo.PersistenceManager#newNamedQuery(Class, String)
	 */
	Collection findByNamedQuery(Class entityClass, String queryName, Map values) throws DataAccessException;

}
