Redo activity Journal APIs

[wadeb]

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

[tomeu]

seems too late to get this one in 0.86, slipping to 0.88

[walter]

This is all potentially tied to Sascha's versioning work... maybe it will all come together in 0.90