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 href="http://blogs.osafoundation.org/chandlerdb/2005/02/using_attribute.html">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 href="http://blogs.osafoundation.org/chandlerdb/2005/07/abstract_sets_o.html">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 href="http://blogs.osafoundation.org/chandlerdb/2006/03/collections_ite.html">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
      ...
  

This entry was posted on Wednesday, March 8th, 2006 at 3:09 pm and is filed under Chandler Desktop Development, chandlerdb. You can follow any responses to this entry through the RSS 2.0 feed. You can skip to the end and leave a response. Pinging is currently not allowed.