[Checkins] SVN: Sandbox/J1m/dozodb/src/zc/dozodb/dozodb.js.test checkpoint

[Jim Fulton]

Log message for revision 119480:
  checkpoint

Changed:
  U   Sandbox/J1m/dozodb/src/zc/dozodb/dozodb.js.test

-=-
Modified: Sandbox/J1m/dozodb/src/zc/dozodb/dozodb.js.test
===================================================================
--- Sandbox/J1m/dozodb/src/zc/dozodb/dozodb.js.test	2011-01-10 22:23:01 UTC (rev 119479)
+++ Sandbox/J1m/dozodb/src/zc/dozodb/dozodb.js.test	2011-01-10 22:23:16 UTC (rev 119480)
@@ -10,12 +10,138 @@
 
 Create a store:
 
-    >>> store = zc.dozodb.Store({url: '/store'});
+    >>> var store = zc.dozodb.Store({url: '/store'});
 
 where the url option names a dozodb web resource.  dozodb web
 resources support loading and saving data via GET and POST ajax
-requests. Fopr these tests, we've stubbed out dojo's xhr interface to
+requests. For these tests, we've stubbed out dojo's xhr interface to
 provide implementations that save xhr callbacks and print other data
 passed to xhr.
 
+In case anyone's reading this, I'll walk through a typical usage
+scenario, before I get to the boring stuff. :)
 
+Usage typically starts with a fetch call.  This is what a dojo tree or
+grid will do to get initial data.  The fetch call can pass a query and
+some callbacks.  It's up to the server to interpret the query to
+decide which data to return.
+
+    >>> var request = store.fetch({
+    ...     query: {a: 1, b: 2},
+    ...     onBegin: function (n, r) {
+    ...         assert(r === request);
+    ...         console.log('onBegin '+n);
+    ...     },
+    ...     onComplete: function (items, r) {
+    ...         assert(r === request);
+    ...         pprint('onComplete items', items);
+    ...     }
+    ... });
+    xhr GET: {
+        content: {
+          a: 1,
+          b: 2 },
+        handleAs: "json",
+        preventCache: true,
+        url: "/store" }
+
+So, fetch makes an xhr get with the URL we have it, and the parameters
+passed to it.
+
+There are a number of handlers we can pass to fetch.  See the dojo
+data api.  The onBegin handler exists mainly to let the client the
+total number of items that match the query.  It can be different from
+the total number of items returned if batching parameters were
+provided.
+
+The onComplete handler behaves differently, depending on whether the
+onItem handler was used.  The onItem handler recieves each item
+individually. If it isn't used, then the onComplete handler is passed
+all of the items.
+
+We'll now emulate the server by calling the xhr load callback.
+
+    >>> last_xhr.load({
+    ...     items: [{_p_oid: '1', _p_serial: '1',
+    ...              name: 'root', children: []}],
+    ...     size: 1
+    ... })
+    onBegin 1
+    onComplete items: [
+        { _p_changed: false,
+          _p_id: "1",
+          _p_oid: "1",
+          _p_serial: "1",
+          children: [],
+          name: "root" } ]
+
+The items we get have spplication-level attributes as well as _p_
+attributes used internally bu dozodb. In practice, the object ids and
+serials are 16-digit hex numbers, but the javascript implementation
+doesn't really care what they are.
+
+Now we'll do another fetch, but this time, pass an onItem handler:
+
+    >>> var request = store.fetch({
+    ...     query: {a: 1, b: 2},
+    ...     onBegin: function (n, r) {
+    ...         assert(r === request);
+    ...         console.log('onBegin '+n);
+    ...     },
+    ...     onItem: function (item, r) {
+    ...         assert(r === request);
+    ...         pprint('onItem item', item);
+    ...     },
+    ...     onComplete: function (items, r) {
+    ...         assert(r === request);
+    ...         pprint('onComplete items', items);
+    ...     }
+    ... });
+    xhr GET: {
+        content: {
+          a: 1,
+          b: 2 },
+        handleAs: "json",
+        preventCache: true,
+        url: "/store" }
+
+    >>> last_xhr.load({
+    ...     items: [
+    ...         {_p_oid: '2', _p_serial: '1', name: 'foo', children: []},
+    ...         {_p_oid: '3', _p_serial: '1', name: 'bar',
+    ...          children: [ {_p_oid: '4'}, {_p_oid: '5'}]
+    ...         }],
+    ...     size: 1
+    ... })
+    onBegin 1
+    onItem item: {
+        _p_changed: false,
+        _p_id: "2",
+        _p_oid: "2",
+        _p_serial: "1",
+        children: [],
+        name: "foo" }
+    onItem item: {
+        _p_changed: false,
+        _p_id: "3",
+        _p_oid: "3",
+        _p_serial: "1",
+        children: [
+          { _p_id: "4",
+            _p_oid: "4" },
+          { _p_id: "5",
+            _p_oid: "5" } ],
+        name: "bar" }
+    onComplete items: null
+
+There are a couple of interesting things to note about this:
+
+1. onItem is called for each item and onComplete is passed null,
+   rather than a list of items.
+
+2. The second item had children and the chelidren didn't have any
+   state.  The items returned directly from fetch always have
+   state. They are distinguished by having _p_changed that's false,
+   meaning they are non-ghost objects.  They also have _p_serial,
+   which is used when saving to detect conflicts.
+