Starting/resuming activities:
=============================
[1]:
-b, --bundle-id  
    Identifier of the activity bundle
-a, --activity-id 
    Identifier of the activity instance.
-o, --object-id  
    Identifier of the associated datastore object.
-u, --uri  
    URI to load.



Datastore Python API for activities:
====================================

sugar.datastore.datastore [2]

create(): 
  new jobject/DSObject, no DBus interaction
  does _not_ set activity_id or bundle_id

write(ds_object, update_mtime=True, transfer_ownership=False, reply_handler=None, error_handler=None, timeout=-1):
  write content from file with filename set via DSObject API
  will call DBus API update() if DSObject.object_id is set or create() otherwise ("Keep")
  object_id set on DSObject from return value of DBus call for create()

get(object_id):
  retrieve jobject/DSObject properties for given id via DBus

find(query, sorting=None, limit=None, offset=None, properties=None, reply_handler=None, error_handler=None):
  retrieve jobject/DSObject properties for matching entries via DBus


DSObject:
  saves metadata
  contains object_id (None for new entries)
  default values set by sugar.activity.activity.Activity.__init__():
    title
    title_set_by_user
    activity (=bundle_id)
    activity_id (=instance id)
    keep (=star marking=favourite)
    preview
    share-scope
    icon-color



DBus API for activities:
========================

carquinyol.datastore:
---------------------

create(self, props, file_path, transfer_ownership, async_cb, async_err_cb):
  generates new uid (object_id) as UUID
  stores given metadata (associated via uid), indexes it
  stores given data (associated via uid)
  returns generated uid

update(self, uid, props, file_path, transfer_ownership, async_cb, async_err_cb):
  sets timestamp (in props) if not given
  stores given metadata (associated via uid), indexes it
  stores given data (associated via uid) if given (!)
  does _not_ return uid

find(self, query, properties):
  returns metadata for all matching entries (associated via uid)

get_filename(self, uid, sender=None):
  retrieves data for given uid?

get_properties(self, uid): 
  returns metadata for given uid


Object chooser / Journal interaction:
-------------------------------------

org.laptop.Journal.ChooseObject(xid, what_filter):
  brings up object chooser, returns handle (chooser_id)

ObjectChooserResponse(chooser_id, object_id):
  signal sent on selection of an object.

ObjectChooserCancelled(chooser_id):
  signal sent on user abort

org.laptop.Journal.ShowObject(object_id)
  open Journal, show details page for given object_id



ID theory:
==========

current situation:
------------------

bundle_id:
	identifies all activity instances created by a given activity (template)

activity_id:
	identifies all entries based on a specific activity instance (created on starting a new instance 
        from home view / journal; resuming preserves previous activity_id)
        For new jobjects created explicitly by an activity (-> collections) it must be set 
        manually (see Record:serialize._saveMediaToDatastore()).

object_id: (uid in datastore)
	identifies the latest and only version of a given object saved inside an activity instance. New objects can be created either
        by using "Keep" or as part of a collection, e.g. (multiple) photos in Record.


Future situation:
-----------------

bundle_id:
	identifies all activity instances created by a given activity (template)

activity_id:
	identifies all entries based on a specific activity instance (created on starting a new instance 
        from home view / journal; resuming preserves previous activity_id)
        For new jobjects created explicitly by an activity (-> collections) it must be set 
        manually (see Record:serialize._saveMediaToDatastore()).


Options:

a) 
	object_id: (uid in datastore)
		identifies all versions of a given object saved inside an activity instance. New objects can be created either
	        by using "Keep" or as part of a collection, e.g. (multiple) photos in Record.
	        By default all APIs will work on / retrieve the latest version.

	Problem: For resuming old entries we'd need to pass a version_id to sugar-activity.

b)
	object_id: (uid in datastore)
		identifies a specific version of an object saved inside an activity instance.

	Problem: would change object_id on saving so we'd need to return that in update() and activities need to update it

c)
	object_id: (uid in datastore)
		identifies a specific branch of an object saved inside an activity instance.
	        By default all APIs will work on / retrieve the latest version of a branch.

	Problem: need to create a new branch when resuming a non-HEAD version, even for read-only access
        Solution: "virtual" branches that get "realized" on the first write access (with actual updates, either data or metadata)





Lifetime view:
==============

See also [3].

Starting a new activity instance from home view or bundle in Journal:
* run activity, i.e. sugar-activity for Python activities
** no object_id passed on command line
** newly created activity_id passed on command line
** bundle_id passed on command line
* create new DS object
** returns new object_id (uid)
* write state on significant changes
* metadata can be updated without data update
** Python API transparently identifies the object
** DBus API uses object_id (uid) to identify what to write
* create new object (Keep or collection entry)
** Keep: Python API sets DSObject.object_id to None [4]
** Record sets activity_id, but not bundle_id
** Python + DBus API call create(), getting new object_id

Resuming an activity instance via Journal:
* run activity, i.e. sugar-activity for Python activities
** object_id, activity_id and bundle_id passed on command line



[1] http://wiki.laptop.org/go/Activity_bundles
[2] http://api.sugarlabs.org/sugar.datastore.datastore-module.html
[3] http://wiki.laptop.org/go/Low-level_Activity_API
[4] http://api.sugarlabs.org/sugar.activity.activity-pysrc.html#Activity.copy