UnitOfWork


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the "License").  You may not use this file except 
5    * in compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * glassfish/bootstrap/legal/CDDLv1.0.txt or 
9    * https://glassfish.dev.java.net/public/CDDLv1.0.html. 
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * HEADER in each file and include the License file at 
15   * glassfish/bootstrap/legal/CDDLv1.0.txt.  If applicable, 
16   * add the following below this CDDL HEADER, with the 
17   * fields enclosed by brackets "[]" replaced with your 
18   * own identifying information: Portions Copyright [yyyy] 
19   * [name of copyright owner]
20   */
21  // Copyright (c) 1998, 2005, Oracle. All rights reserved.  
22  package oracle.toplink.essentials.sessions;
23  
24  import java.util.*;
25  import oracle.toplink.essentials.exceptions.*;
26  import oracle.toplink.essentials.changesets.UnitOfWorkChangeSet;
27  
28  /**
29   * <b>Purpose</b>: To allow object level transactions.  This class represents the public API of the
30   * unit of work and should be used to maintain complete compatibility.
31   * <p>
32   * <b>Description</b>: The unit of work is a session that implements all of the normal
33   * protocol of a TopLink session. It can be spawned from any other session including another unit of work.
34   * Objects can be brought into the unit of work through reading them or through registering them.
35   * The unit of work will opperate on its own object space, that is the objects within the unit of work
36   * will be clones of the orignial objects.  When the unit of work is commited, all changes to any objects
37   * registered within the unit of work will be commited to the database.  A minimal commit/update will
38   * be performed and any foreign keys/circular reference/referencial integrity will be resolved.
39   * If the commit to the database is successful the changed objects will be merged back into the unit of work
40   * parent session.
41   * <p>
42   * <b>Responsibilities</b>:
43   * <ul>
44   * <li> Allow parallel transactions against a session's objects.
45   * <li> Allow nested transactions.
46   * <li> Not require the application to write objects that is changes, automatically determine what has changed.
47   * <li> Perform a minimal commit/update of all changes that occured.
48   * <li> Resolve foreign keys for newly created objects and maintain referencial integrity.
49   * <li> Allow for the object transaction to use its own object space.
50   * </ul>
51   */
52  public interface UnitOfWork extends Session {
53  
54      /**
55       * PUBLIC:
56       * Adds the given Java class to the receiver's set of read-only classes.
57       * Cannot be called after objects have been registered in the unit of work.
58       */
59      public void addReadOnlyClass(Class   theClass);
60  
61      /**
62       * PUBLIC:
63       * Adds the classes in the given Vector to the existing set of read-only classes.
64       * Cannot be called after objects have been registered in the unit of work.
65       */
66      public void addReadOnlyClasses(Vector classes);
67  
68      /**
69       * ADVANCED:
70       * Assign sequence number to the object.
71       * This allows for an object's id to be assigned before commit.
72       * It can be used if the application requires to use the object id before the object exists on the database.
73       * Normally all ids are assigned during the commit automatically.
74       */
75      public void assignSequenceNumber(Object   object) throws DatabaseException;
76  
77      /**
78       * ADVANCED:
79       * Assign sequence numbers to all new objects registered in this unit of work,
80       * or any new objects reference by any objects registered.
81       * This allows for an object's id to be assigned before commit.
82       * It can be used if the application requires to use the object id before the object exists on the database.
83       * Normally all ids are assigned during the commit automatically.
84       */
85      public void assignSequenceNumbers() throws DatabaseException;
86  
87      /**
88       * PUBLIC:
89       * Tell the unit of work to begin a transaction now.
90       * By default the unit of work will begin a transaction at commit time.
91       * The default is the recommended approach, however sometimes it is
92       * neccessary to start the transaction before commit time.  When the
93       * unit of work commits, this transcation will be commited.
94       *
95       * @see #commit()
96       * @see #release()
97       */
98      public void beginEarlyTransaction() throws DatabaseException;
99  
100     /**
101      * PUBLIC:
102      * Commit the unit of work to its parent.
103      * For a nested unit of work this will merge any changes to its objects
104      * with its parents.
105      * For a first level unit of work it will commit all changes to its objects
106      * to the database as a single transaction.  If successful the changes to its
107      * objects will be merged to its parent's objects.  If the commit fails the database
108      * transaction will be rolledback, and the unit of work will be released.
109      * If the commit is successful the unit of work is released, and a new unit of work
110      * must be acquired if further changes are desired.
111      *
112      * @see #commitAndResumeOnFailure()
113      * @see #commitAndResume()
114      * @see #release()
115      */
116     public void commit() throws DatabaseException, OptimisticLockException;
117 
118     /**
119      * PUBLIC:
120      * Commit the unit of work to its parent.
121      * For a nested unit of work this will merge any changes to its objects
122      * with its parents.
123      * For a first level unit of work it will commit all changes to its objects
124      * to the database as a single transaction.  If successful the changes to its
125      * objects will be merged to its parent's objects.  If the commit fails the database
126      * transaction will be rolledback, and the unit of work will be released.
127      * The normal commit releases the unit of work, forcing a new one to be acquired if further changes are desired.
128      * The resuming feature allows for the same unit of work (and working copies) to be continued to be used.
129      *
130      * @see #commitAndResumeOnFailure()
131      * @see #commit()
132      * @see #release()
133      */
134     public void commitAndResume() throws DatabaseException, OptimisticLockException;
135 
136     /**
137      * PUBLIC:
138      * Commit the unit of work to its parent.
139      * For a nested unit of work this will merge any changes to its objects
140      * with its parents.
141      * For a first level unit of work it will commit all changes to its objects
142      * to the database as a single transaction.  If successful the changes to its
143      * objects will be merged to its parent's objects.  If the commit fails the database
144      * transaction will be rolledback, but the unit of work will remain active.
145      * It can then be retried or released.
146      * The normal commit failure releases the unit of work, forcing a new one to be acquired if further changes are desired.
147      * The resuming feature allows for the same unit of work (and working copies) to be continued to be used if an error occurs.
148      *
149      * @see #commit()
150      * @see #release()
151      */
152     public void commitAndResumeOnFailure() throws DatabaseException, OptimisticLockException;
153 
154     /**
155      * PUBLIC:
156      * Merge the attributes of the clone into the unit of work copy.
157      * This can be used for objects that are returned from the client through
158      * RMI serialization or other serialization mechanisms, because the RMI object will
159      * be a clone this will merge its attributes correctly to preserve object identity
160      * within the unit of work and record its changes.
161      * Everything connected to this object (i.e. the entire object tree where rmiClone
162      * is the root) is also merged.
163      *
164      * @return the registered version for the clone being merged.
165      * @see #mergeClone(Object)
166      * @see #shallowMergeClone(Object)
167      */
168     public Object   deepMergeClone(Object   rmiClone);
169 
170     /**
171      * PUBLIC:
172      * Revert the object's attributes from the parent.
173      * This reverts everything the object references.
174      *
175      * @return the object reverted.
176      * @see #revertObject(Object)
177      * @see #shallowRevertObject(Object)
178      */
179     public Object   deepRevertObject(Object   clone);
180 
181     /**
182      * ADVANCED:
183      * Unregister the object with the unit of work.
184      * This can be used to delete an object that was just created and is not yet persistent.
185      * Delete object can also be used, but will result in inserting the object and then deleting it.
186      * The method should be used carefully because it will delete all the reachable parts.
187      */
188     public void deepUnregisterObject(Object   clone);
189 
190     /**
191      * PUBLIC:
192      * Delete all of the objects and all of their privately owned parts in the database.
193      * Delete operations are delayed in a unit of work until commit.
194      */
195     public void deleteAllObjects(Collection domainObjects);
196 
197     /**
198      * PUBLIC:
199      * Delete all of the objects and all of their privately owned parts in the database.
200      * Delete operations are delayed in a unit of work until commit.
201      */
202     public void deleteAllObjects(Vector domainObjects);
203 
204     /**
205      * PUBLIC:
206      * Delete the object and all of their privately owned parts in the database.
207      * Delete operations are delayed in a unit of work until commit.
208      */
209     public Object   deleteObject(Object   domainObject);
210 
211     /**
212      * ADVANCED:
213      * The unit of work performs validations such as,
214      * ensuring multiple copies of the same object don't exist in the same unit of work,
215      * ensuring deleted objects are not refered after commit,
216      * ensures that objects from the parent cache are not refered in the unit of work cache.
217      * The level of validation can be increased or decreased for debugging purposes or under
218      * advanced situation where the application requires/desires to violate clone identity in the unit of work.
219      * It is strongly suggested that clone identity not be violate in the unit of work.
220      */
221     public void dontPerformValidation();
222 
223     /**
224      * ADVANCED:
225      * Set optmistic read lock on the object.  This feature is overide by normal optimistic lock.
226      * when the object is changed in UnitOfWork. The cloneFromUOW must be the clone of from this
227      * UnitOfWork and it must implements version locking or timestamp locking.
228      * The SQL would look like the followings.
229      *
230      * If shouldModifyVersionField is true,
231      * "UPDATE EMPLOYEE SET VERSION = 2 WHERE EMP_ID = 9 AND VERSION = 1"
232      *
233      * If shouldModifyVersionField is false,
234      * "UPDATE EMPLOYEE SET VERSION = 1 WHERE EMP_ID = 9 AND VERSION = 1"
235      */
236     public void forceUpdateToVersionField(Object   cloneFromUOW, boolean shouldModifyVersionField);
237 
238     /**
239      * ADVANCED:
240      * This method Will Calculate the chages for the UnitOfWork.  Without assigning sequence numbers
241      * This is a Computationaly intensive operation and should be avoided unless necessary.
242      * A valid changeSet, with sequencenumbers can be collected from the UnitOfWork After the commit
243      * is complete by calling unitOfWork.getUnitOfWorkChangeSet()
244      */
245     public UnitOfWorkChangeSet getCurrentChanges();
246 
247     /**
248      * ADVANCED:
249      * Return the original version of the object(clone) from the parent's identity map.
250      */
251     public Object   getOriginalVersionOfObject(Object   workingClone);
252 
253     /**
254      * PUBLIC:
255      * Return the parent.
256      * This is a unit of work if nested, otherwise a database session or client session.
257      */
258     public oracle.toplink.essentials.internal.sessions.AbstractSession getParent();
259 
260     /**
261      * ADVANCED:
262      * Returns the currentChangeSet from the UnitOfWork.
263      * This is only valid after the UnitOfWOrk has commited successfully
264      */
265     public oracle.toplink.essentials.changesets.UnitOfWorkChangeSet getUnitOfWorkChangeSet();
266 
267     /**
268      * ADVANCED:
269      * The unit of work performs validations such as,
270      * ensuring multiple copies of the same object don't exist in the same unit of work,
271      * ensuring deleted objects are not refered after commit,
272      * ensures that objects from the parent cache are not refered in the unit of work cache.
273      * The level of validation can be increased or decreased for debugging purposes or under
274      * advanced situation where the application requires/desires to violate clone identity in the unit of work.
275      * It is strongly suggested that clone identity not be violate in the unit of work.
276      */
277     public int getValidationLevel();
278 
279     /**
280      * ADVANCED:
281      * The Unit of work is capable of preprocessing to determine if any on the clone have been changed.
282      * This is computationaly expensive and should be avoided on large object graphs.
283       */
284     public boolean hasChanges();
285 
286     /**
287      * PUBLIC:
288      * Return if the unit of work is active (has not been released).
289      */
290     public boolean isActive();
291     
292     /**
293      * PUBLIC:
294      * Checks to see if the specified class is read-only or not in this UnitOfWork.
295      *
296      * @return true if the class is read-only, false otherwise.
297      */
298     public boolean isClassReadOnly(Class   theClass);
299 
300     /**
301      * ADVANCED:
302      * Return if this session is a nested unit of work.
303      */
304     public boolean isNestedUnitOfWork();
305 
306     /**
307      * PUBLIC:
308      * Merge the attributes of the clone into the unit of work copy.
309      * This can be used for objects that are returned from the client through
310      * RMI serialization (or another serialization mechanism), because the RMI object
311      * will be a clone this will merge its attributes correctly to preserve object
312      * identity within the unit of work and record its changes.
313      *
314      * The object and its private owned parts are merged.
315      *
316      * @return the registered version for the clone being merged.
317      * @see #shallowMergeClone(Object)
318      * @see #deepMergeClone(Object)
319      */
320     public Object   mergeClone(Object   rmiClone);
321 
322     /**
323      * PUBLIC:
324      * Merge the attributes of the clone into the unit of work copy.
325      * This can be used for objects that are returned from the client through
326      * RMI serialization (or another serialization mechanism), because the RMI object
327      * will be a clone this will merge its attributes correctly to preserve object
328      * identity within the unit of work and record its changes.
329      *
330      * The object and its private owned parts are merged. This will include
331      * references from this clone to independent objects.
332      *
333      * @return the registered version for the clone being merged.
334      * @see #shallowMergeClone(Object)
335      * @see #deepMergeClone(Object)
336      */
337     public Object   mergeCloneWithReferences(Object   rmiClone);
338 
339     /**
340      * PUBLIC:
341      * Return a new instance of the class registered in this unit of work.
342      * This can be used to ensure that new objects are registered correctly.
343      */
344     public Object   newInstance(Class   theClass);
345 
346     /**
347      * ADVANCED:
348      * The unit of work performs validations such as,
349      * ensuring multiple copies of the same object don't exist in the same unit of work,
350      * ensuring deleted objects are not refered after commit,
351      * ensures that objects from the parent cache are not refered in the unit of work cache.
352      * The level of validation can be increased or decreased for debugging purposes or under
353      * advanced situation where the application requires/desires to violate clone identity in the unit of work.
354      * It is strongly suggested that clone identity not be violate in the unit of work.
355      */
356     public void performFullValidation();
357 
358     /**
359      * ADVANCED:
360      * The unit of work performs validations such as,
361      * ensuring multiple copies of the same object don't exist in the same unit of work,
362      * ensuring deleted objects are not refered after commit,
363      * ensures that objects from the parent cache are not refered in the unit of work cache.
364      * The level of validation can be increased or decreased for debugging purposes or under
365      * advanced situation where the application requires/desires to violate clone identity in the unit of work.
366      * It is strongly suggested that clone identity not be violate in the unit of work.
367      */
368     public void performPartialValidation();
369 
370     /**
371      * PUBLIC:
372      * Print the objects in the unit of work.
373      */
374     public void printRegisteredObjects();
375 
376     /**
377      * PUBLIC:
378      * Refresh the attributes of the object and of all of its private parts from the database.
379      * The object will be pessimisticly locked on the database for the duration of the transaction.
380      * If the object is already locked this method will wait until the lock is released.
381      * A no wait option is available through setting the lock mode.
382      * @see #refreshAndLockObject(Object, lockMode)
383      */
384     public Object   refreshAndLockObject(Object   object);
385 
386     /**
387      * PUBLIC:
388      * Refresh the attributes of the object and of all of its private parts from the database.
389      * The object will be pessimisticly locked on the database for the duration of the transaction.
390      * <p>Lock Modes: ObjectBuildingQuery.NO_LOCK, LOCK, LOCK_NOWAIT
391      */
392     public Object   refreshAndLockObject(Object   object, short lockMode);
393 
394     /**
395      * PUBLIC:
396      * Register the objects with the unit of work.
397      * All newly created root domain objects must be registered to be inserted on commit.
398      * Also any existing objects that will be edited and were not read from this unit of work
399      * must also be registered.
400      * Once registered any changes to the objects will be commited to the database on commit.
401      *
402      * @return is the clones of the original objects, the return value must be used for editing,
403      * editing the original is not allowed in the unit of work.
404      */
405     public Vector registerAllObjects(Collection domainObjects);
406 
407     /**
408      * PUBLIC:
409      * Register the objects with the unit of work.
410      * All newly created root domain objects must be registered to be inserted on commit.
411      * Also any existing objects that will be edited and were not read from this unit of work
412      * must also be registered.
413      * Once registered any changes to the objects will be commited to the database on commit.
414      *
415      * @return is the clones of the original objects, the return value must be used for editing,
416      * editing the original is not allowed in the unit of work.
417      */
418     public Vector registerAllObjects(Vector domainObjects);
419 
420     /**
421      * ADVANCED:
422      * Register the existing object with the unit of work.
423      * This is a advanced API that can be used if the application can guarentee the object exists on the database.
424      * When registerObject is called the unit of work determines existence through the descriptor's doesExist setting.
425      *
426      * @return The clone of the original object, the return value must be used for editing.
427      * Editing the original is not allowed in the unit of work.
428      */
429     public Object   registerExistingObject(Object   existingObject);
430 
431     /**
432      * ADVANCED:
433      * Register the new object with the unit of work.
434      * This will register the new object without cloning.
435      * Normally the registerObject method should be used for all registration of new and existing objects.
436      * This version of the register method can only be used for new objects.
437      * This method should only be used if a new object is desired to be registered without cloning.
438      *
439      * @see #registerObject(Object)
440      */
441     public Object   registerNewObject(Object   newObject);
442 
443     /**
444      * PUBLIC:
445      * Register the object with the unit of work.
446      * All newly created root domain objects must be registered to be inserted on commit.
447      * Also any existing objects that will be edited and were not read from this unit of work
448      * must also be registered.
449      * Once registered any changes to the objects will be commited to the database on commit.
450      *
451      * @return the clone of the original object, the return value must be used for editing,
452      *
453      * ** Editing the original is not allowed in the unit of work. **
454      */
455     public Object   registerObject(Object   domainObject);
456 
457     /**
458      * PUBLIC:
459      * Release the unit of work.
460      * This terminates this unit of work.
461      * Because the unit of work operates on its own object space (clones) no work is required.
462      * The unit of work should no longer be used or referenced by the application beyond this point
463      * so that it can garbage collect.
464      *
465      * @see #commit()
466      */
467     public void release();
468 
469     /**
470      * PUBLIC:
471      * Empties the set of read-only classes.
472      * It is illegal to call this method on nested UnitOfWork objects. A nested UnitOfWork
473      * cannot have a subset of its parent's set of read-only classes.
474      */
475     public void removeAllReadOnlyClasses();
476 
477     /**
478      * ADVANCED:
479      * Remove optimistic read lock from the object
480      * See forceUpdateToVersionField(Object)
481      */
482     public void removeForceUpdateToVersionField(Object   cloneFromUOW);
483 
484     /**
485      * PUBLIC:
486      * Removes a Class from the receiver's set of read-only classes.
487      * It is illegal to try to send this method to a nested UnitOfWork.
488      */
489     public void removeReadOnlyClass(Class   theClass);
490 
491     /**
492      * PUBLIC:
493      * Revert all changes made to any registered object.
494      * Clear all deleted and new objects.
495      * Revert should not be confused with release which it the normal compliment to commit.
496      * Revert is more similar to commit and resume, however reverts all changes and resumes.
497      * If you do not require to resume the unit of work release should be used instead.
498      *
499      * @see #commitAndResume()
500      * @see #release()
501      */
502     public void revertAndResume();
503 
504     /**
505      * PUBLIC:
506      * Revert the object's attributes from the parent.
507      * This also reverts the object privately-owned parts.
508      *
509      * @return the object reverted.
510      * @see #shallowRevertObject(Object)
511      * @see #deepRevertObject(Object)
512      */
513     public Object   revertObject(Object   clone);
514 
515     /**
516      * ADVANCED:
517      * By default new objects are not cached until the exist on the database.
518      * Occasionally if mergeClone is used on new objects and is required to allow multiple merges
519      * on the same new object, then if the new objects are not cached, each mergeClone will be
520      * interpretted as a different new object.
521      * By setting new objects to be cached mergeClone can be performed multiple times before commit.
522      * New objects cannot be cached unless they have a valid assigned primary key before being registered.
523      * New object with non-null invalid primary keys such as 0 or '' can cause problems and should not be used with this option.
524      */
525     public void setShouldNewObjectsBeCached(boolean shouldNewObjectsBeCached);
526 
527     /**
528      * ADVANCED:
529      * By default deletes are performed last in a unit of work.
530      * Sometimes you may want to have the deletes performed before other actions.
531      */
532     public void setShouldPerformDeletesFirst(boolean shouldPerformDeletesFirst);
533 
534     /**
535      * ADVANCED:
536      * Conforming queries can be set to provide different levels of detail about the
537      * exceptions they encounter
538      * There are two levels:
539      *    DO_NOT_THROW_CONFORM_EXCEPTIONS = 0;
540      *    THROW_ALL_CONFORM_EXCEPTIONS = 1;
541      */
542     public void setShouldThrowConformExceptions(int shouldThrowExceptions);
543 
544     /**
545      * ADVANCED:
546      * The unit of work performs validations such as,
547      * ensuring multiple copies of the same object don't exist in the same unit of work,
548      * ensuring deleted objects are not refered after commit,
549      * ensures that objects from the parent cache are not refered in the unit of work cache.
550      * The level of validation can be increased or decreased for debugging purposes or under
551      * advanced situation where the application requires/desires to violate clone identity in the unit of work.
552      * It is strongly suggested that clone identity not be violate in the unit of work.
553      */
554     public void setValidationLevel(int validationLevel);
555 
556     /**
557      * PUBLIC:
558      * Merge the attributes of the clone into the unit of work copy.
559      * This can be used for objects that are returned from the client through
560      * RMI serialization (or other serialization mechanisms), because the RMI object will
561      * be a clone this will merge its attributes correctly to preserve object identity
562      * within the unit of work and record its changes.
563      *
564      * Only direct attributes are merged.
565      *
566      * @return the registered version for the clone being merged.
567      * @see #mergeClone(Object)
568      * @see #deepMergeClone(Object)
569      */
570     public Object   shallowMergeClone(Object   rmiClone);
571 
572     /**
573      * PUBLIC:
574      * Revert the object's attributes from the parent.
575      * This only reverts the object's direct attributes.
576      *
577      * @return the object reverted.
578      * @see #revertObject(Object)
579      * @see #deepRevertObject(Object)
580      */
581     public Object   shallowRevertObject(Object   clone);
582 
583     /**
584      * ADVANCED:
585      * Unregister the object with the unit of work.
586      * This can be used to delete an object that was just created and is not yet persistent.
587      * Delete object can also be used, but will result in inserting the object and then deleting it.
588      * The method will only unregister the clone, none of its parts.
589      */
590     public void shallowUnregisterObject(Object   clone);
591 
592     /**
593      * ADVANCED:
594      * By default new objects are not cached until the exist on the database.
595      * Occasionally if mergeClone is used on new objects and is required to allow multiple merges
596      * on the same new object, then if the new objects are not cached, each mergeClone will be
597      * interpretted as a different new object.
598      * By setting new objects to be cached mergeClone can be performed multiple times before commit.
599      * New objects cannot be cached unless they have a valid assigned primary key before being registered.
600      * New object with non-null invalid primary keys such as 0 or '' can cause problems and should not be used with this option.
601      */
602     public boolean shouldNewObjectsBeCached();
603 
604     /**
605      * ADVANCED:
606      * By default all objects are inserted and updated in the database before
607      * any object is deleted. If this flag is set to true, deletes will be
608      * performed before inserts and updates
609      */
610     public boolean shouldPerformDeletesFirst();
611 
612     /**
613      * ADVANCED:
614      * The unit of work performs validations such as,
615      * ensuring multiple copies of the same object don't exist in the same unit of work,
616      * ensuring deleted objects are not refered after commit,
617      * ensures that objects from the parent cache are not refered in the unit of work cache.
618      * The level of validation can be increased or decreased for debugging purposes or under
619      * advanced situation where the application requires/desires to violate clone identity in the unit of work.
620      * It is strongly suggested that clone identity not be violate in the unit of work.
621      */
622     public boolean shouldPerformFullValidation();
623 
624     /**
625      * ADVANCED:
626      * The unit of work performs validations such as,
627      * ensuring multiple copies of the same object don't exist in the same unit of work,
628      * ensuring deleted objects are not refered after commit,
629      * ensures that objects from the parent cache are not refered in the unit of work cache.
630      * The level of validation can be increased or decreased for debugging purposes or under
631      * advanced situation where the application requires/desires to violate clone identity in the unit of work.
632      * It is strongly suggested that clone identity not be violate in the unit of work.
633      */
634     public boolean shouldPerformNoValidation();
635 
636     /**
637      * ADVANCED:
638      * The unit of work performs validations such as,
639      * ensuring multiple copies of the same object don't exist in the same unit of work,
640      * ensuring deleted objects are not refered after commit,
641      * ensures that objects from the parent cache are not refered in the unit of work cache.
642      * The level of validation can be increased or decreased for debugging purposes or under
643      * advanced situation where the application requires/desires to violate clone identity in the unit of work.
644      * It is strongly suggested that clone identity not be violate in the unit of work.
645      */
646     public boolean shouldPerformPartialValidation();
647 
648     /**
649      * ADVANCED:
650      * Unregister the object with the unit of work.
651      * This can be used to delete an object that was just created and is not yet persistent.
652      * Delete object can also be used, but will result in inserting the object and then deleting it.
653      * The method will only unregister private owned parts
654      */
655     public void unregisterObject(Object   clone);
656 
657     /**
658      * ADVANCED:
659      * This can be used to help debugging an object-space corruption.
660      * An object-space corruption is when your application has incorrectly related a clone to an original object.
661      * This method will validate that all registered objects are in a correct state and throw
662      * an error if not,  it will contain the full stack of object references in the error message.
663      * If you call this method after each register or change you perform it will pin-point where the error was made.
664      */
665     public void validateObjectSpace();
666 
667     /**
668      * ADVANCED: Writes all changes now before commit().
669      * The commit process will begin and all changes will be written out to the datastore, but the datastore transaction will not
670      * be committed, nor will changes be merged into the global cache.
671      * <p>
672      * A subsequent commit (on UnitOfWork or global transaction) will be required to finalize the commit process.
673      * <p>
674      * As the commit process has begun any attempt to register objects, or execute object-level queries will
675      * generate an exception.  Report queries, non-caching queries, and data read/modify queries are allowed.
676      * <p>
677      * On exception any global transaction will be rolled marked or marked rollback only.  No recovery of this UnitOfWork will be possible.
678      * <p>
679      * Can only be called once.  It can not be used to write out changes in an incremental fashion.
680      * <p>
681      * Use to partially commit a transaction outside of a JTA transaction's callbacks.  Allows you to get back any exception directly.
682      * <p>
683      * Use to commit a UnitOfWork in two stages.
684      */
685     public void writeChanges();
686 }
687
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags