Up Save lifecycle
DevForce Resource Center » Development guide » Save » Save lifecycle » Client-side save lifecycle events

Client-side save lifecycle events

Last modified on September 17, 2012 18:11

The client side lifecycle of a save consists of two events on the EntityManager; Saving and Saved. These are summarized in the table below.



Saving and Saved events

Event    EventArgsCommentsTypical Uses of the Corresponding Event Handler
SavingEntitySavingEventArgs

Raised when the EntityManager is preparing to save changes.
Provides access to the collection of entities submitted for the save. Permits cancellation of the save.

Modify the object submitted for saving, or refuse the request to perform inserts and/or updates.
SavedEntitySavedEventArgs

Raised when the EntityManager has completed a save (including a save which was cancelled or failed).
Provides access to the collection of entities saved and other status information.

Modify the saved object (which might be different from the object submitted for saving by virtue of triggers that were fired on the back end to modify the latter after it was saved).

The EntityManager raises a Saving event shortly after the application initiates a save. It raises a Saved event upon completion of the save, regardless of whether any entities were saved successfully. We can add our own event handlers to these events.

The Saving event provides the handler with a list of entities that the caller proposes to save. It will calculate that list if the method parameters do not prescribe the list. SaveChanges() with no arguments, for example, is a blanket request to save every added, changed or deleted entity in cache. The event handler can scrutinize the list, invoke validation methods on selected entities, clean up others (e.g., clear meaningless error conditions), add additional entities to the list, and even exclude entities from the list. Lastly, it can cancel the save.

The EntityManager raises the saved event upon completion of the save. The handler receives a list of the entities that were saved successfully.

In DevForce, saves are always transactional, even across disparate back-end data sources. In transactional saves, either every entity in the save list is saved or none of them are.

Virtual EntityManager methods

Corresponding to each of these events is a protected virtual method on the EntityManager that can be used to perform the same task directly in a subclassed EntityManager.

MemberSummary
OnSaving The virtual method that a derived EntityManager can override to raise the Saving event.
OnSavedThe virtual method that a derived EntityManager can override to raise the Saved event.

EntitySavingEventArgs

Property  PropertyType  Access  Description
EntitiesIList<Object>get - but the list returned can be modifiedThe list of entities to be saved.
Cancel boolget, setAllows the save to be cancelled.

EntitySavedEventArgs

Property  PropertyType  Access  Description
EntitiesIList<Object>getReturns the entities saved.
SaveResultSaveResultgetReturns the SaveResult - see SaveResult
CancelledboolgetWhether the save was cancelled.
IsCompletedboolgetWhether the operation completed.
CompletedSuccessfullyboolgetWhether the save was successful.
CompletedSynchronouslyboolgetWhether the save was sync.
HasErrorboolgetWhether an exception occurred.
ErrorExceptiongetNon-null if an exception was thrown.
IsErrorHandledboolgetTrue if an EntityServerError handler "handled" the error.

Created by DevForce on December 10, 2010 09:58

This wiki is licensed under a Creative Commons 2.0 license. XWiki Enterprise 3.2 - Documentation. Copyright © 2020 IdeaBlade