[sugar] datastore use cases for activities

[Tomeu Vizoso]

Hi,

follows a list of the use cases I have gathered during these months of
datastore development.

I'm using "activity" for the software component and "activity session"
for one instance of it, which can be running or frozen inside the
datastore.

== Activity session stops ==

When an activity session stops, we want to store its state to the
Datastore so it can be examined later from the journal and it can be
resumed from where it was stopped.

Activities need to at least save to the journal an entry with the
activity session title, the buddies that participated on the activity
session, an image that visually represents the state of the activity (a
screenshot, currently), any tags that can help in categorizing the entry
and the activity-dependent data as metadata properties or a file on
disk. If the data in the file can be interpreted by other activities,
the 'mime_type' property should be set.

For some activities like Record that wish to expose some products of the
activity session like in this case photographs, videos or audio
recordings, a journal entry for each of those can be created, specifying
the right mime type for each of them. In this way, a photograph can be
modified in Paint, a video watched in Watch&Listen, or an audio
recording imported in one of the TamTam activities.


== Activity automatically saves its state ==

At any point during the activity session, the activity can judge
necessary to update the entry in the journal. In this way the journal
can show the state of currently running activities and in case of a
crash the work is not lost.


== User presses 'Keep' button in a running activity instance ==

Same as in the two previous use cases, only that in this case, any
future saves will be done in a new entry. The current one is preserved
in the journal as frozen so it can be resumed later in a new activity
session. This acts similarly as branching in a vcs.


== A Journal entry is resumed ==

The activity is started by the journal and an object id corresponding to
the resumed entry is handled to it.

The activity will retrieve from the datastore the metadata for that
object id and the file were data was stored.

In cases like Record, querying the datastore by 'activity_id' will
retrieve the separate entries that make part of this activity session
(photographs, videos and audio recordings).


== User presses 'Insert image' button in a running activity instance ==

The activity requests sugar that the user should choose a journal entry
of the type Image (or several).

After the user has chosen one or several entries, the dialog is closed
and the activity receives the object ids for those entries. Then it can
request the metadata or files for any of them.

A similar use case would be for the upload file dialog in Browse. In
this case all entries that have an associated file should be presented
to the user. The user should be able to search, filter and sort just
like in the journal in order to find the entry that will be uploaded.


Any activity author that sees these use cases as insufficient for their
activities, please jump and tell. I'm also not sure that the security
provisions in Bitfrost contemplate all of this, so Michael, please
comment.

I will put all this in the wiki after some discussion has happened.

Tomeu