redesign notes: add current API

1 files changed, 61 insertions, 0 deletions

diff --git a/datastore-redesign.html b/datastore-redesign.html
index dcf5bcd..3687a61 100644
--- a/datastore-redesign.html
+++ b/datastore-redesign.html
@@ -105,6 +105,7 @@
    <li>data store records "finished" state in database backend</li>
    <li>data store removes hard link in "incoming" queue</li>
    <li>data store invokes callback to activity</li>
+   <li>TODO: who deletes the activity "copy" of the entry?</li>
   </ul>
 
 
@@ -167,6 +168,66 @@
    <li>data store returns all matches</li>
   </ul>
 
+
+  <h2>API</h2>
+  
+  <h3>datastore DBus API</h3>
+  
+  Current API:
+  <dl>
+   <dt><code>create(properties, filename, transfer_ownership)</code></dt>
+   <dd>
+    Create new journal object with metadata given in <code>properties</code>, returns <code>uid</code> / <code>object_id</code>.
+    If <code>transfer_ownership</code> is False the data store will make a copy of the file. Metadata storage and index update
+    is synchronous and while file storage and optimizer run in a separate thread, the API call actually only returns
+    after everything is done (including emitting a <code>Created(uid)</code> signal) and thus is fully synchronous.
+    Returns <code>uid</code> (<code>object_id</code>).
+   </dd>
+
+   <dt><code>update(uid, properties, filename, transfer_ownership)</code></dt>
+   <dd>Submit new version (currently replacing the old version) and/or new metadata of the object identified 
+    by <code>uid</code> (<code>object_id</code>). Similar to <code>create()</code> Metadata storage and index update is synchronous, 
+    file storage and optimizer run in a separate thread, but the API call only returns after everything is done, including
+    emitting an <code>Updated(uid)</code> signal. Doesn't return anything.
+   </dd>
+
+   <dt><code>delete(uid)</code></dt>
+   <dd>Remove given object from data store. Fully synchronous. Doesn't return anything, emits signal <code>Deleted(uid)</code>.</dd>
+
+   <dt><code>get_properties(uid)</code></dt>
+   <dd>Returns (full) metadata for given object. Fully synchronous.</dd>
+
+   <dt><code>get_filename(uid)</code></dt>
+   <dd>Hardlinks or symlinks the given object into a global directory and returns the filename. Fully synchronous.</dd>
+
+   <dt><code>find(query, properties)</code></dt>
+   <dd>Finds entries matching <code>query</code> in the index, returning the values of the requested <code>properties</code>.
+    If the index is unavailable, <em>all</em> entries are returned (but taking <code>limit</code> and <code>offset</code>
+    into account). <code>query</code> is a dictionary and may contain <code>propertyname=value</code> mappings 
+    (that are directly matched against metadata - only <code>timestamp</code> (with a range), <code>uid</code>,
+    <code>activity</code>, <code>activity_id</code>, <code>keep</code> and <code>mime_type</code> are supported so far)
+    in addition to values for <code>limit</code> (max. number of results), <code>offset</code> (skip given number of results) and
+    <code>query</code> ("full-text" search in all properties). Returns estimated number of matching entries (not affected by
+    <code>limit</code> and <code>offset</code>) and requested metadata for matching entries.</dd>
+
+   <dt><code>get_uniquevaluesfor(propertyname, query)</code></dt>
+   <dd>Supposedly would returns a list of all (unique) values associated with given property (metadata) name for all 
+    datastore entries matching query. Only supports <code>propertyname='activity'</code> and 
+    <code>query=None</code>, so a list of all activities (<code>activity</code> / <code>bundle_id</code>) is returned.</dd>
+
+   <dt><code>mount(uri, options)</code></dt>
+   <dd>Compat only. Noop, returns ''.</dd>
+
+   <dt><code>unmount(mount_point_id)</code></dt>
+   <dd>Compat only. Noop, doesn't return anything.</dd>
+
+   <dt><code>mounts()</code></dt>
+   <dd>Compat only. Noop, returns [{'id': 1}].</dd>
+   
+   <dt><code>Stopped()</code></dt>
+   <dd>Signal emitted after datastore has been shut down.</dd>
+  </dl>
+  
  </body>
 </html>