Receiving notifications about changes to items
March 8th, 2006 at 3:09 pm (2 years, 2 months ago) by Andi Vajda under Chandler Desktop Development, chandlerdbTo support the requirements of Chandler, the repository had to implement a richer set of notifications than what was originally offered with attribute monitors.
Common to all kinds of repository notification, a method on a subscribing item is invoked when changes take place in an item. The subscriber may be notified immediately after the change happened or the notification may be queued for later delivery. The subscription may be persisted in the repository and eventually exist in all repository views or may be kept transient in a view until that view is closed.
The use cases below describe the various kinds of repository notifications and how to set them up. There is overlap between them, read on carefully. Collection item notifications are based off some of these use cases and are described last.
- How to receive a notification when an attribute of a given name
changes on any item.
This is done with attribute monitors.- a monitor is always a persistent subscription
- monitor methods are always invoked immediately after a monitored attribute changes in the view of the subscriber items
- monitor methods are not invoked during view refresh
- How to receive a notification when a given item changes
A item is said to change when one or several of its attribute values are changed, added or removed, or when its kind changes during item creation, stamping or deletion. This style of notification is setup with thewatchItemAPI.- an item watcher may be persistent by calling
watchItemon the subscriber:
subscriber.watchItem(item, methodName)
- an item watcher may be kept transient to a view by calling
watchItemon the view instead:
subscriber.itsView.watchItem(subscriber, item, methodName) - an item watcher method is invoked immediately after an item changed in the view of the subscriber items
- an item watcher method is invoked during view refresh when a watched item is refreshed to changes the occurred earlier in other views
The method name passed to
watchItemmust correspond to a method defined on the subscriber item’s implementation class:def watchedItemChanged(self, op, item, names): # self is the subscriber item # op is one of 'set', 'remove' or 'refresh' # 'set' means that an attribute value was set # 'remove' means that an attribute value removed # 'refresh' means that the item was changed because the view refreshed # item is the uuid of the item that changed # names is a tuple naming all the attributes that changed # it normally contains one name except when op is 'refresh' # if the item's kind changed, then it also contains 'itsKind' ... - an item watcher may be persistent by calling
- How to receive a notification when any item of a given kind is created,
deleted or stamped.
This style of notification is setup with thewatchKindAPI.- a kind watcher may be persistent by calling
watchKindon the subscriber:
subscriber.watchKind(kind, methodName)
- a kind watcher may be kept transient to a view by calling
watchKindon the view instead:
subscriber.itsView.watchKind(subscriber, kind, methodName) - a kind watcher method is invoked immediately after any item’s watched kind changed in the view of the subscriber items
- a kind watcher method is not invoked during view refresh
The method name passed to
watchKindmust correspond to a method defined on the subscriber item’s implementation class:def watchedKindChanged(self, op, kind, item): # self is the subscriber item # op is one of 'add' or 'remove' # 'add' means that the item is now of that kind (or a subkind thereof) # 'remove' means that the item is no longer of that kind # item is the item or the uuid of the item that changed ... - a kind watcher may be persistent by calling
- How to receive a notification when any item is added to or removed from
an abstract
set or a bi-directional ref collection.
This style of notification is setup with thewatchCollectionAPI.- a collection watcher may be persistent by calling
watchCollectionon the subscriber:
subscriber.watchCollection(item, attribute, methodName)
- a collection watcher may be kept transient to a view by calling
watchCollectionon the view instead:
subscriber.itsView.watchCollection(subscriber, item, attribute, methodName) - a collection watcher method is invoked immediately after any item’s watched collection changed in the view of the subscriber items
- a collection watcher method is invoked during view refresh
The method name passed to
watchCollectionmust correspond to a method defined on the subscriber item’s implementation class:def watchedCollectionChanged(self, op, item, attribute, other): # self is the subscriber item # op is one of 'add', 'remove', 'refresh' or 'changed' # item is the item or the uuid of the item that owns # the collection that changed # attribute is the name of the attribute that contains the collection # value that changed. # other is the item or the uuid of the item that was added to, removed # from, refreshed or otherwise changed while it belonged to the collection ... - a collection watcher may be persistent by calling
- How to receive a notification when any item is added to or removed from
a Collection item or when an item belonging to a Collection item is
changed
This style of notification is setup with thenotificationQueueSubscribeAPI.- a collection item subscription may be persistent by calling
notificationQueueSubscribeon the collection item:
collection.notificationQueueSubscribe(subscriber)
- a collection item subscription may be kept transient to a view by calling
notificationQueueSubscribeon the view instead:
collection.itsView.notificationQueueSubscribe(subscriber) - collection item notifications are queued and are dispatched during view
refresh or when
view.dispatchNotifications()is called explicitely.
A collection item notification subscriber must implement a method called
onCollectionNotification:def onCollectionNotification(self, op, collection, attribute, other): # self is the subscriber item # op is one of 'add', 'remove', 'refresh' or 'changed' # collection is the collection item that changed # attribute is the name of the attribute that contains the collection # value that changed. # other is the item or the uuid of the item that was added to, removed # from, refreshed or otherwise changed while it belonged to the collection ... - a collection item subscription may be persistent by calling








