DatastoreRequirements
Requirements for activities
See http://lists.laptop.org/pipermail/sugar/2007-September/003442.html for the thread where these requirements were discussed related to security.
The term "activity" is used 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.
Requirements for the journal
Synthesized from OLPC_Human_Interface_Guidelines/The_Laptop_Experience/The_Journal:
- Free text queries similar to google.
- Filtering and sorting by metadata fields.
- Paged retrieval of query results.
- Retrieval of all unique values that a property has (for implementing comboboxes for the filters).