001: /*
002: * Copyright 2002-2007 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.springframework.orm.jdo;
018:
019: import java.util.Collection;
020: import java.util.Map;
021:
022: import org.springframework.dao.DataAccessException;
023:
024: /**
025: * Interface that specifies a basic set of JDO operations,
026: * implemented by {@link JdoTemplate}. Not often used, but a useful
027: * option to enhance testability, as it can easily be mocked or stubbed.
028: *
029: * <p>Defines <code>JdoTemplate</code>'s data access methods that mirror
030: * various JDO {@link javax.jdo.PersistenceManager} methods. Users are
031: * strongly encouraged to read the JDO <code>PersistenceManager</code>
032: * javadocs for details on the semantics of those methods.
033: *
034: * <p>Note that lazy loading will just work with an open JDO
035: * <code>PersistenceManager</code>, either within a managed transaction or within
036: * {@link org.springframework.orm.jdo.support.OpenPersistenceManagerInViewFilter}/
037: * {@link org.springframework.orm.jdo.support.OpenPersistenceManagerInViewInterceptor}.
038: * Furthermore, some operations just make sense within transactions,
039: * for example: <code>evict</code>, <code>evictAll</code>, <code>flush</code>.
040: *
041: * <p>Updated to build on JDO 2.0 or higher, as of Spring 2.5.
042: *
043: * @author Juergen Hoeller
044: * @since 1.1
045: * @see JdoTemplate
046: * @see javax.jdo.PersistenceManager
047: * @see JdoTransactionManager
048: * @see JdoDialect
049: * @see org.springframework.orm.jdo.support.OpenPersistenceManagerInViewFilter
050: * @see org.springframework.orm.jdo.support.OpenPersistenceManagerInViewInterceptor
051: */
052: public interface JdoOperations {
053:
054: /**
055: * Execute the action specified by the given action object within a
056: * PersistenceManager. Application exceptions thrown by the action object
057: * get propagated to the caller (can only be unchecked). JDO exceptions
058: * are transformed into appropriate DAO ones. Allows for returning a
059: * result object, i.e. a domain object or a collection of domain objects.
060: * <p>Note: Callback code is not supposed to handle transactions itself!
061: * Use an appropriate transaction manager like JdoTransactionManager.
062: * @param action callback object that specifies the JDO action
063: * @return a result object returned by the action, or <code>null</code>
064: * @throws org.springframework.dao.DataAccessException in case of JDO errors
065: * @see JdoTransactionManager
066: * @see org.springframework.dao
067: * @see org.springframework.transaction
068: * @see javax.jdo.PersistenceManager
069: */
070: Object execute(JdoCallback action) throws DataAccessException;
071:
072: /**
073: * Execute the specified action assuming that the result object is a
074: * Collection. This is a convenience method for executing JDO queries
075: * within an action.
076: * @param action callback object that specifies the JDO action
077: * @return a Collection result returned by the action, or <code>null</code>
078: * @throws org.springframework.dao.DataAccessException in case of JDO errors
079: */
080: Collection executeFind(JdoCallback action)
081: throws DataAccessException;
082:
083: //-------------------------------------------------------------------------
084: // Convenience methods for load, save, delete
085: //-------------------------------------------------------------------------
086:
087: /**
088: * Return the persistent instance with the given JDO object id,
089: * throwing an exception if not found.
090: * <p>A JDO object id identifies both the persistent class and the id
091: * within the namespace of that class.
092: * @param objectId a JDO object id of the persistent instance
093: * @return the persistent instance
094: * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
095: * @throws org.springframework.dao.DataAccessException in case of JDO errors
096: * @see javax.jdo.PersistenceManager#getObjectById(Object, boolean)
097: */
098: Object getObjectById(Object objectId) throws DataAccessException;
099:
100: /**
101: * Return the persistent instance of the given entity class
102: * with the given id value, throwing an exception if not found.
103: * <p>The given id value is typically just unique within the namespace
104: * of the persistent class. Its toString value must correspond to the
105: * toString value of the corresponding JDO object id.
106: * <p>Usually, the passed-in value will have originated from the primary
107: * key field of a persistent object that uses JDO's application identity.
108: * @param entityClass a persistent class
109: * @param idValue an id value of the persistent instance
110: * @return the persistent instance
111: * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
112: * @throws org.springframework.dao.DataAccessException in case of JDO errors
113: * @see javax.jdo.PersistenceManager#getObjectById(Object, boolean)
114: * @see javax.jdo.PersistenceManager#getObjectById(Class, Object)
115: */
116: Object getObjectById(Class entityClass, Object idValue)
117: throws DataAccessException;
118:
119: /**
120: * Remove the given object from the PersistenceManager cache.
121: * @param entity the persistent instance to evict
122: * @throws org.springframework.dao.DataAccessException in case of JDO errors
123: * @see javax.jdo.PersistenceManager#evict(Object)
124: */
125: void evict(Object entity) throws DataAccessException;
126:
127: /**
128: * Remove all given objects from the PersistenceManager cache.
129: * @param entities the persistent instances to evict
130: * @throws org.springframework.dao.DataAccessException in case of JDO errors
131: * @see javax.jdo.PersistenceManager#evictAll(java.util.Collection)
132: */
133: void evictAll(Collection entities) throws DataAccessException;
134:
135: /**
136: * Remove all objects from the PersistenceManager cache.
137: * @throws org.springframework.dao.DataAccessException in case of JDO errors
138: * @see javax.jdo.PersistenceManager#evictAll()
139: */
140: void evictAll() throws DataAccessException;
141:
142: /**
143: * Re-read the state of the given persistent instance.
144: * @param entity the persistent instance to re-read
145: * @throws org.springframework.dao.DataAccessException in case of JDO errors
146: * @see javax.jdo.PersistenceManager#refresh(Object)
147: */
148: void refresh(Object entity) throws DataAccessException;
149:
150: /**
151: * Re-read the state of all given persistent instances.
152: * @param entities the persistent instances to re-read
153: * @throws org.springframework.dao.DataAccessException in case of JDO errors
154: * @see javax.jdo.PersistenceManager#refreshAll(java.util.Collection)
155: */
156: void refreshAll(Collection entities) throws DataAccessException;
157:
158: /**
159: * Re-read the state of all persistent instances.
160: * @throws org.springframework.dao.DataAccessException in case of JDO errors
161: * @see javax.jdo.PersistenceManager#refreshAll()
162: */
163: void refreshAll() throws DataAccessException;
164:
165: /**
166: * Make the given transient instance persistent.
167: * Attach the given entity if the instance is detached.
168: * @param entity the transient instance to make persistent
169: * @return the persistent instance
170: * @throws org.springframework.dao.DataAccessException in case of JDO errors
171: * @see javax.jdo.PersistenceManager#makePersistent(Object)
172: */
173: Object makePersistent(Object entity) throws DataAccessException;
174:
175: /**
176: * Make the given transient instances persistent.
177: * Attach the given entities if the instances are detached.
178: * @param entities the transient instances to make persistent
179: * @return the persistent instances
180: * @throws org.springframework.dao.DataAccessException in case of JDO errors
181: * @see javax.jdo.PersistenceManager#makePersistentAll(java.util.Collection)
182: */
183: Collection makePersistentAll(Collection entities)
184: throws DataAccessException;
185:
186: /**
187: * Delete the given persistent instance.
188: * @param entity the persistent instance to delete
189: * @throws org.springframework.dao.DataAccessException in case of JDO errors
190: * @see javax.jdo.PersistenceManager#deletePersistent(Object)
191: */
192: void deletePersistent(Object entity) throws DataAccessException;
193:
194: /**
195: * Delete all given persistent instances.
196: * <p>This can be combined with any of the find methods to delete by query
197: * in two lines of code.
198: * @param entities the persistent instances to delete
199: * @throws org.springframework.dao.DataAccessException in case of JDO errors
200: * @see javax.jdo.PersistenceManager#deletePersistentAll(java.util.Collection)
201: */
202: void deletePersistentAll(Collection entities)
203: throws DataAccessException;
204:
205: /**
206: * Detach a copy of the given persistent instance from the current JDO transaction,
207: * for use outside a JDO transaction (for example, as web form object).
208: * @param entity the persistent instance to detach
209: * @return the corresponding detached instance
210: * @see javax.jdo.PersistenceManager#detachCopy(Object)
211: */
212: Object detachCopy(Object entity);
213:
214: /**
215: * Detach copies of the given persistent instances from the current JDO transaction,
216: * for use outside a JDO transaction (for example, as web form objects).
217: * @param entities the persistent instances to detach
218: * @return the corresponding detached instances
219: * @see javax.jdo.PersistenceManager#detachCopyAll(Collection)
220: */
221: Collection detachCopyAll(Collection entities);
222:
223: /**
224: * Reattach the given detached instance (for example, a web form object) with
225: * the current JDO transaction, merging its changes into the current persistence
226: * instance that represents the corresponding entity.
227: * <p>Note that as of JDO 2.0 final, this operation is equivalent to a
228: * <code>makePersistent</code> call, with the latter method returning the
229: * persistence instance.
230: * @param detachedEntity the detached instance to attach
231: * @return the corresponding persistent instance
232: * @deprecated in favor of {@link #makePersistent(Object)}.
233: * To be removed in Spring 3.0.
234: */
235: Object attachCopy(Object detachedEntity);
236:
237: /**
238: * Reattach the given detached instances (for example, web form objects) with
239: * the current JDO transaction, merging their changes into the current persistence
240: * instances that represent the corresponding entities.
241: * <p>Note that as of JDO 2.0 final, this operation is equivalent to a
242: * <code>makePersistentAll</code> call, with the latter method returning the
243: * persistence instance.
244: * @param detachedEntities the detached instances to reattach
245: * @return the corresponding persistent instances
246: * @deprecated in favor of {@link #makePersistentAll(java.util.Collection)}.
247: * To be removed in Spring 3.0.
248: */
249: Collection attachCopyAll(Collection detachedEntities);
250:
251: /**
252: * Flush all transactional modifications to the database.
253: * <p>Only invoke this for selective eager flushing, for example when JDBC code
254: * needs to see certain changes within the same transaction. Else, it's preferable
255: * to rely on auto-flushing at transaction completion.
256: * @throws org.springframework.dao.DataAccessException in case of JDO errors
257: * @see javax.jdo.PersistenceManager#flush()
258: * @see JdoDialect#flush(javax.jdo.PersistenceManager)
259: */
260: void flush() throws DataAccessException;
261:
262: //-------------------------------------------------------------------------
263: // Convenience finder methods
264: //-------------------------------------------------------------------------
265:
266: /**
267: * Find all persistent instances of the given class.
268: * @param entityClass a persistent class
269: * @return the persistent instances
270: * @throws org.springframework.dao.DataAccessException in case of JDO errors
271: * @see javax.jdo.PersistenceManager#newQuery(Class)
272: */
273: Collection find(Class entityClass) throws DataAccessException;
274:
275: /**
276: * Find all persistent instances of the given class that match the given
277: * JDOQL filter.
278: * @param entityClass a persistent class
279: * @param filter the JDOQL filter to match (or <code>null</code> if none)
280: * @return the persistent instances
281: * @throws org.springframework.dao.DataAccessException in case of JDO errors
282: * @see javax.jdo.PersistenceManager#newQuery(Class, String)
283: */
284: Collection find(Class entityClass, String filter)
285: throws DataAccessException;
286:
287: /**
288: * Find all persistent instances of the given class that match the given
289: * JDOQL filter, with the given result ordering.
290: * @param entityClass a persistent class
291: * @param filter the JDOQL filter to match (or <code>null</code> if none)
292: * @param ordering the ordering of the result (or <code>null</code> if none)
293: * @return the persistent instances
294: * @throws org.springframework.dao.DataAccessException in case of JDO errors
295: * @see javax.jdo.PersistenceManager#newQuery(Class, String)
296: * @see javax.jdo.Query#setOrdering
297: */
298: Collection find(Class entityClass, String filter, String ordering)
299: throws DataAccessException;
300:
301: /**
302: * Find all persistent instances of the given class that match the given
303: * JDOQL filter, using the given parameter declarations and parameter values.
304: * @param entityClass a persistent class
305: * @param filter the JDOQL filter to match
306: * @param parameters the JDOQL parameter declarations
307: * @param values the corresponding parameter values
308: * @return the persistent instances
309: * @throws org.springframework.dao.DataAccessException in case of JDO errors
310: * @see javax.jdo.PersistenceManager#newQuery(Class, String)
311: * @see javax.jdo.Query#declareParameters
312: * @see javax.jdo.Query#executeWithArray
313: */
314: Collection find(Class entityClass, String filter,
315: String parameters, Object[] values)
316: throws DataAccessException;
317:
318: /**
319: * Find all persistent instances of the given class that match the given
320: * JDOQL filter, using the given parameter declarations and parameter values,
321: * with the given result ordering.
322: * @param entityClass a persistent class
323: * @param filter the JDOQL filter to match
324: * @param parameters the JDOQL parameter declarations
325: * @param values the corresponding parameter values
326: * @param ordering the ordering of the result (or <code>null</code> if none)
327: * @return the persistent instances
328: * @throws org.springframework.dao.DataAccessException in case of JDO errors
329: * @see javax.jdo.PersistenceManager#newQuery(Class, String)
330: * @see javax.jdo.Query#declareParameters
331: * @see javax.jdo.Query#executeWithArray
332: * @see javax.jdo.Query#setOrdering
333: */
334: Collection find(Class entityClass, String filter,
335: String parameters, Object[] values, String ordering)
336: throws DataAccessException;
337:
338: /**
339: * Find all persistent instances of the given class that match the given
340: * JDOQL filter, using the given parameter declarations and parameter values.
341: * @param entityClass a persistent class
342: * @param filter the JDOQL filter to match
343: * @param parameters the JDOQL parameter declarations
344: * @param values a Map with parameter names as keys and parameter values
345: * @return the persistent instances
346: * @throws org.springframework.dao.DataAccessException in case of JDO errors
347: * @see javax.jdo.PersistenceManager#newQuery(Class, String)
348: * @see javax.jdo.Query#declareParameters
349: * @see javax.jdo.Query#executeWithMap
350: */
351: Collection find(Class entityClass, String filter,
352: String parameters, Map values) throws DataAccessException;
353:
354: /**
355: * Find all persistent instances of the given class that match the given
356: * JDOQL filter, using the given parameter declarations and parameter values,
357: * with the given result ordering.
358: * @param entityClass a persistent class
359: * @param filter the JDOQL filter to match
360: * @param parameters the JDOQL parameter declarations
361: * @param values a Map with parameter names as keys and parameter values
362: * @param ordering the ordering of the result (or <code>null</code> if none)
363: * @return the persistent instances
364: * @throws org.springframework.dao.DataAccessException in case of JDO errors
365: * @see javax.jdo.PersistenceManager#newQuery(Class, String)
366: * @see javax.jdo.Query#declareParameters
367: * @see javax.jdo.Query#executeWithMap
368: * @see javax.jdo.Query#setOrdering
369: */
370: Collection find(Class entityClass, String filter,
371: String parameters, Map values, String ordering)
372: throws DataAccessException;
373:
374: /**
375: * Find persistent instances through the given query object
376: * in the specified query language.
377: * @param language the query language (<code>javax.jdo.Query#JDOQL</code>
378: * or <code>javax.jdo.Query#SQL</code>, for example)
379: * @param queryObject the query object for the specified language
380: * @return the persistent instances
381: * @throws org.springframework.dao.DataAccessException in case of JDO errors
382: * @see javax.jdo.PersistenceManager#newQuery(String, Object)
383: * @see javax.jdo.Query#JDOQL
384: * @see javax.jdo.Query#SQL
385: */
386: Collection find(String language, Object queryObject)
387: throws DataAccessException;
388:
389: /**
390: * Find persistent instances through the given single-string JDOQL query.
391: * @param queryString the single-string JDOQL query
392: * @return the persistent instances
393: * @throws org.springframework.dao.DataAccessException in case of JDO errors
394: * @see javax.jdo.PersistenceManager#newQuery(String)
395: */
396: Collection find(String queryString) throws DataAccessException;
397:
398: /**
399: * Find persistent instances through the given single-string JDOQL query.
400: * @param queryString the single-string JDOQL query
401: * @param values the corresponding parameter values
402: * @return the persistent instances
403: * @throws org.springframework.dao.DataAccessException in case of JDO errors
404: * @see javax.jdo.PersistenceManager#newQuery(String)
405: */
406: Collection find(String queryString, Object[] values)
407: throws DataAccessException;
408:
409: /**
410: * Find persistent instances through the given single-string JDOQL query.
411: * @param queryString the single-string JDOQL query
412: * @param values a Map with parameter names as keys and parameter values
413: * @return the persistent instances
414: * @throws org.springframework.dao.DataAccessException in case of JDO errors
415: * @see javax.jdo.PersistenceManager#newQuery(String)
416: */
417: Collection find(String queryString, Map values)
418: throws DataAccessException;
419:
420: /**
421: * Find persistent instances through the given named query.
422: * @param entityClass a persistent class
423: * @param queryName the name of the query
424: * @return the persistent instances
425: * @throws org.springframework.dao.DataAccessException in case of JDO errors
426: * @see javax.jdo.PersistenceManager#newNamedQuery(Class, String)
427: */
428: Collection findByNamedQuery(Class entityClass, String queryName)
429: throws DataAccessException;
430:
431: /**
432: * Find persistent instances through the given named query.
433: * @param entityClass a persistent class
434: * @param queryName the name of the query
435: * @param values the corresponding parameter values
436: * @return the persistent instances
437: * @throws org.springframework.dao.DataAccessException in case of JDO errors
438: * @see javax.jdo.PersistenceManager#newNamedQuery(Class, String)
439: */
440: Collection findByNamedQuery(Class entityClass, String queryName,
441: Object[] values) throws DataAccessException;
442:
443: /**
444: * Find persistent instances through the given named query.
445: * @param entityClass a persistent class
446: * @param queryName the name of the query
447: * @param values a Map with parameter names as keys and parameter values
448: * @return the persistent instances
449: * @throws org.springframework.dao.DataAccessException in case of JDO errors
450: * @see javax.jdo.PersistenceManager#newNamedQuery(Class, String)
451: */
452: Collection findByNamedQuery(Class entityClass, String queryName,
453: Map values) throws DataAccessException;
454:
455: }
|