TopLinkOperations


1   /*
2    * Copyright 2002-2006 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.springframework.orm.toplink;
18  
19  import java.util.Collection  ;
20  import java.util.List  ;
21  
22  import oracle.toplink.expressions.Expression;
23  import oracle.toplink.queryframework.Call;
24  import oracle.toplink.queryframework.DatabaseQuery;
25  import oracle.toplink.sessions.ObjectCopyingPolicy;
26  
27  import org.springframework.dao.DataAccessException;
28  
29  /**
30   * Interface that specifies a basic set of TopLink operations,
31   * implemented by {@link TopLinkTemplate}. Not often used, but a useful
32   * option to enhance testability, as it can easily be mocked or stubbed.
33   *
34   * <p>Defines <code>TopLinkTemplate</code>'s data access methods that
35   * mirror various TopLink {@link oracle.toplink.sessions.Session} /
36   * {@link oracle.toplink.sessions.UnitOfWork} methods. Users are
37   * strongly encouraged to read the TopLink javadocs for details
38   * on the semantics of those methods.
39   *
40   * @author Juergen Hoeller
41   * @since 1.2
42   */
43  public interface TopLinkOperations {
44  
45      /**
46       * Execute the action specified by the given action object within a
47       * TopLink Session. Application exceptions thrown by the action object
48       * get propagated to the caller (can only be unchecked). TopLink exceptions
49       * are transformed into appropriate DAO ones. Allows for returning a
50       * result object, i.e. a domain object or a collection of domain objects.
51       * <p>Note: Callback code is not supposed to handle transactions itself!
52       * Use an appropriate transaction manager like TopLinkTransactionManager.
53       * @param action callback object that specifies the TopLink action
54       * @return a result object returned by the action, or <code>null</code>
55       * @throws org.springframework.dao.DataAccessException in case of TopLink errors
56       * @see TopLinkTransactionManager
57       * @see org.springframework.dao
58       * @see org.springframework.transaction
59       * @see oracle.toplink.sessions.Session
60       */
61      Object   execute(TopLinkCallback action) throws DataAccessException;
62  
63      /**
64       * Execute the specified action assuming that the result object is a
65       * Collection. This is a convenience method for executing TopLink queries
66       * within an action.
67       * @param action callback object that specifies the TopLink action
68       * @return a Collection result returned by the action, or <code>null</code>
69       * @throws org.springframework.dao.DataAccessException in case of TopLink errors
70       */
71      List   executeFind(TopLinkCallback action) throws DataAccessException;
72  
73  
74      //-------------------------------------------------------------------------
75      // Convenience methods for executing generic queries
76      //-------------------------------------------------------------------------
77  
78      /**
79       * Execute a given named query with the given arguments.
80       * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
81       * non-read-only transaction, and read-only objects else.
82       * @param entityClass the entity class that has the named query descriptor
83       * @param queryName the name of the query
84       * @return the result object or list of result objects for the query
85       * (can be cast to the entity class or Collection/List, respectively)
86       * @throws org.springframework.dao.DataAccessException in case of TopLink errors
87       * @see oracle.toplink.sessions.Session#executeQuery(String, Class)
88       */
89      Object   executeNamedQuery(Class   entityClass, String   queryName) throws DataAccessException;
90  
91      /**
92       * Execute a given named query with the given arguments.
93       * @param entityClass the entity class that has the named query descriptor
94       * @param queryName the name of the query
95       * @param enforceReadOnly whether to always retrieve read-only objects from
96       * the plain TopLink Session (else, read-write objects will be retrieved
97       * from the TopLink UnitOfWork in case of a non-read-only transaction)
98       * @return the result object or list of result objects for the query
99       * (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, boolean enforceReadOnly)
104             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, Object  [] args) throws DataAccessException;
119 
120     /**
121      * Execute a given named query with the given arguments.
122      * @param entityClass the entity class that has the named query descriptor
123      * @param queryName the name of the query
124      * @param args the arguments for the query (can be <code>null</code>)
125      * @param enforceReadOnly whether to always retrieve read-only objects from
126      * the plain TopLink Session (else, read-write objects will be retrieved
127      * from the TopLink UnitOfWork in case of a non-read-only transaction)
128      * @return the result object or list of result objects for the query
129      * (can be cast to the entity class or Collection/List, respectively)
130      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
131      * @see oracle.toplink.sessions.Session#executeQuery(String, Class, java.util.Vector)
132      */
133     Object   executeNamedQuery(Class   entityClass, String   queryName, Object  [] args, boolean enforceReadOnly)
134             throws DataAccessException;
135 
136     /**
137      * Execute the given query object with the given arguments.
138      * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
139      * non-read-only transaction, and read-only objects else.
140      * @param query the query object to execute (for example,
141      * a ReadObjectQuery or ReadAllQuery instance)
142      * @return the result object or list of result objects for the query
143      * (can be cast to the entity class or Collection/List, respectively)
144      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
145      * @see oracle.toplink.sessions.Session#executeQuery(oracle.toplink.queryframework.DatabaseQuery)
146      */
147     Object   executeQuery(DatabaseQuery query) throws DataAccessException;
148 
149     /**
150      * Execute the given query object with the given arguments.
151      * @param query the query object to execute (for example,
152      * a ReadObjectQuery or ReadAllQuery instance)
153      * @param enforceReadOnly whether to always retrieve read-only objects from
154      * the plain TopLink Session (else, read-write objects will be retrieved
155      * from the TopLink UnitOfWork in case of a non-read-only transaction)
156      * @return the result object or list of result objects for the query
157      * (can be cast to the entity class or Collection/List, respectively)
158      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
159      * @see oracle.toplink.sessions.Session#executeQuery(oracle.toplink.queryframework.DatabaseQuery)
160      */
161     Object   executeQuery(DatabaseQuery query, boolean enforceReadOnly) throws DataAccessException;
162 
163     /**
164      * Execute the given query object with the given arguments.
165      * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
166      * non-read-only transaction, and read-only objects else.
167      * @param query the query object to execute (for example,
168      * a ReadObjectQuery or ReadAllQuery instance)
169      * @param args the arguments for the query (can be <code>null</code>)
170      * @return the result object or list of result objects for the query
171      * (can be cast to the entity class or Collection/List, respectively)
172      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
173      * @see oracle.toplink.sessions.Session#executeQuery(oracle.toplink.queryframework.DatabaseQuery, java.util.Vector)
174      */
175     Object   executeQuery(DatabaseQuery query, Object  [] args) throws DataAccessException;
176 
177     /**
178      * Execute the given query object with the given arguments.
179      * @param query the query object to execute (for example,
180      * a ReadObjectQuery or ReadAllQuery instance)
181      * @param args the arguments for the query (can be <code>null</code>)
182      * @param enforceReadOnly whether to always retrieve read-only objects from
183      * the plain TopLink Session (else, read-write objects will be retrieved
184      * from the TopLink UnitOfWork in case of a non-read-only transaction)
185      * @return the result object or list of result objects for the query
186      * (can be cast to the entity class or Collection/List, respectively)
187      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
188      * @see oracle.toplink.sessions.Session#executeQuery(oracle.toplink.queryframework.DatabaseQuery, java.util.Vector)
189      */
190     Object   executeQuery(DatabaseQuery query, Object  [] args, boolean enforceReadOnly)
191             throws DataAccessException;
192 
193 
194     //-------------------------------------------------------------------------
195     // Convenience methods for reading a specific set of objects
196     //-------------------------------------------------------------------------
197 
198     /**
199      * Read all entity instances of the given class.
200      * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
201      * non-read-only transaction, and read-only objects else.
202      * @param entityClass the entity class
203      * @return the list of entity instances
204      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
205      * @see oracle.toplink.sessions.Session#readAllObjects(Class)
206      */
207     List   readAll(Class   entityClass) throws DataAccessException;
208 
209     /**
210      * Read all entity instances of the given class.
211      * @param entityClass the entity class
212      * @param enforceReadOnly whether to always retrieve read-only objects from
213      * the plain TopLink Session (else, read-write objects will be retrieved
214      * from the TopLink UnitOfWork in case of a non-read-only transaction)
215      * @return the list of entity instances
216      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
217      * @see oracle.toplink.sessions.Session#readAllObjects(Class)
218      */
219     List   readAll(Class   entityClass, boolean enforceReadOnly) throws DataAccessException;
220 
221     /**
222      * Read all entity instances of the given class that match the given expression.
223      * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
224      * non-read-only transaction, and read-only objects else.
225      * @param entityClass the entity class
226      * @param expression the TopLink expression to match,
227      * usually built through the TopLink ExpressionBuilder
228      * @return the list of matching entity instances
229      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
230      * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
231      * @see oracle.toplink.expressions.ExpressionBuilder
232      */
233     List   readAll(Class   entityClass, Expression expression) throws DataAccessException;
234 
235     /**
236      * Read all entity instances of the given class that match the given expression.
237      * @param entityClass the entity class
238      * @param expression the TopLink expression to match,
239      * usually built through the TopLink ExpressionBuilder
240      * @param enforceReadOnly whether to always retrieve read-only objects from
241      * the plain TopLink Session (else, read-write objects will be retrieved
242      * from the TopLink UnitOfWork in case of a non-read-only transaction)
243      * @return the list of matching entity instances
244      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
245      * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
246      * @see oracle.toplink.expressions.ExpressionBuilder
247      */
248     List   readAll(Class   entityClass, Expression expression, boolean enforceReadOnly)
249             throws DataAccessException;
250 
251     /**
252      * Read all entity instances of the given class, as returned by the given call.
253      * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
254      * non-read-only transaction, and read-only objects else.
255      * @param entityClass the entity class
256      * @param call the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
257      * @return the list of matching entity instances
258      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
259      * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.queryframework.Call)
260      * @see oracle.toplink.queryframework.SQLCall
261      * @see oracle.toplink.queryframework.EJBQLCall
262      */
263     List   readAll(Class   entityClass, Call call) throws DataAccessException;
264 
265     /**
266      * Read all entity instances of the given class, as returned by the given call.
267      * @param entityClass the entity class
268      * @param call the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
269      * @param enforceReadOnly whether to always retrieve read-only objects from
270      * the plain TopLink Session (else, read-write objects will be retrieved
271      * from the TopLink UnitOfWork in case of a non-read-only transaction)
272      * @return the list of matching entity instances
273      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
274      * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
275      * @see oracle.toplink.queryframework.SQLCall
276      * @see oracle.toplink.queryframework.EJBQLCall
277      */
278     List   readAll(Class   entityClass, Call call, boolean enforceReadOnly) throws DataAccessException;
279 
280     /**
281      * Read an entity instance of the given class that matches the given expression.
282      * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
283      * non-read-only transaction, and read-only objects else.
284      * @param entityClass the entity class
285      * @param expression the TopLink expression to match,
286      * usually built through the TopLink ExpressionBuilder
287      * @return the matching entity instance, or <code>null</code> if none found
288      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
289      * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
290      * @see oracle.toplink.expressions.ExpressionBuilder
291      */
292     Object   read(Class   entityClass, Expression expression) throws DataAccessException;
293 
294     /**
295      * Read an entity instance of the given class that matches the given expression.
296      * @param entityClass the entity class
297      * @param expression the TopLink expression to match,
298      * usually built through the TopLink ExpressionBuilder
299      * @param enforceReadOnly whether to always retrieve read-only objects from
300      * the plain TopLink Session (else, read-write objects will be retrieved
301      * from the TopLink UnitOfWork in case of a non-read-only transaction)
302      * @return a matching entity instance, or <code>null</code> if none found
303      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
304      * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
305      * @see oracle.toplink.expressions.ExpressionBuilder
306      */
307     Object   read(Class   entityClass, Expression expression, boolean enforceReadOnly)
308             throws DataAccessException;
309 
310     /**
311      * Read an entity instance of the given class, as returned by the given call.
312      * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
313      * non-read-only transaction, and read-only objects else.
314      * @param entityClass the entity class
315      * @param call the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
316      * @return a matching entity instance, or <code>null</code> if none found
317      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
318      * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.queryframework.Call)
319      * @see oracle.toplink.queryframework.SQLCall
320      * @see oracle.toplink.queryframework.EJBQLCall
321      */
322     Object   read(Class   entityClass, Call call) throws DataAccessException;
323 
324     /**
325      * Read an entity instance of the given class, as returned by the given call.
326      * @param entityClass the entity class
327      * @param call the TopLink Call object to apply (either a SQLCall or an EJBQLCall)
328      * @param enforceReadOnly whether to always retrieve read-only objects from
329      * the plain TopLink Session (else, read-write objects will be retrieved
330      * from the TopLink UnitOfWork in case of a non-read-only transaction)
331      * @return a matching entity instance, or <code>null</code> if none found
332      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
333      * @see oracle.toplink.sessions.Session#readAllObjects(Class, oracle.toplink.expressions.Expression)
334      * @see oracle.toplink.queryframework.SQLCall
335      * @see oracle.toplink.queryframework.EJBQLCall
336      */
337     Object   read(Class   entityClass, Call call, boolean enforceReadOnly)
338             throws DataAccessException;
339 
340 
341     //-------------------------------------------------------------------------
342     // Convenience methods for reading an individual object by id
343     //-------------------------------------------------------------------------
344 
345     /**
346      * Read the entity instance of the given class with the given id,
347      * throwing an exception if not found.
348      * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
349      * non-read-only transaction, and read-only objects else.
350      * @param entityClass the entity class
351      * @param id the id of the desired object
352      * @return the entity instance
353      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
354      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
355      * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
356      */
357     Object   readById(Class   entityClass, Object   id) throws DataAccessException;
358 
359     /**
360      * Read the entity instance of the given class with the given id,
361      * throwing an exception if not found.
362      * @param entityClass the entity class
363      * @param id the id of the desired object
364      * @return the entity instance
365      * @param enforceReadOnly whether to always retrieve read-only objects from
366      * the plain TopLink Session (else, read-write objects will be retrieved
367      * from the TopLink UnitOfWork in case of a non-read-only transaction)
368      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
369      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
370      * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
371      */
372     Object   readById(Class   entityClass, Object   id, boolean enforceReadOnly) throws DataAccessException;
373 
374     /**
375      * Read the entity instance of the given class with the given composite id,
376      * throwing an exception if not found.
377      * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
378      * non-read-only transaction, and read-only objects else.
379      * @param entityClass the entity class
380      * @param keys the composite id elements of the desired object
381      * @return the entity instance
382      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
383      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
384      * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
385      */
386     Object   readById(Class   entityClass, Object  [] keys) throws DataAccessException;
387 
388     /**
389      * Read the entity instance of the given class with the given composite id,
390      * throwing an exception if not found.
391      * @param entityClass the entity class
392      * @param keys the composite id elements of the desired object
393      * @param enforceReadOnly whether to always retrieve read-only objects from
394      * the plain TopLink Session (else, read-write objects will be retrieved
395      * from the TopLink UnitOfWork in case of a non-read-only transaction)
396      * @return the entity instance
397      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
398      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
399      * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
400      */
401     Object   readById(Class   entityClass, Object  [] keys, boolean enforceReadOnly) throws DataAccessException;
402 
403     /**
404      * Read the entity instance of the given class with the given id,
405      * throwing an exception if not found. A detached copy of the entity object
406      * will be returned, allowing for modifications outside the current transaction,
407      * with the changes to be merged into a later transaction.
408      * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
409      * non-read-only transaction, and read-only objects else.
410      * @param entityClass the entity class
411      * @param id the id of the desired object
412      * @return a copy of the entity instance
413      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
414      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
415      * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
416      * @see oracle.toplink.sessions.Session#copyObject(Object)
417      */
418     Object   readAndCopy(Class   entityClass, Object   id) throws DataAccessException;
419 
420     /**
421      * Read the entity instance of the given class with the given id,
422      * throwing an exception if not found. A detached copy of the entity object
423      * will be returned, allowing for modifications outside the current transaction,
424      * with the changes to be merged into a later transaction.
425      * @param entityClass the entity class
426      * @param id the id of the desired object
427      * @param enforceReadOnly whether to always retrieve read-only objects from
428      * the plain TopLink Session (else, read-write objects will be retrieved
429      * from the TopLink UnitOfWork in case of a non-read-only transaction)
430      * @return a copy of the entity instance
431      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
432      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
433      * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
434      * @see oracle.toplink.sessions.Session#copyObject(Object)
435      */
436     Object   readAndCopy(Class   entityClass, Object   id, boolean enforceReadOnly) throws DataAccessException;
437 
438     /**
439      * Read the entity instance of the given class with the given composite id,
440      * throwing an exception if not found. A detached copy of the entity object
441      * will be returned, allowing for modifications outside the current transaction,
442      * with the changes to be merged into a later transaction.
443      * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
444      * non-read-only transaction, and read-only objects else.
445      * @param entityClass the entity class
446      * @param keys the composite id elements of the desired object
447      * @return a copy of the entity instance
448      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
449      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
450      * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
451      * @see oracle.toplink.sessions.Session#copyObject(Object)
452      */
453     Object   readAndCopy(Class   entityClass, Object  [] keys) throws DataAccessException;
454 
455     /**
456      * Read the entity instance of the given class with the given composite id,
457      * throwing an exception if not found. A detached copy of the entity object
458      * will be returned, allowing for modifications outside the current transaction,
459      * with the changes to be merged into a later transaction.
460      * @param entityClass the entity class
461      * @param keys the composite id elements of the desired object
462      * @param enforceReadOnly whether to always retrieve read-only objects from
463      * the plain TopLink Session (else, read-write objects will be retrieved
464      * from the TopLink UnitOfWork in case of a non-read-only transaction)
465      * @return a copy of the entity instance
466      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
467      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
468      * @see oracle.toplink.queryframework.ReadObjectQuery#setSelectionKey(java.util.Vector)
469      * @see oracle.toplink.sessions.Session#copyObject(Object)
470      */
471     Object   readAndCopy(Class   entityClass, Object  [] keys, boolean enforceReadOnly) throws DataAccessException;
472 
473 
474     //-------------------------------------------------------------------------
475     // Convenience methods for copying and refreshing objects
476     //-------------------------------------------------------------------------
477 
478     /**
479      * Create a detached copy of the given entity object,
480      * using TopLink's default ObjectCopyingPolicy.
481      * @param entity the entity object to copy
482      * @return the copy of the entity object
483      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
484      * @see oracle.toplink.sessions.Session#copyObject(Object)
485      */
486     Object   copy(Object   entity) throws DataAccessException;
487 
488     /**
489      * Create a detached copy of the given entity object.
490      * @param entity the entity object to copy
491      * @param copyingPolicy the TopLink ObjectCopyingPolicy to apply
492      * @return the copy of the entity object
493      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
494      * @see oracle.toplink.sessions.Session#copyObject(Object, oracle.toplink.sessions.ObjectCopyingPolicy)
495      */
496     Object   copy(Object   entity, ObjectCopyingPolicy copyingPolicy) throws DataAccessException;
497 
498     /**
499      * Create detached copies of all given entity objects,
500      * using TopLink's default ObjectCopyingPolicy.
501      * @param entities the entity objects to copy
502      * @return the copies of the entity objects
503      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
504      * @see oracle.toplink.sessions.Session#copyObject(Object)
505      */
506     List   copyAll(Collection   entities) throws DataAccessException;
507 
508     /**
509      * Create detached copies of all given entity objects.
510      * @param entities the entity objects to copy
511      * @param copyingPolicy the TopLink ObjectCopyingPolicy to apply
512      * @return the copies of the entity objects
513      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
514      * @see oracle.toplink.sessions.Session#copyObject(Object)
515      */
516     List   copyAll(Collection   entities, ObjectCopyingPolicy copyingPolicy) throws DataAccessException;
517 
518     /**
519      * Refresh the given entity object, returning the refreshed object.
520      * <p>The returned object will only be different from the passed-in object
521      * if the passed-in object is not the currently registered version of
522      * the corresponding entity.
523      * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
524      * non-read-only transaction, and read-only objects else.
525      * @param entity the entity object to refresh
526      * @return the refreshed version of the entity object
527      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
528      * @see oracle.toplink.sessions.Session#refreshObject(Object)
529      */
530     Object   refresh(Object   entity) throws DataAccessException;
531 
532     /**
533      * Refresh the given entity object, returning the refreshed object.
534      * <p>The returned object will only be different from the passed-in object
535      * if the passed-in object is not the currently registered version of
536      * the corresponding entity.
537      * <p>Retrieves read-write objects from the TopLink UnitOfWork in case of a
538      * non-read-only transaction, and read-only objects else.
539      * @param entity the entity object to refresh
540      * @param enforceReadOnly whether to always retrieve read-only objects from
541      * the plain TopLink Session (else, read-write objects will be retrieved
542      * from the TopLink UnitOfWork in case of a non-read-only transaction)
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, boolean enforceReadOnly) throws DataAccessException;
548 
549     /**
550      * Refresh the given entity objects, returning the corresponding refreshed objects.
551      * <p>A returned object will only be different from the corresponding passed-in
552      * object 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 entities the entity objects to refresh
557      * @return the refreshed versions of the entity objects
558      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
559      * @see oracle.toplink.sessions.Session#refreshObject(Object)
560      */
561     List   refreshAll(Collection   entities) throws DataAccessException;
562 
563     /**
564      * Refresh the given entity objects, returning the corresponding refreshed objects.
565      * <p>A returned object will only be different from the corresponding passed-in
566      * object if the passed-in object is not the currently registered version of
567      * the corresponding entity.
568      * @param entities the entity objects to refresh
569      * @param enforceReadOnly whether to always retrieve read-only objects from
570      * the plain TopLink Session (else, read-write objects will be retrieved
571      * from the TopLink UnitOfWork in case of a non-read-only transaction)
572      * @return the refreshed versions of the entity objects
573      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
574      * @see oracle.toplink.sessions.Session#refreshObject(Object)
575      */
576     List   refreshAll(Collection   entities, boolean enforceReadOnly) throws DataAccessException;
577 
578 
579     //-------------------------------------------------------------------------
580     // Convenience methods for persisting and deleting objects
581     //-------------------------------------------------------------------------
582 
583     /**
584      * Register the given (new or existing) entity with the current UnitOfWork.
585      * <p>The entity will be checked for existence, according to TopLink's
586      * configured existence checking policy. To avoid the (potentially costly)
587      * existence check, consider using the specific <code>registerNew</code>
588      * or <code>registerExisting</code> method.
589      * <b>Do not edit the passed-in object any further afterwards.</b>
590      * @param entity the entity to register
591      * @return the registered clone of the original object,
592      * which needs to be used for further editing
593      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
594      * @see oracle.toplink.sessions.UnitOfWork#registerObject(Object)
595      * @see #registerNew(Object)
596      * @see #registerExisting(Object)
597      */
598     Object   register(Object   entity);
599 
600     /**
601      * Register all given entities with the current UnitOfWork.
602      * <b>Do not edit the passed-in objects any further afterwards.</b>
603      * @param entities the entities to register
604      * @return the registered clones of the original objects,
605      * which need to be used for further editing
606      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
607      * @see oracle.toplink.sessions.UnitOfWork#registerAllObjects(java.util.Collection)
608      */
609     List   registerAll(Collection   entities);
610 
611     /**
612      * Register the given new entity with the current UnitOfWork.
613      * The passed-in object can be edited further afterwards.
614      * @param entity the new entity to register
615      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
616      * @see oracle.toplink.sessions.UnitOfWork#registerNewObject(Object)
617      */
618     void registerNew(Object   entity);
619 
620     /**
621      * Register the given existing entity with the current UnitOfWork.
622      * <b>Do not edit the passed-in object any further afterwards.</b>
623      * @param entity the existing entity to register
624      * @return the registered clone of the original object,
625      * which needs to be used for further editing
626      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
627      * @see oracle.toplink.sessions.UnitOfWork#registerExistingObject(Object)
628      */
629     Object   registerExisting(Object   entity);
630 
631     /**
632      * Reassociate the given entity copy with the current UnitOfWork,
633      * using simple merging.
634      * <p>The given object will not be reassociated itself: instead, the state
635      * will be copied onto the persistent object with the same identifier.
636      * In case of a new entity, merge will copy to a registered object as well,
637      * but will also update the identifier of the passed-in object.
638      * @param entity the updated copy to merge
639      * @return the updated, registered persistent instance
640      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
641      * @see oracle.toplink.sessions.UnitOfWork#mergeClone(Object)
642      */
643     Object   merge(Object   entity) throws DataAccessException;
644 
645     /**
646      * Reassociate the given entity copy with the current UnitOfWork,
647      * using deep merging of all contained entities.
648      * <p>The given object will not be reassociated itself: instead, the state
649      * will be copied onto the persistent object with the same identifier.
650      * In case of a new entity, merge will register a copy as well,
651      * but will also update the identifier of the passed-in object.
652      * @param entity the updated copy to merge
653      * @return the updated, registered persistent instance
654      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
655      * @see oracle.toplink.sessions.UnitOfWork#deepMergeClone(Object)
656      */
657     Object   deepMerge(Object   entity) throws DataAccessException;
658 
659     /**
660      * Reassociate the given entity copy with the current UnitOfWork,
661      * using shallow merging of the entity instance.
662      * <p>The given object will not be reassociated itself: instead, the state
663      * will be copied onto the persistent object with the same identifier.
664      * In case of a new entity, merge will register a copy as well,
665      * but will also update the identifier of the passed-in object.
666      * @param entity the updated copy to merge
667      * @return the updated, registered persistent instance
668      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
669      * @see oracle.toplink.sessions.UnitOfWork#shallowMergeClone(Object)
670      */
671     Object   shallowMerge(Object   entity) throws DataAccessException;
672 
673     /**
674      * Reassociate the given entity copy with the current UnitOfWork,
675      * using merging with all references from this clone.
676      * <p>The given object will not be reassociated itself: instead, the state
677      * will be copied onto the persistent object with the same identifier.
678      * In case of a new entity, merge will register a copy as well,
679      * but will also update the identifier of the passed-in object.
680      * @param entity the updated copy to merge
681      * @return the updated, registered persistent instance
682      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
683      * @see oracle.toplink.sessions.UnitOfWork#mergeCloneWithReferences(Object)
684      */
685     Object   mergeWithReferences(Object   entity) throws DataAccessException;
686 
687     /**
688      * Delete the given entity.
689      * @param entity the entity to delete
690      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
691      * @see oracle.toplink.sessions.UnitOfWork#deleteObject(Object)
692      */
693     void delete(Object   entity) throws DataAccessException;
694 
695     /**
696      * Delete all given entities.
697      * @param entities the entities to delete
698      * @throws org.springframework.dao.DataAccessException in case of TopLink errors
699      * @see oracle.toplink.sessions.UnitOfWork#deleteAllObjects(java.util.Collection)
700      */
701     void deleteAll(Collection   entities) throws DataAccessException;
702 
703 }
704
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags