[Chandler-dev] Sharing API for edit/update

Morgen Sagen morgen at osafoundation.org
Tue Jan 30 12:37:52 PST 2007


I recently checked in some functions that can be used for serializing/ 
deserializing items in a peer-to-peer context such as mail-based edit/ 
update sharing.  Documentation is the API section of:

    http://wiki.osafoundation.org/Projects/SharingProject

 From that page:

To support p2p sharing of individual items, the sharing package now  
has inbound( ) and outbound( ) functions.  Each function takes a  
"peer" parameter which is any Chandler item that represents who you  
are sharing the item with.  For example, this peer might be a Contact  
or emailAddress item; the inbound/outbound functions don't care what  
it is as long as it's a Chandler Item with a UUID.

sharing.inbound( ) currently takes an EIMML string (although in the  
future we will want the Translator and Serializer to be  
configurable), processes it, and applies any non-conflicting changes  
to the local item.  The item is created if not already existing, and  
stamped/unstamped as needed.  Conflicts are stored in the share  
item's "conflictingStates" ref collection.  The API for accessing  
conflict information is still TBD.  A basic method called  
SharedItem.getConflicts( ) returns a list of (peer, pending) tuples.

sharing.outbound( ) takes an existing item and returns an EIMML  
string to transmit.  If the item has any pending conflicts, outbound 
( ) will instead raise a ConflictsPending exception.

Unlike server-centric sharing, the EIMML generated by outbound( )  
always contains the full state of the item.  It also contains some  
additional information, including the sender's repository UUID, plus  
the sender's version number of the transmitted item.  This allows the  
inbound( ) function to compare the peer repository UUID with the one  
it previously saw; if it's different, inbound( ) assumes that the  
peer has re-created its repository, and all the inbound records are  
considered as changes.  If the peer repository UUID is a match, then  
the inbound records are compared against the previously seen state to  
determine what's actually changed.  Additionally, If the item version  
embedded in the EIMML is less than or equal to the version number  
last seen from this peer, an OutOfSequence exception is raised.

See the Itemcentric Sharing section of EIMML.txt for example usage:

    http://viewcvs.o11n.org/chandler/trunk/chandler/parcels/osaf/ 
sharing/EIMML.txt?view=markup

~morgen


More information about the chandler-dev mailing list