To 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 the watchItem API.
  • an item watcher may be persistent by calling watchItem on the subscriber:
    subscriber.watchItem(item, methodName)
    
  • an item watcher may be kept transient to a view by calling watchItem on 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 watchItem must 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'
      ...
  

• How to receive a notification when any item of a given kind is created, deleted or stamped.
  This style of notification is setup with the watchKind API.
  • a kind watcher may be persistent by calling watchKind on the subscriber:
    subscriber.watchKind(kind, methodName)
    
  • a kind watcher may be kept transient to a view by calling watchKind on 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 watchKind must 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
      ...
  

• 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 the watchCollection API.
  • a collection watcher may be persistent by calling watchCollection on the subscriber:
    subscriber.watchCollection(item, attribute, methodName)
    
  • a collection watcher may be kept transient to a view by calling watchCollection on 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 watchCollection must 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
      ...
  

• 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 the notificationQueueSubscribe API.
  • a collection item subscription may be persistent by calling notificationQueueSubscribe on the collection item:
    collection.notificationQueueSubscribe(subscriber)
    
  • a collection item subscription may be kept transient to a view by calling notificationQueueSubscribe on 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
      ...