[Bugs] #568 UNSP: Redo activity Journal APIs

[SugarLabs Bugs]

#568: Redo activity Journal APIs
------------------------------------------+---------------------------------
    Reporter:  wadeb                      |          Owner:  tomeu                      
        Type:  enhancement                |         Status:  new                        
    Priority:  Unspecified by Maintainer  |      Milestone:  Unspecified by Release Team
   Component:  sugar                      |        Version:  Git as of bugdate          
    Severity:  Major                      |       Keywords:                             
Distribution:  Unspecified                |   Status_field:  Unconfimed                 
------------------------------------------+---------------------------------
 When an activity starts up, it can be in one of several states:

 * Starting a new instance.
 * Resuming an instance from the Journal.
 * Joining a shared activity.

 While executing, several additional events can occur:

 * Saving to the journal.
 * Sharing the activity.

 The APIs for these events are currently scattered.

 * New instance: __init__ only
 * Resume instance: __init__ followed by read_file (called by set_canvas)
 * Save instance: write_file
 * Join instance: __init__ followed by join_cb (must be connected manually)
 * Share instance: __init__ followed shared_cb (must be connected manually)

 My hope is to see a clear set of APIs for activities to interact with the
 journal and sharing.

 A possible example of this API was developed by alsroot and can be seen
 here:
 http://git.sugarlabs.org/projects/cartoon-
 builder/repos/mainline/blobs/master/shared.py

 This introduces the following new Activity methods:

 * new_instance
 * resume_instance
 * save_instance
 * join_instance
 * share_instance

 One of {new,resume,join}_instance is guaranteed to be called at startup,
 after __init__ returns (the set_canvas relationship is removed).

 Further, share_instance and save_instance will be called as needed.

 Ideally, these new method calls would be integrated to the Sugar Activity
 class, with default implementations which call the old read_file and
 write_file APIs for backwards compatibility purposes.

 Note that even with these changes, the collaboration API remains difficult
 to use and should be the subject of a separate ticket.  One possibility
 for improving this comes from the Calculate activity:
 http://git.sugarlabs.org/projects/calculate/repos/mainline/blobs/master/shareable_activity.py

-- 
Ticket URL: <http://dev.sugarlabs.org/ticket/568>
Sugar Labs <http://sugarlabs.org/>
Sugar Labs bug tracking system