Sharing Status API

This is an overview of the Chandler client Sharing Status objects and their API. See Lisa's overview of Sharing Status for background on what information needs to be tracked, and how the server interaction works.

Here are the objects that appear on the Chandler client:

• Shared Item - an Item Collection being shared
• Sharing Status - maintains overall status of the Shared Item
• Sharee Status - maintains status for a particular sharee
• Invite - an invitation to share an item.

Each Shared Item has a reference to its Sharing Status object.

Each Sharing Status object has a structure that folows Lisa description in her Sharing Status, with a few additions. On the Chandler client the Sharing Status object supports an API to allow adding or removing sharees, getting or setting the status of a sharee, etc. The Sharing Status object also has a reference to a list of Invite objects, so we can associate errors in the delivery of an invitation with the Sharing Status. Critically, there is a ref collection of Sharee Status objects keyed by emailAddress. This allows quick lookup of a Sharee Status given an emailAddress.

Each Sharee Status object has these attributes: ACL (reader/Edit), Disabled, StatusEnum (sync'ed, pending, error). These attributes differ from Lisa's proposal - I separated out the status, ACL, and Disabled attributes so they can be changed independently. We can add additional attributes as needed, e.g. date of last sync.

An Invite object just an API that allows creation, sending, of a sharing invitation. Our implementation for 0.5 will use Mail as a transport for these invites, just as we did in 0.4. Additionally we'll add a way for the Mail to point back to the Sharing Status, so we can update the status when a delivery error occurs. Sometimes these errors happen immediately, but sometimes they happen after a successful sending of the mail, e.g. an hour later the mail is bounced as undeliverable. We'll reflect these errors back in the Sharing Status for the affected sharees.

Operational Overview

When Sharing commences a Sharing Status object is created for the Shared Item. Using the Sharing Status API the Invite is sent, and the UI can query the status or ACL for each sharee. Each time synchronization is done with WebDAV, the Sharing Status object is sync'ed as well. This has the effect of automatically updating the Sharing Status for the "sharer" each time that sharer syncs with WebDAV. So a status of "pending" for a sharee will be updated to "shared" when that user does a sync of the Shared Item and the Sharing Status object. If errors occur in the delivery of invitations, the Mail that bounced is used to lookup the Sharing Status object and update the sharee's sync status to the "error" state.

-- DonnDenman - 11 Nov 2004