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.toplink;
018:
019: import java.util.Collection;
020: import java.util.List;
021:
022: import oracle.toplink.expressions.Expression;
023: import oracle.toplink.queryframework.Call;
024: import oracle.toplink.queryframework.DatabaseQuery;
025: import oracle.toplink.sessions.ObjectCopyingPolicy;
026:
027: import org.springframework.dao.DataAccessException;
028:
029: /**
030: * Interface that specifies a basic set of TopLink operations,
031: * implemented by {@link TopLinkTemplate}. Not often used, but a useful
032: * option to enhance testability, as it can easily be mocked or stubbed.
033: *
034: * <p>Defines <code>TopLinkTemplate</code>'s data access methods that
035: * mirror various TopLink {@link oracle.toplink.sessions.Session} /
036: * {@link oracle.toplink.sessions.UnitOfWork} methods. Users are
037: * strongly encouraged to read the TopLink javadocs for details
038: * on the semantics of those methods.
039: *
040: * @author Juergen Hoeller
041: * @since 1.2
042: */
043: public interface TopLinkOperations {
044:
045: /**
046: * Execute the action specified by the given action object within a
047: * TopLink Session. Application exceptions thrown by the action object
048: * get propagated to the caller (can only be unchecked). TopLink exceptions
049: * are transformed into appropriate DAO ones. Allows for returning a
050: * result object, i.e. a domain object or a collection of domain objects.
051: * <p>Note: Callback code is not supposed to handle transactions itself!
052: * Use an appropriate transaction manager like TopLinkTransactionManager.
053: * @param action callback object that specifies the TopLink action
054: * @return a result object returned by the action, or <code>null</code>
055: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
056: * @see TopLinkTransactionManager
057: * @see org.springframework.dao
058: * @see org.springframework.transaction
059: * @see oracle.toplink.sessions.Session
060: */
061: Object execute(TopLinkCallback action) throws DataAccessException;
062:
063: /**
064: * Execute the specified action assuming that the result object is a
065: * Collection. This is a convenience method for executing TopLink queries
066: * within an action.
067: * @param action callback object that specifies the TopLink action
068: * @return a Collection result returned by the action, or <code>null</code>
069: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
070: */
071: List executeFind(TopLinkCallback action) throws DataAccessException;
072:
073: //-------------------------------------------------------------------------
074: // Convenience methods for executing generic queries
075: //-------------------------------------------------------------------------
076:
077: /**
078: * Execute a given named query with the given arguments.
079: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
080: * non-read-only transaction, and read-only objects else.
081: * @param entityClass the entity class that has the named query descriptor
082: * @param queryName the name of the query
083: * @return the result object or list of result objects for the query
084: * (can be cast to the entity class or Collection/List, respectively)
085: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
086: * @see oracle.toplink.sessions.Session#executeQuery(String, Class)
087: */
088: Object executeNamedQuery(Class entityClass, String queryName)
089: throws DataAccessException;
090:
091: /**
092: * Execute a given named query with the given arguments.
093: * @param entityClass the entity class that has the named query descriptor
094: * @param queryName the name of the query
095: * @param enforceReadOnly whether to always retrieve read-only objects from
096: * the plain TopLink Session (else, read-write objects will be retrieved
097: * from the TopLink UnitOfWork in case of a non-read-only transaction)
098: * @return the result object or list of result objects for the query
099: * (can be cast to the entity class or Collection/List, respectively)
100: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
101: * @see oracle.toplink.sessions.Session#executeQuery(String, Class)
102: */
103: Object executeNamedQuery(Class entityClass, String queryName,
104: boolean enforceReadOnly) throws DataAccessException;
105:
106: /**
107: * Execute a given named query with the given arguments.
108: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
109: * non-read-only transaction, and read-only objects else.
110: * @param entityClass the entity class that has the named query descriptor
111: * @param queryName the name of the query
112: * @param args the arguments for the query (can be <code>null</code>)
113: * @return the result object or list of result objects for the query
114: * (can be cast to the entity class or Collection/List, respectively)
115: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
116: * @see oracle.toplink.sessions.Session#executeQuery(String, Class, java.util.Vector)
117: */
118: Object executeNamedQuery(Class entityClass, String queryName,
119: Object[] args) throws DataAccessException;
120:
121: /**
122: * Execute a given named query with the given arguments.
123: * @param entityClass the entity class that has the named query descriptor
124: * @param queryName the name of the query
125: * @param args the arguments for the query (can be <code>null</code>)
126: * @param enforceReadOnly whether to always retrieve read-only objects from
127: * the plain TopLink Session (else, read-write objects will be retrieved
128: * from the TopLink UnitOfWork in case of a non-read-only transaction)
129: * @return the result object or list of result objects for the query
130: * (can be cast to the entity class or Collection/List, respectively)
131: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
132: * @see oracle.toplink.sessions.Session#executeQuery(String, Class, java.util.Vector)
133: */
134: Object executeNamedQuery(Class entityClass, String queryName,
135: Object[] args, boolean enforceReadOnly)
136: throws DataAccessException;
137:
138: /**
139: * Execute the given query object with the given arguments.
140: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
141: * non-read-only transaction, and read-only objects else.
142: * @param query the query object to execute (for example,
143: * a ReadObjectQuery or ReadAllQuery instance)
144: * @return the result object or list of result objects for the query
145: * (can be cast to the entity class or Collection/List, respectively)
146: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
147: * @see oracle.toplink.sessions.Session#executeQuery(oracle.toplink.queryframework.DatabaseQuery)
148: */
149: Object executeQuery(DatabaseQuery query) throws DataAccessException;
150:
151: /**
152: * Execute the given query object with the given arguments.
153: * @param query the query object to execute (for example,
154: * a ReadObjectQuery or ReadAllQuery instance)
155: * @param enforceReadOnly whether to always retrieve read-only objects from
156: * the plain TopLink Session (else, read-write objects will be retrieved
157: * from the TopLink UnitOfWork in case of a non-read-only transaction)
158: * @return the result object or list of result objects for the query
159: * (can be cast to the entity class or Collection/List, respectively)
160: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
161: * @see oracle.toplink.sessions.Session#executeQuery(oracle.toplink.queryframework.DatabaseQuery)
162: */
163: Object executeQuery(DatabaseQuery query, boolean enforceReadOnly)
164: throws DataAccessException;
165:
166: /**
167: * Execute the given query object with the given arguments.
168: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
169: * non-read-only transaction, and read-only objects else.
170: * @param query the query object to execute (for example,
171: * a ReadObjectQuery or ReadAllQuery instance)
172: * @param args the arguments for the query (can be <code>null</code>)
173: * @return the result object or list of result objects for the query
174: * (can be cast to the entity class or Collection/List, respectively)
175: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
176: * @see oracle.toplink.sessions.Session#executeQuery(oracle.toplink.queryframework.DatabaseQuery, java.util.Vector)
177: */
178: Object executeQuery(DatabaseQuery query, Object[] args)
179: throws DataAccessException;
180:
181: /**
182: * Execute the given query object with the given arguments.
183: * @param query the query object to execute (for example,
184: * a ReadObjectQuery or ReadAllQuery instance)
185: * @param args the arguments for the query (can be <code>null</code>)
186: * @param enforceReadOnly whether to always retrieve read-only objects from
187: * the plain TopLink Session (else, read-write objects will be retrieved
188: * from the TopLink UnitOfWork in case of a non-read-only transaction)
189: * @return the result object or list of result objects for the query
190: * (can be cast to the entity class or Collection/List, respectively)
191: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
192: * @see oracle.toplink.sessions.Session#executeQuery(oracle.toplink.queryframework.DatabaseQuery, java.util.Vector)
193: */
194: Object executeQuery(DatabaseQuery query, Object[] args,
195: boolean enforceReadOnly) throws DataAccessException;
196:
197: //-------------------------------------------------------------------------
198: // Convenience methods for reading a specific set of objects
199: //-------------------------------------------------------------------------
200:
201: /**
202: * Read all entity instances of the given class.
203: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
204: * non-read-only transaction, and read-only objects else.
205: * @param entityClass the entity class
206: * @return the list of entity instances
207: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
208: * @see oracle.toplink.sessions.Session#readAllObjects(Class)
209: */
210: List readAll(Class entityClass) throws DataAccessException;
211:
212: /**
213: * Read all entity instances of the given class.
214: * @param entityClass the entity class
215: * @param enforceReadOnly whether to always retrieve read-only objects from
216: * the plain TopLink Session (else, read-write objects will be retrieved
217: * from the TopLink UnitOfWork in case of a non-read-only transaction)
218: * @return the list of entity instances
219: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
220: * @see oracle.toplink.sessions.Session#readAllObjects(Class)
221: */
222: List readAll(Class entityClass, boolean enforceReadOnly)
223: throws DataAccessException;
224:
225: /**
226: * Read all entity instances of the given class that match the given expression.
227: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
228: * non-read-only transaction, and read-only objects else.
229: * @param entityClass the entity class
230: * @param expression the TopLink expression to match,
231: * usually built through the TopLink ExpressionBuilder
232: * @return the list of matching entity instances
233: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
234: * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
235: * @see oracle.toplink.expressions.ExpressionBuilder
236: */
237: List readAll(Class entityClass, Expression expression)
238: throws DataAccessException;
239:
240: /**
241: * Read all entity instances of the given class that match the given expression.
242: * @param entityClass the entity class
243: * @param expression the TopLink expression to match,
244: * usually built through the TopLink ExpressionBuilder
245: * @param enforceReadOnly whether to always retrieve read-only objects from
246: * the plain TopLink Session (else, read-write objects will be retrieved
247: * from the TopLink UnitOfWork in case of a non-read-only transaction)
248: * @return the list of matching entity instances
249: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
250: * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
251: * @see oracle.toplink.expressions.ExpressionBuilder
252: */
253: List readAll(Class entityClass, Expression expression,
254: boolean enforceReadOnly) throws DataAccessException;
255:
256: /**
257: * Read all entity instances of the given class, as returned by the given call.
258: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
259: * non-read-only transaction, and read-only objects else.
260: * @param entityClass the entity class
261: * @param call the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
262: * @return the list of matching entity instances
263: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
264: * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.queryframework.Call)
265: * @see oracle.toplink.queryframework.SQLCall
266: * @see oracle.toplink.queryframework.EJBQLCall
267: */
268: List readAll(Class entityClass, Call call)
269: throws DataAccessException;
270:
271: /**
272: * Read all entity instances of the given class, as returned by the given call.
273: * @param entityClass the entity class
274: * @param call the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
275: * @param enforceReadOnly whether to always retrieve read-only objects from
276: * the plain TopLink Session (else, read-write objects will be retrieved
277: * from the TopLink UnitOfWork in case of a non-read-only transaction)
278: * @return the list of matching entity instances
279: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
280: * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
281: * @see oracle.toplink.queryframework.SQLCall
282: * @see oracle.toplink.queryframework.EJBQLCall
283: */
284: List readAll(Class entityClass, Call call, boolean enforceReadOnly)
285: throws DataAccessException;
286:
287: /**
288: * Read an entity instance of the given class that matches the given expression.
289: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
290: * non-read-only transaction, and read-only objects else.
291: * @param entityClass the entity class
292: * @param expression the TopLink expression to match,
293: * usually built through the TopLink ExpressionBuilder
294: * @return the matching entity instance, or <code>null</code> if none found
295: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
296: * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
297: * @see oracle.toplink.expressions.ExpressionBuilder
298: */
299: Object read(Class entityClass, Expression expression)
300: throws DataAccessException;
301:
302: /**
303: * Read an entity instance of the given class that matches the given expression.
304: * @param entityClass the entity class
305: * @param expression the TopLink expression to match,
306: * usually built through the TopLink ExpressionBuilder
307: * @param enforceReadOnly whether to always retrieve read-only objects from
308: * the plain TopLink Session (else, read-write objects will be retrieved
309: * from the TopLink UnitOfWork in case of a non-read-only transaction)
310: * @return a matching entity instance, or <code>null</code> if none found
311: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
312: * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
313: * @see oracle.toplink.expressions.ExpressionBuilder
314: */
315: Object read(Class entityClass, Expression expression,
316: boolean enforceReadOnly) throws DataAccessException;
317:
318: /**
319: * Read an entity instance of the given class, as returned by the given call.
320: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
321: * non-read-only transaction, and read-only objects else.
322: * @param entityClass the entity class
323: * @param call the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
324: * @return a matching entity instance, or <code>null</code> if none found
325: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
326: * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.queryframework.Call)
327: * @see oracle.toplink.queryframework.SQLCall
328: * @see oracle.toplink.queryframework.EJBQLCall
329: */
330: Object read(Class entityClass, Call call)
331: throws DataAccessException;
332:
333: /**
334: * Read an entity instance of the given class, as returned by the given call.
335: * @param entityClass the entity class
336: * @param call the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
337: * @param enforceReadOnly whether to always retrieve read-only objects from
338: * the plain TopLink Session (else, read-write objects will be retrieved
339: * from the TopLink UnitOfWork in case of a non-read-only transaction)
340: * @return a matching entity instance, or <code>null</code> if none found
341: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
342: * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
343: * @see oracle.toplink.queryframework.SQLCall
344: * @see oracle.toplink.queryframework.EJBQLCall
345: */
346: Object read(Class entityClass, Call call, boolean enforceReadOnly)
347: throws DataAccessException;
348:
349: //-------------------------------------------------------------------------
350: // Convenience methods for reading an individual object by id
351: //-------------------------------------------------------------------------
352:
353: /**
354: * Read the entity instance of the given class with the given id,
355: * throwing an exception if not found.
356: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
357: * non-read-only transaction, and read-only objects else.
358: * @param entityClass the entity class
359: * @param id the id of the desired object
360: * @return the entity instance
361: * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
362: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
363: * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
364: */
365: Object readById(Class entityClass, Object id)
366: throws DataAccessException;
367:
368: /**
369: * Read the entity instance of the given class with the given id,
370: * throwing an exception if not found.
371: * @param entityClass the entity class
372: * @param id the id of the desired object
373: * @return the entity instance
374: * @param enforceReadOnly whether to always retrieve read-only objects from
375: * the plain TopLink Session (else, read-write objects will be retrieved
376: * from the TopLink UnitOfWork in case of a non-read-only transaction)
377: * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
378: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
379: * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
380: */
381: Object readById(Class entityClass, Object id,
382: boolean enforceReadOnly) throws DataAccessException;
383:
384: /**
385: * Read the entity instance of the given class with the given composite id,
386: * throwing an exception if not found.
387: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
388: * non-read-only transaction, and read-only objects else.
389: * @param entityClass the entity class
390: * @param keys the composite id elements of the desired object
391: * @return the entity instance
392: * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
393: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
394: * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
395: */
396: Object readById(Class entityClass, Object[] keys)
397: throws DataAccessException;
398:
399: /**
400: * Read the entity instance of the given class with the given composite id,
401: * throwing an exception if not found.
402: * @param entityClass the entity class
403: * @param keys the composite id elements of the desired object
404: * @param enforceReadOnly whether to always retrieve read-only objects from
405: * the plain TopLink Session (else, read-write objects will be retrieved
406: * from the TopLink UnitOfWork in case of a non-read-only transaction)
407: * @return the entity instance
408: * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
409: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
410: * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
411: */
412: Object readById(Class entityClass, Object[] keys,
413: boolean enforceReadOnly) throws DataAccessException;
414:
415: /**
416: * Read the entity instance of the given class with the given id,
417: * throwing an exception if not found. A detached copy of the entity object
418: * will be returned, allowing for modifications outside the current transaction,
419: * with the changes to be merged into a later transaction.
420: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
421: * non-read-only transaction, and read-only objects else.
422: * @param entityClass the entity class
423: * @param id the id of the desired object
424: * @return a copy of the entity instance
425: * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
426: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
427: * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
428: * @see oracle.toplink.sessions.Session#copyObject(Object)
429: */
430: Object readAndCopy(Class entityClass, Object id)
431: throws DataAccessException;
432:
433: /**
434: * Read the entity instance of the given class with the given id,
435: * throwing an exception if not found. A detached copy of the entity object
436: * will be returned, allowing for modifications outside the current transaction,
437: * with the changes to be merged into a later transaction.
438: * @param entityClass the entity class
439: * @param id the id of the desired object
440: * @param enforceReadOnly whether to always retrieve read-only objects from
441: * the plain TopLink Session (else, read-write objects will be retrieved
442: * from the TopLink UnitOfWork in case of a non-read-only transaction)
443: * @return a copy of the entity instance
444: * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
445: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
446: * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
447: * @see oracle.toplink.sessions.Session#copyObject(Object)
448: */
449: Object readAndCopy(Class entityClass, Object id,
450: boolean enforceReadOnly) throws DataAccessException;
451:
452: /**
453: * Read the entity instance of the given class with the given composite id,
454: * throwing an exception if not found. A detached copy of the entity object
455: * will be returned, allowing for modifications outside the current transaction,
456: * with the changes to be merged into a later transaction.
457: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
458: * non-read-only transaction, and read-only objects else.
459: * @param entityClass the entity class
460: * @param keys the composite id elements of the desired object
461: * @return a copy of the entity instance
462: * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
463: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
464: * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
465: * @see oracle.toplink.sessions.Session#copyObject(Object)
466: */
467: Object readAndCopy(Class entityClass, Object[] keys)
468: throws DataAccessException;
469:
470: /**
471: * Read the entity instance of the given class with the given composite id,
472: * throwing an exception if not found. A detached copy of the entity object
473: * will be returned, allowing for modifications outside the current transaction,
474: * with the changes to be merged into a later transaction.
475: * @param entityClass the entity class
476: * @param keys the composite id elements of the desired object
477: * @param enforceReadOnly whether to always retrieve read-only objects from
478: * the plain TopLink Session (else, read-write objects will be retrieved
479: * from the TopLink UnitOfWork in case of a non-read-only transaction)
480: * @return a copy of the entity instance
481: * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
482: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
483: * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
484: * @see oracle.toplink.sessions.Session#copyObject(Object)
485: */
486: Object readAndCopy(Class entityClass, Object[] keys,
487: boolean enforceReadOnly) throws DataAccessException;
488:
489: //-------------------------------------------------------------------------
490: // Convenience methods for copying and refreshing objects
491: //-------------------------------------------------------------------------
492:
493: /**
494: * Create a detached copy of the given entity object,
495: * using TopLink's default ObjectCopyingPolicy.
496: * @param entity the entity object to copy
497: * @return the copy of the entity object
498: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
499: * @see oracle.toplink.sessions.Session#copyObject(Object)
500: */
501: Object copy(Object entity) throws DataAccessException;
502:
503: /**
504: * Create a detached copy of the given entity object.
505: * @param entity the entity object to copy
506: * @param copyingPolicy the TopLink ObjectCopyingPolicy to apply
507: * @return the copy of the entity object
508: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
509: * @see oracle.toplink.sessions.Session#copyObject(Object, oracle.toplink.sessions.ObjectCopyingPolicy)
510: */
511: Object copy(Object entity, ObjectCopyingPolicy copyingPolicy)
512: throws DataAccessException;
513:
514: /**
515: * Create detached copies of all given entity objects,
516: * using TopLink's default ObjectCopyingPolicy.
517: * @param entities the entity objects to copy
518: * @return the copies of the entity objects
519: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
520: * @see oracle.toplink.sessions.Session#copyObject(Object)
521: */
522: List copyAll(Collection entities) throws DataAccessException;
523:
524: /**
525: * Create detached copies of all given entity objects.
526: * @param entities the entity objects to copy
527: * @param copyingPolicy the TopLink ObjectCopyingPolicy to apply
528: * @return the copies of the entity objects
529: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
530: * @see oracle.toplink.sessions.Session#copyObject(Object)
531: */
532: List copyAll(Collection entities, ObjectCopyingPolicy copyingPolicy)
533: throws DataAccessException;
534:
535: /**
536: * Refresh the given entity object, returning the refreshed object.
537: * <p>The returned object will only be different from the passed-in object
538: * if the passed-in object is not the currently registered version of
539: * the corresponding entity.
540: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
541: * non-read-only transaction, and read-only objects else.
542: * @param entity the entity object to refresh
543: * @return the refreshed version of the entity object
544: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
545: * @see oracle.toplink.sessions.Session#refreshObject(Object)
546: */
547: Object refresh(Object entity) throws DataAccessException;
548:
549: /**
550: * Refresh the given entity object, returning the refreshed object.
551: * <p>The returned object will only be different from the passed-in object
552: * if the passed-in object is not the currently registered version of
553: * the corresponding entity.
554: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
555: * non-read-only transaction, and read-only objects else.
556: * @param entity the entity object to refresh
557: * @param enforceReadOnly whether to always retrieve read-only objects from
558: * the plain TopLink Session (else, read-write objects will be retrieved
559: * from the TopLink UnitOfWork in case of a non-read-only transaction)
560: * @return the refreshed version of the entity object
561: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
562: * @see oracle.toplink.sessions.Session#refreshObject(Object)
563: */
564: Object refresh(Object entity, boolean enforceReadOnly)
565: throws DataAccessException;
566:
567: /**
568: * Refresh the given entity objects, returning the corresponding refreshed objects.
569: * <p>A returned object will only be different from the corresponding passed-in
570: * object if the passed-in object is not the currently registered version of
571: * the corresponding entity.
572: * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
573: * non-read-only transaction, and read-only objects else.
574: * @param entities the entity objects to refresh
575: * @return the refreshed versions of the entity objects
576: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
577: * @see oracle.toplink.sessions.Session#refreshObject(Object)
578: */
579: List refreshAll(Collection entities) throws DataAccessException;
580:
581: /**
582: * Refresh the given entity objects, returning the corresponding refreshed objects.
583: * <p>A returned object will only be different from the corresponding passed-in
584: * object if the passed-in object is not the currently registered version of
585: * the corresponding entity.
586: * @param entities the entity objects to refresh
587: * @param enforceReadOnly whether to always retrieve read-only objects from
588: * the plain TopLink Session (else, read-write objects will be retrieved
589: * from the TopLink UnitOfWork in case of a non-read-only transaction)
590: * @return the refreshed versions of the entity objects
591: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
592: * @see oracle.toplink.sessions.Session#refreshObject(Object)
593: */
594: List refreshAll(Collection entities, boolean enforceReadOnly)
595: throws DataAccessException;
596:
597: //-------------------------------------------------------------------------
598: // Convenience methods for persisting and deleting objects
599: //-------------------------------------------------------------------------
600:
601: /**
602: * Register the given (new or existing) entity with the current UnitOfWork.
603: * <p>The entity will be checked for existence, according to TopLink's
604: * configured existence checking policy. To avoid the (potentially costly)
605: * existence check, consider using the specific <code>registerNew</code>
606: * or <code>registerExisting</code> method.
607: * <b>Do not edit the passed-in object any further afterwards.</b>
608: * @param entity the entity to register
609: * @return the registered clone of the original object,
610: * which needs to be used for further editing
611: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
612: * @see oracle.toplink.sessions.UnitOfWork#registerObject(Object)
613: * @see #registerNew(Object)
614: * @see #registerExisting(Object)
615: */
616: Object register(Object entity);
617:
618: /**
619: * Register all given entities with the current UnitOfWork.
620: * <b>Do not edit the passed-in objects any further afterwards.</b>
621: * @param entities the entities to register
622: * @return the registered clones of the original objects,
623: * which need to be used for further editing
624: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
625: * @see oracle.toplink.sessions.UnitOfWork#registerAllObjects(java.util.Collection)
626: */
627: List registerAll(Collection entities);
628:
629: /**
630: * Register the given new entity with the current UnitOfWork.
631: * The passed-in object can be edited further afterwards.
632: * @param entity the new entity to register
633: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
634: * @see oracle.toplink.sessions.UnitOfWork#registerNewObject(Object)
635: */
636: void registerNew(Object entity);
637:
638: /**
639: * Register the given existing entity with the current UnitOfWork.
640: * <b>Do not edit the passed-in object any further afterwards.</b>
641: * @param entity the existing entity to register
642: * @return the registered clone of the original object,
643: * which needs to be used for further editing
644: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
645: * @see oracle.toplink.sessions.UnitOfWork#registerExistingObject(Object)
646: */
647: Object registerExisting(Object entity);
648:
649: /**
650: * Reassociate the given entity copy with the current UnitOfWork,
651: * using simple merging.
652: * <p>The given object will not be reassociated itself: instead, the state
653: * will be copied onto the persistent object with the same identifier.
654: * In case of a new entity, merge will copy to a registered object as well,
655: * but will also update the identifier of the passed-in object.
656: * @param entity the updated copy to merge
657: * @return the updated, registered persistent instance
658: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
659: * @see oracle.toplink.sessions.UnitOfWork#mergeClone(Object)
660: */
661: Object merge(Object entity) throws DataAccessException;
662:
663: /**
664: * Reassociate the given entity copy with the current UnitOfWork,
665: * using deep merging of all contained entities.
666: * <p>The given object will not be reassociated itself: instead, the state
667: * will be copied onto the persistent object with the same identifier.
668: * In case of a new entity, merge will register a copy as well,
669: * but will also update the identifier of the passed-in object.
670: * @param entity the updated copy to merge
671: * @return the updated, registered persistent instance
672: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
673: * @see oracle.toplink.sessions.UnitOfWork#deepMergeClone(Object)
674: */
675: Object deepMerge(Object entity) throws DataAccessException;
676:
677: /**
678: * Reassociate the given entity copy with the current UnitOfWork,
679: * using shallow merging of the entity instance.
680: * <p>The given object will not be reassociated itself: instead, the state
681: * will be copied onto the persistent object with the same identifier.
682: * In case of a new entity, merge will register a copy as well,
683: * but will also update the identifier of the passed-in object.
684: * @param entity the updated copy to merge
685: * @return the updated, registered persistent instance
686: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
687: * @see oracle.toplink.sessions.UnitOfWork#shallowMergeClone(Object)
688: */
689: Object shallowMerge(Object entity) throws DataAccessException;
690:
691: /**
692: * Reassociate the given entity copy with the current UnitOfWork,
693: * using merging with all references from this clone.
694: * <p>The given object will not be reassociated itself: instead, the state
695: * will be copied onto the persistent object with the same identifier.
696: * In case of a new entity, merge will register a copy as well,
697: * but will also update the identifier of the passed-in object.
698: * @param entity the updated copy to merge
699: * @return the updated, registered persistent instance
700: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
701: * @see oracle.toplink.sessions.UnitOfWork#mergeCloneWithReferences(Object)
702: */
703: Object mergeWithReferences(Object entity)
704: throws DataAccessException;
705:
706: /**
707: * Delete the given entity.
708: * @param entity the entity to delete
709: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
710: * @see oracle.toplink.sessions.UnitOfWork#deleteObject(Object)
711: */
712: void delete(Object entity) throws DataAccessException;
713:
714: /**
715: * Delete all given entities.
716: * @param entities the entities to delete
717: * @throws org.springframework.dao.DataAccessException in case of TopLink errors
718: * @see oracle.toplink.sessions.UnitOfWork#deleteAllObjects(java.util.Collection)
719: */
720: void deleteAll(Collection entities) throws DataAccessException;
721:
722: }
|