/* * 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. * *
Defines JdoTemplate
's data access methods that mirror
* various JDO {@link javax.jdo.PersistenceManager} methods. Users are
* strongly encouraged to read the JDO PersistenceManager
* javadocs for details on the semantics of those methods.
*
*
Note that lazy loading will just work with an open JDO
* PersistenceManager
, either within a managed transaction or within
* {@link org.springframework.orm.jdo.support.OpenPersistenceManagerInViewFilter}/
* {@link org.springframework.orm.jdo.support.OpenPersistenceManagerInViewInterceptor}.
* Furthermore, some operations just make sense within transactions,
* for example: evict
, evictAll
, flush
.
*
*
Updated to build on JDO 2.0 or higher, as of Spring 2.5. * * @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. *
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 null
* @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 null
* @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.
*
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. *
The given id value is typically just unique within the namespace * of the persistent class. Its toString value must correspond to the * toString value of the corresponding JDO object id. *
Usually, the passed-in value will have originated from the primary * key field of a persistent object that uses JDO's application identity. * @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. *
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. *
Note that as of JDO 2.0 final, this operation is equivalent to a
* makePersistent
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.
*
Note that as of JDO 2.0 final, this operation is equivalent to a
* makePersistentAll
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.
*
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 null
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 null
if none)
* @param ordering the ordering of the result (or null
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 null
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 null
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 (javax.jdo.Query#JDOQL
* or javax.jdo.Query#SQL
, 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;
}