1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
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
|
