Object class events |
|
|
|
|
||
|
Object class events |
|
|
|
|
|
Object class events
|
Object class events |
|
|
|
|
||
|
Object class events |
|
|
|
|
|
|
|
||
Events which are linked to ObjectClass objects are fired whenever the event is raised for any instance object of that ObjectClass. There are six events linked to ObjectClass objects. When any of these events are raised for an instance of a particular ObjectClass, they are first raised for all it’s base classes, starting with the least derived. Also, there are six corresponding events for individual Persistent objects. These are fired before the events described here. See Persistent events for details.
The following list gives a summary of each of these events. See the Persistate API documentation for full details. See the Event Firing Sequences section for details on the order in which these and persistent events are fired in various circumstances.
| ▪ | The InstanceAdopted event is fired whenever an instance of the class is attached to a parent object. This happens whenever you assign the object to a contained (not associated) member of another object, or whenever you add the object to a contained collection. It also happens (after InstanceDisowned) during the Persistent.Move method. |
| ▪ | The InstanceDisowned event is fired whenever an instance of the class is detached from its parent object. This happens whenever you overwrite the contained (not associated) member containing the object with null, or another object, or you remove the object from a contained collection. It also happens (before InstanceAdopted) during the Persistent.Move method. |
| ▪ | The InstanceAssociated event is fired whenever an instance of the class is associated to another object. This happens whenever you assign the object to an associated scalar member of another object, or whenever you add the object to an associated collection. |
| ▪ | The InstanceDissociated event is fired whenever an instance of the class is disassociated from another object. This happens whenever you overwrite an associated scalar member containing the object with null or another object, or when you remove the object from an associated collection. |
| ▪ | The InstanceModified event is fired whenever an instance of the class is modified using one of the generated properties, or when the OnModified() method is called manually. |
| ▪ | The InstanceDeleted event is fired whenever an instance of the class is detached from its parent object. This happens whenever you overwrite the contained (not associated) member containing the object with null, or another object, or you remove the object from a contained collection. Unlike InstanceDisowned, it is not fired by the Persistent.Move method, but it is fired whenever any newly created objects are deleted when an operation execution returns a ResultAction of Rollback. See Synchronising with persistent storage for details of the latter. |
Here is an example of the use of ObjectClass events.
/// <summary>
/// Set up event handling
/// </summary>
public static void SetEventHandlers()
{
Author.ItsObjectClass.InstanceAssociated
+= new LinkageEventHandler(Author_InstanceAssociated);
Author.ItsObjectClass.InstanceDissociated
+= new LinkageEventHandler(Author_InstanceDissociated);
}
static void Author_InstanceAssociated(object sender, LinkageEventArgs args)
{
Book book = args.Container as Book;
if (book != null)
((Author)args.Containee).Books.AddIfAbsent(book);
}
static void Author_InstanceDissociated(object sender, LinkageEventArgs args) {
Book book = args.Container as Book;
if (book != null)
((Author)args.Containee).Books.Remove(book);
}
This example shows the use of data events in maintaining redundant data links. If you look at the library sample definition file shown in An Example Definition File, you will see that each author has several associated books, and that each book has an associated author. It is very useful to have links going both ways like this, but obviously there is scope for error, where the links get out of sync.
Using the associated and dissociated events as above keeps the links synchronised with little effort, and allows you to assign authors to books anywhere, without fear of introducing problems. In this case, you would complete the scenario by performing the same as above for books, so that adding a book to an author’s book collection would automatically assign that author as the author of the book. Note that this would not result in a circular event loop, since assigning an object to a member which has that object already assigned causes no events to be raised.
