Hello All,<br><br>First off, thanks to everyone who has been contributing to the almanac (<a href="http://wiki.laptop.org/go/Sugar-api-doc">http://wiki.laptop.org/go/Sugar-api-doc</a>) directly or giving me feedback on things that need to be added or improved for accuracy. Please keep the feedback coming. <br>
<br>Among many other additions, the Sugar Almanac now has a section on using the datastore. It includes a basic overview of the architecture as well as a bunch of entries on how to do different useful tasks with the datastore: <br>
<br><ul><li class="toclevel-1"><a href="http://wiki.laptop.org/go/Sugar.datastore.datastore#Datastore_Helper_Functions"><span class="tocnumber">2</span> <span class="toctext">Datastore Helper Functions</span></a>
<ul><li class="toclevel-2"><a href="http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_create_a_new_datastore_object.3F"><span class="tocnumber">2.1</span> <span class="toctext">How do I create a new datastore object?</span></a></li>
<li class="toclevel-2"><a href="http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_provide_a_query_to_the_datastore.find.28.29_method_so_that_I_can_find_datastore_objects_with_a_particular_property.3F"><span class="tocnumber">2.2</span> <span class="toctext">How do I provide a query to the datastore.find() method so that I can find datastore objects with a particular property?</span></a></li>
<li class="toclevel-2"><a href="http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_delete_datastore_entries_with_a_particular_property.3F"><span class="tocnumber">2.3</span> <span class="toctext">How do I delete datastore entries with a particular property?</span></a></li>
<li class="toclevel-2"><a href="http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_get_all_the_unique_values_that_are_mapped_to_a_particular_key_in_the_datastore.3F"><span class="tocnumber">2.4</span> <span class="toctext">How do I get all the unique values that are mapped to a particular key in the datastore?</span></a></li>
<li class="toclevel-2"><a href="http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_get_command_line_access_to_the_files_in_my_DataStore.3F"><span class="tocnumber">2.5</span> <span class="toctext">How do I get command line access to the files in my DataStore?</span></a></li>
<li class="toclevel-2"><a href="http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_identify_the_different_mount_points_available_through_the_datastore_api.3F"><span class="tocnumber">2.6</span> <span class="toctext">How do I identify the different mount points available through the datastore api?</span></a></li>
</ul>
</li><li class="toclevel-1"><a href="http://wiki.laptop.org/go/Sugar.datastore.datastore#Class:_DSObject"><span class="tocnumber">3</span> <span class="toctext">Class: DSObject</span></a>
<ul><li class="toclevel-2"><a href="http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_create_new_metadata_entries_or_reassign_metadata_for_a_datastore_object_that_has_been_created.3F"><span class="tocnumber">3.1</span> <span class="toctext">How do I create new metadata entries or reassign metadata for a datastore object that has been created?</span></a></li>
<li class="toclevel-2"><a href="http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_save_a_simple_text_file_to_the_datastore.3F"><span class="tocnumber">3.2</span> <span class="toctext">How do I save a simple text file to the datastore?</span></a></li>
<li class="toclevel-2"><a href="http://wiki.laptop.org/go/Sugar.datastore.datastore#How_do_I_resume_an_activity_from_the_datastore_programmatically.3F"><span class="tocnumber">3.3</span> <span class="toctext">How do I resume an activity from the datastore programmatically?</span></a></li>
</ul></li></ul><br>Also, for those who are experienced with writing the actual datastore code, I had the following questions that came up while trying to understand how this module works:<br><br>?? Is there a specific reason why there isn't a "set()" method in the
datastore.DSMetadata class? Shouldn't people be given standard
accessors and mutators to work with this code. This is especially
confusing because it seems there is presently a "get()" method, but the
set() method does not exist (so the abstraction is completely different
based on whether you are getting or setting data). d<br id="cnuv">
<br id="cnuv0">
?? Several things that are currently
documented at
<a href="http://wiki.laptop.org/go/Low-level_Activity_API#Keeping_and_Resuming">http://wiki.laptop.org/go/Low-level_Activity_API#Keeping_and_Resuming</a>
are outdated. Specifically, it says datastore.create() returns the
object_id. That's wrong, it returns the actual DSObject. Furthermore,
it says there are methods called datastore.update and
datastore.get_properties, but they don't exists. <br id="ixhg">
<br id="ixhg0">
??
The deletion/destruction of datastore activities seems to be a little
confusing. In particular, there is a datastore.delete() method and
there is also a DSObject.destroy() method. Why doesn't
datastore.delete() simply call the destroy() method in its code so that
any files associated with the deleted datastore object are also
removed. Given that a warning is thrown telling the developer that an
object is deleted without directly calling DSObject.destroy() (it is
called indirectly through the __del__ method, but why not have things
more explicit?), I'm not sure why this isn't just done
programmatically. Is there ever a reason why one woul perform a
delete() on an object without doing the functionality in
DSObject.destroy() and are any of these reasons compelling enough that
we should keep the delete() and destroy() methods as they are now?<br><br><br>Other questions may come up as people work more on this documentation. In the meantime, I'd greatly appreciate any feedback on the existing work and also any answers to the questions above. <br>
<br><br><br>Faisal<br><br>