001: /*
002: * Copyright 2002-2006 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 expose JDO 2.0 functionality, as of Spring 1.2:
042: * <code>detachCopy</code>, <code>attachCopy</code>, <code>findByNamedQuery</code>, etc.
043: * Those operations will by default only work on top of the standard JDO 2.0 API.
044: * Since Spring 1.2.2, the execution of those operations can also be adapted through
045: * the JdoDialect mechanism (for example, for vendor-specific pre-JDO2 methods).
046: *
047: * @author Juergen Hoeller
048: * @since 1.1
049: * @see JdoTemplate
050: * @see javax.jdo.PersistenceManager
051: * @see JdoTransactionManager
052: * @see JdoDialect
053: * @see org.springframework.orm.jdo.support.OpenPersistenceManagerInViewFilter
054: * @see org.springframework.orm.jdo.support.OpenPersistenceManagerInViewInterceptor
055: */
056: public interface JdoOperations {
057:
058: /**
059: * Execute the action specified by the given action object within a
060: * PersistenceManager. Application exceptions thrown by the action object
061: * get propagated to the caller (can only be unchecked). JDO exceptions
062: * are transformed into appropriate DAO ones. Allows for returning a
063: * result object, i.e. a domain object or a collection of domain objects.
064: * <p>Note: Callback code is not supposed to handle transactions itself!
065: * Use an appropriate transaction manager like JdoTransactionManager.
066: * @param action callback object that specifies the JDO action
067: * @return a result object returned by the action, or <code>null</code>
068: * @throws org.springframework.dao.DataAccessException in case of JDO errors
069: * @see JdoTransactionManager
070: * @see org.springframework.dao
071: * @see org.springframework.transaction
072: * @see javax.jdo.PersistenceManager
073: */
074: Object execute(JdoCallback action) throws DataAccessException;
075:
076: /**
077: * Execute the specified action assuming that the result object is a
078: * Collection. This is a convenience method for executing JDO queries
079: * within an action.
080: * @param action callback object that specifies the JDO action
081: * @return a Collection result returned by the action, or <code>null</code>
082: * @throws org.springframework.dao.DataAccessException in case of JDO errors
083: */
084: Collection executeFind(JdoCallback action)
085: throws DataAccessException;
086:
087: //-------------------------------------------------------------------------
088: // Convenience methods for load, save, delete
089: //-------------------------------------------------------------------------
090:
091: /**
092: * Return the persistent instance with the given JDO object id,
093: * throwing an exception if not found.
094: * <p>A JDO object id identifies both the persistent class and the id
095: * within the namespace of that class.
096: * @param objectId a JDO object id of the persistent instance
097: * @return the persistent instance
098: * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
099: * @throws org.springframework.dao.DataAccessException in case of JDO errors
100: * @see javax.jdo.PersistenceManager#getObjectById(Object, boolean)
101: */
102: Object getObjectById(Object objectId) throws DataAccessException;
103:
104: /**
105: * Return the persistent instance of the given entity class
106: * with the given id value, throwing an exception if not found.
107: * <p>The given id value is typically just unique within the namespace
108: * of the persistent class. Its toString value must correspond to the
109: * toString value of the corresponding JDO object id.
110: * <p>Usually, the passed-in value will have originated from the primary
111: * key field of a persistent object that uses JDO's application identity.
112: * @param entityClass a persistent class
113: * @param idValue an id value of the persistent instance
114: * @return the persistent instance
115: * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
116: * @throws org.springframework.dao.DataAccessException in case of JDO errors
117: * @see javax.jdo.PersistenceManager#getObjectById(Object, boolean)
118: * @see javax.jdo.PersistenceManager#getObjectById(Class, Object)
119: */
120: Object getObjectById(Class entityClass, Object idValue)
121: throws DataAccessException;
122:
123: /**
124: * Remove the given object from the PersistenceManager cache.
125: * @param entity the persistent instance to evict
126: * @throws org.springframework.dao.DataAccessException in case of JDO errors
127: * @see javax.jdo.PersistenceManager#evict(Object)
128: */
129: void evict(Object entity) throws DataAccessException;
130:
131: /**
132: * Remove all given objects from the PersistenceManager cache.
133: * @param entities the persistent instances to evict
134: * @throws org.springframework.dao.DataAccessException in case of JDO errors
135: * @see javax.jdo.PersistenceManager#evictAll(java.util.Collection)
136: */
137: void evictAll(Collection entities) throws DataAccessException;
138:
139: /**
140: * Remove all objects from the PersistenceManager cache.
141: * @throws org.springframework.dao.DataAccessException in case of JDO errors
142: * @see javax.jdo.PersistenceManager#evictAll()
143: */
144: void evictAll() throws DataAccessException;
145:
146: /**
147: * Re-read the state of the given persistent instance.
148: * @param entity the persistent instance to re-read
149: * @throws org.springframework.dao.DataAccessException in case of JDO errors
150: * @see javax.jdo.PersistenceManager#refresh(Object)
151: */
152: void refresh(Object entity) throws DataAccessException;
153:
154: /**
155: * Re-read the state of all given persistent instances.
156: * @param entities the persistent instances to re-read
157: * @throws org.springframework.dao.DataAccessException in case of JDO errors
158: * @see javax.jdo.PersistenceManager#refreshAll(java.util.Collection)
159: */
160: void refreshAll(Collection entities) throws DataAccessException;
161:
162: /**
163: * Re-read the state of all persistent instances.
164: * @throws org.springframework.dao.DataAccessException in case of JDO errors
165: * @see javax.jdo.PersistenceManager#refreshAll()
166: */
167: void refreshAll() throws DataAccessException;
168:
169: /**
170: * Make the given transient instance persistent.
171: * @param entity the transient instance to make persistent
172: * @throws org.springframework.dao.DataAccessException in case of JDO errors
173: * @see javax.jdo.PersistenceManager#makePersistent(Object)
174: */
175: void makePersistent(Object entity) throws DataAccessException;
176:
177: /**
178: * Make the given transient instances persistent.
179: * @param entities the transient instances to make persistent
180: * @throws org.springframework.dao.DataAccessException in case of JDO errors
181: * @see javax.jdo.PersistenceManager#makePersistentAll(java.util.Collection)
182: */
183: void 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: * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
209: * @param entity the persistent instance to detach
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: * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
218: * @param entities the persistent instances to detach
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>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
228: * Note that as of JDO 2.0 final, this operation is equivalent to a
229: * <code>makePersistent</code> call. This dedicated reattach operation
230: * now solely serves as distinction point for custom JdoDialects.
231: * It is still recommended to call this operation for enhanced adaptability.
232: * @param detachedEntity the detached instance to attach
233: * @return the corresponding persistent instance
234: * @see javax.jdo.PersistenceManager#makePersistent(Object)
235: */
236: Object attachCopy(Object detachedEntity);
237:
238: /**
239: * Reattach the given detached instances (for example, web form objects) with
240: * the current JDO transaction, merging their changes into the current persistence
241: * instances that represent the corresponding entities.
242: * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
243: * Note that as of JDO 2.0 final, this operation is equivalent to a
244: * <code>makePersistentAll</code> call. This dedicated reattach operation
245: * now solely serves as distinction point for custom JdoDialects.
246: * It is still recommended to call this operation for enhanced adaptability.
247: * @param detachedEntities the detached instances to reattach
248: * @return the corresponding persistent instances
249: * @see javax.jdo.PersistenceManager#makePersistentAll(java.util.Collection)
250: */
251: Collection attachCopyAll(Collection detachedEntities);
252:
253: /**
254: * Flush all transactional modifications to the database.
255: * <p>Only invoke this for selective eager flushing, for example when JDBC code
256: * needs to see certain changes within the same transaction. Else, it's preferable
257: * to rely on auto-flushing at transaction completion.
258: * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
259: * @throws org.springframework.dao.DataAccessException in case of JDO errors
260: * @see javax.jdo.PersistenceManager#flush()
261: * @see JdoDialect#flush(javax.jdo.PersistenceManager)
262: */
263: void flush() throws DataAccessException;
264:
265: //-------------------------------------------------------------------------
266: // Convenience finder methods
267: //-------------------------------------------------------------------------
268:
269: /**
270: * Find all persistent instances of the given class.
271: * @param entityClass a persistent class
272: * @return the persistent instances
273: * @throws org.springframework.dao.DataAccessException in case of JDO errors
274: * @see javax.jdo.PersistenceManager#newQuery(Class)
275: */
276: Collection find(Class entityClass) throws DataAccessException;
277:
278: /**
279: * Find all persistent instances of the given class that match the given
280: * JDOQL filter.
281: * @param entityClass a persistent class
282: * @param filter the JDOQL filter to match (or <code>null</code> if none)
283: * @return the persistent instances
284: * @throws org.springframework.dao.DataAccessException in case of JDO errors
285: * @see javax.jdo.PersistenceManager#newQuery(Class, String)
286: */
287: Collection find(Class entityClass, String filter)
288: throws DataAccessException;
289:
290: /**
291: * Find all persistent instances of the given class that match the given
292: * JDOQL filter, with the given result ordering.
293: * @param entityClass a persistent class
294: * @param filter the JDOQL filter to match (or <code>null</code> if none)
295: * @param ordering the ordering of the result (or <code>null</code> if none)
296: * @return the persistent instances
297: * @throws org.springframework.dao.DataAccessException in case of JDO errors
298: * @see javax.jdo.PersistenceManager#newQuery(Class, String)
299: * @see javax.jdo.Query#setOrdering
300: */
301: Collection find(Class entityClass, String filter, String ordering)
302: throws DataAccessException;
303:
304: /**
305: * Find all persistent instances of the given class that match the given
306: * JDOQL filter, using the given parameter declarations and parameter values.
307: * @param entityClass a persistent class
308: * @param filter the JDOQL filter to match
309: * @param parameters the JDOQL parameter declarations
310: * @param values the corresponding parameter values
311: * @return the persistent instances
312: * @throws org.springframework.dao.DataAccessException in case of JDO errors
313: * @see javax.jdo.PersistenceManager#newQuery(Class, String)
314: * @see javax.jdo.Query#declareParameters
315: * @see javax.jdo.Query#executeWithArray
316: */
317: Collection find(Class entityClass, String filter,
318: String parameters, Object[] values)
319: throws DataAccessException;
320:
321: /**
322: * Find all persistent instances of the given class that match the given
323: * JDOQL filter, using the given parameter declarations and parameter values,
324: * with the given result ordering.
325: * @param entityClass a persistent class
326: * @param filter the JDOQL filter to match
327: * @param parameters the JDOQL parameter declarations
328: * @param values the corresponding parameter values
329: * @param ordering the ordering of the result (or <code>null</code> if none)
330: * @return the persistent instances
331: * @throws org.springframework.dao.DataAccessException in case of JDO errors
332: * @see javax.jdo.PersistenceManager#newQuery(Class, String)
333: * @see javax.jdo.Query#declareParameters
334: * @see javax.jdo.Query#executeWithArray
335: * @see javax.jdo.Query#setOrdering
336: */
337: Collection find(Class entityClass, String filter,
338: String parameters, Object[] values, String ordering)
339: throws DataAccessException;
340:
341: /**
342: * Find all persistent instances of the given class that match the given
343: * JDOQL filter, using the given parameter declarations and parameter values.
344: * @param entityClass a persistent class
345: * @param filter the JDOQL filter to match
346: * @param parameters the JDOQL parameter declarations
347: * @param values a Map with parameter names as keys and parameter values
348: * @return the persistent instances
349: * @throws org.springframework.dao.DataAccessException in case of JDO errors
350: * @see javax.jdo.PersistenceManager#newQuery(Class, String)
351: * @see javax.jdo.Query#declareParameters
352: * @see javax.jdo.Query#executeWithMap
353: */
354: Collection find(Class entityClass, String filter,
355: String parameters, Map values) throws DataAccessException;
356:
357: /**
358: * Find all persistent instances of the given class that match the given
359: * JDOQL filter, using the given parameter declarations and parameter values,
360: * with the given result ordering.
361: * @param entityClass a persistent class
362: * @param filter the JDOQL filter to match
363: * @param parameters the JDOQL parameter declarations
364: * @param values a Map with parameter names as keys and parameter values
365: * @param ordering the ordering of the result (or <code>null</code> if none)
366: * @return the persistent instances
367: * @throws org.springframework.dao.DataAccessException in case of JDO errors
368: * @see javax.jdo.PersistenceManager#newQuery(Class, String)
369: * @see javax.jdo.Query#declareParameters
370: * @see javax.jdo.Query#executeWithMap
371: * @see javax.jdo.Query#setOrdering
372: */
373: Collection find(Class entityClass, String filter,
374: String parameters, Map values, String ordering)
375: throws DataAccessException;
376:
377: /**
378: * Find persistent instances through the given query object
379: * in the specified query language.
380: * <p>Only available on JDO 2.0 and higher.
381: * @param language the query language (<code>javax.jdo.Query#JDOQL</code>
382: * or <code>javax.jdo.Query#SQL</code>, for example)
383: * @param queryObject the query object for the specified language
384: * @return the persistent instances
385: * @throws org.springframework.dao.DataAccessException in case of JDO errors
386: * @see javax.jdo.PersistenceManager#newQuery(String, Object)
387: * @see javax.jdo.Query#JDOQL
388: * @see javax.jdo.Query#SQL
389: */
390: Collection find(String language, Object queryObject)
391: throws DataAccessException;
392:
393: /**
394: * Find persistent instances through the given single-string JDOQL query.
395: * <p>Only available on JDO 2.0 and higher.
396: * @param queryString the single-string JDOQL query
397: * @return the persistent instances
398: * @throws org.springframework.dao.DataAccessException in case of JDO errors
399: * @see javax.jdo.PersistenceManager#newQuery(String)
400: */
401: Collection find(String queryString) throws DataAccessException;
402:
403: /**
404: * Find persistent instances through the given single-string JDOQL query.
405: * <p>Only available on JDO 2.0 and higher.
406: * @param queryString the single-string JDOQL query
407: * @param values the corresponding parameter values
408: * @return the persistent instances
409: * @throws org.springframework.dao.DataAccessException in case of JDO errors
410: * @see javax.jdo.PersistenceManager#newQuery(String)
411: */
412: Collection find(String queryString, Object[] values)
413: throws DataAccessException;
414:
415: /**
416: * Find persistent instances through the given single-string JDOQL query.
417: * <p>Only available on JDO 2.0 and higher.
418: * @param queryString the single-string JDOQL query
419: * @param values a Map with parameter names as keys and parameter values
420: * @return the persistent instances
421: * @throws org.springframework.dao.DataAccessException in case of JDO errors
422: * @see javax.jdo.PersistenceManager#newQuery(String)
423: */
424: Collection find(String queryString, Map values)
425: throws DataAccessException;
426:
427: /**
428: * Find persistent instances through the given named query.
429: * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
430: * @param entityClass a persistent class
431: * @param queryName the name of the query
432: * @return the persistent instances
433: * @throws org.springframework.dao.DataAccessException in case of JDO errors
434: * @see javax.jdo.PersistenceManager#newNamedQuery(Class, String)
435: */
436: Collection findByNamedQuery(Class entityClass, String queryName)
437: throws DataAccessException;
438:
439: /**
440: * Find persistent instances through the given named query.
441: * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
442: * @param entityClass a persistent class
443: * @param queryName the name of the query
444: * @param values the corresponding parameter values
445: * @return the persistent instances
446: * @throws org.springframework.dao.DataAccessException in case of JDO errors
447: * @see javax.jdo.PersistenceManager#newNamedQuery(Class, String)
448: */
449: Collection findByNamedQuery(Class entityClass, String queryName,
450: Object[] values) throws DataAccessException;
451:
452: /**
453: * Find persistent instances through the given named query.
454: * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
455: * @param entityClass a persistent class
456: * @param queryName the name of the query
457: * @param values a Map with parameter names as keys and parameter values
458: * @return the persistent instances
459: * @throws org.springframework.dao.DataAccessException in case of JDO errors
460: * @see javax.jdo.PersistenceManager#newNamedQuery(Class, String)
461: */
462: Collection findByNamedQuery(Class entityClass, String queryName,
463: Map values) throws DataAccessException;
464:
465: }
|