Up Create, modify and delete

Listen for changes

Last modified on July 08, 2015 14:28

Listen for changes to specific entities or for changes to groups of entities in cache by attaching handlers to Entity and EntityManager events.


EntityManager events


The EntityManager has a number of events that provide access to a variety of information regarding changes to both the Entities within an EntityManager as well as the EntityManager itself.

Instance events:

EventDescription
ClearedFired whenever the EntityManager.Clear method is called.
EntityChangingFired just before any entity within the EntityManager is about to be changed. The change can be cancelled from within the event handler. Information about the change is available via an EntityChangingEventArgs parameter passed to the event handler.
EntityChangedFired just after any entity within the EntityManager is changed. Information about the change is available via an EntityChangedEventArgs parameter passed to the event handler.
EntityServerErrorFired when an error occurs during an operation that passed data to the EntityServer. The IdeaBlade.EntityModel  allows the exception to be examined and optionally "handled" so that the exception does not propogate further.  This can be used as a "last resort" error handler for any EntityServer errors.
QueryingDiscussed here
FetchingDiscussed here
QueriedDiscussed here
SavingDiscussed here
SavedDiscussed here

Both the EntityChanging and EntityChanged event handlers are passed an event args variable that in turn contains an instance of the EntityAction enumeration.  This action may be used to determine the kind of change that is either about to occur or has just occured. The descriptions below are phrased in the past tense but should be translated to the future tense in the case of the EntityChanging event. EntityAction is a flag enumeration meaning that more than one action may set at the same time. Where this occurs, it is called out.

EntityActionDescription
RemoveThe entity has been removed. Either via a call to RemoveEntity or after the save of a Deleted entity.
ChangeThe entity has changed as a result of a change to some property on the entity. 
RollbackThe most recent change to the entity has been rolled back. This occurs as a result of a RejectChanges call.
CommitThe changes to the entity have been committed. This occurs as a result of a AcceptChanges call.
AddThe entity has just been attached to the EntityManager. 
ChangeOriginalThe original version of the entity has been changed. This occurs as a result of a Merge operation (via Query or ImportEntities) with PreserveChangesUpdateOriginal strategy.
ChangeCurrentAndOriginalThe original and the current versions of the entity have been changed. This occurs on any Merge operation other than the one above.
AddOnQueryThe entity has been attached as a result of an query operation. (This is also an Add EntityAction)
AddOnImportThe entity has been attached as a result of an import operation. (This is also an Add EntityAction)
AddOnAttachThe entity has been attached to as a result of an AttachEntity call but with an EntityState other than Added. (This is also an Add EntityAction)
DeleteThe entity was marked for deletion 

By default, if your handler for the EntityChanging or EntityChanged event throws an exception when an entity is added by either query or import, DevForce will "eat" the exception and your application will never see the problem.  DevForce handles these exceptions in order to insure that the state of the EntityManager remains consistent.  To override this behavior, set the EntityManagerOptions.ThrowAllLoadExceptions flag to true.  For example:

C#
entityManager.Options.ThrowAllLoadExceptions = true;

Note that this flag also controls the behavior of exception handling for these events on the EntityGroup, and PropertyChanged events on the Entity and EntityAspect.

Static ( class level) events:

EventDescription
EntityManagerCreatedA class level event that is fired anytime a new EntityManager is created

EntityGroup events

In DevForce, every EntityManager contains a collection of EntityGroups.  Each EntityGroup in turn contains all of the entities of a single entity type that are part of this EntityManager. An EntityGroup can be retrieved via either of the following methods on an EntityManager.

C#
public EntityGroup GetEntityGroup(Type entityType);
public EntityGroup<T> GetEntityGroup<T>();
VB
Public Overloads Function GetEntityGroup( _
  ByVal entityType As Type _
) As EntityGroup
Public Overloads Function GetEntityGroup(Of T)() As EntityGroup(Of T)

Each EntityGroup has a number of events that may be handled:

EventDescription
EntityPropertyChangingFired just before a property of an entity changes. The associated EntityPropertyChangingEventArgs contains information regarding the entity being changed, the property being changed and the "proposed value" for the change.  The change may be cancelled, in which case the property set operation will not occur.
EntityPropertyChangedFired just after a property of an entity changes. The associated EntityPropertyChangedEventArgs contains information regarding the entity that was changed, the property that was changed and the "value" for the change. 
EntityChangingThis is basically the same as the EntityManager.EntityChanging event simply fired at a different level.
EntityChangedThis is basically the same as the EntityManager.EntityChanged event simply fired at a different level.

There may be cases where a developer wants to suppress all "change notification" within an EntityGroup for a period of time.  This can be accomplished by setting the ChangeNotificationEnabled property to 'false'. Note that this will affect change notification at the EntityManager level (EntityChanging, EntityChanged) as well as at the Entity level (INotifyPropertyChanged).

Entity events

EventDescription
PropertyChangedImplementation of INotifyPropertyChanged
ErrorsChangedExplicit implementation of INotifyDataErrorInfo 

EntityAspect events

Most changes that relate to an Entity are handled by the events listed previously on this page; however, the EntityAspect also implements INotifyPropertyChanged to raise a change notification for several of its properties.

EventDescription
PropertyChangedPart of INotifyPropertyChanged implementation. Properties on the EntityAspect that are subject to changes and therefore available via the PropertyChanged notification are EntityState, EntityKey, IsChanged, and HasErrors.

Tags:
Created by DevForce on February 16, 2011 16:08

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