From 4210e5a24f700e5104333ed014c3269262b66bec Mon Sep 17 00:00:00 2001
From: Christian Mollekopf <chrigi_1@fastmail.fm>
Date: Wed, 23 Dec 2015 12:18:54 +0100
Subject: Docs

---
 docs/applicationdomaintypes.md |  8 +++++---
 docs/storage.md                | 40 +++++++++++++++++++++++++++++++++++++---
 2 files changed, 42 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/applicationdomaintypes.md b/docs/applicationdomaintypes.md
index 502a349..9a50940 100644
--- a/docs/applicationdomaintypes.md
+++ b/docs/applicationdomaintypes.md
@@ -31,18 +31,19 @@ This is a proposed set of types that we will need to evolve into what we actuall
             * Tag
             * Contact Group
             * Thread
-        * Akonadi Resource
+    * Akonadi Resource
+        * Maildir Resource
 
 #### Properties
 ```no-highlight
 Entity: The smallest unit in the akonadi universe
     id: unique identifier in the akonadi storage. Not persistant over db recreations and can therefore only be referenced from within the akonadi database.
-    revision: revision of the entity
-    resource: reference to AkonadiResource:id
 ```
 ```no-highlight
 Domain Object:
     uid: unique identifier of the domain object.
+    revision: revision of the entity
+    resource: reference to AkonadiResource:id of the parent resource.
 ```
 ```no-highlight
 Event:
@@ -61,6 +62,7 @@ Mail:
 ```no-highlight
 Akonadi Resource:
     type: The type of the resource.
+    name: The name of the resource.
 ```
 ```no-highlight
 Maildir Resource:
diff --git a/docs/storage.md b/docs/storage.md
index 26469a7..b6d73fe 100644
--- a/docs/storage.md
+++ b/docs/storage.md
@@ -86,7 +86,7 @@ Storage is split up in multiple named databases that reside in the same database
 ```
 
 The resource can be effectively removed from disk (besides configuration),
-by deleting the `$RESOURCE_IDENTIFIER` directory and everything it contains.
+by deleting the directories matching `$RESOURCE_IDENTIFIER*` and everything they contain.
 
 #### Design Considerations
 * The stores are split by buffertype, so a full scan (which is done by type), doesn't require filtering by type first. The downside is that an additional lookup is required to get from revision to the data.
@@ -95,9 +95,43 @@ by deleting the `$RESOURCE_IDENTIFIER` directory and everything it contains.
 Every operation (create/delete/modify), leads to a new revision. The revision is an ever increasing number for the complete store.
 
 #### Design Considerations
-By having one revision for the complete store instead of one per type, the change replay always works across all types. This is especially important in the write-back
-mechanism that replays the changes to the source.
+By having one revision for the complete store instead of one per type, the change replay always works across all types. This is especially important in the write-back mechanism that replays the changes to the source.
 
+### BLOB properties
+Files are used to handle opaque large properties that should not end up in memory. BLOB properties are in their nature never queriable (extract parts of it to other properties if indexes are required).
+
+For reading:
+
+Resources...
+* store the file in ~/akonadi2/storage/$RESOURCE_IDENTIFIER_files/
+* store the filename in the blob property.
+* delete the file when the corresponding entity is deleted.
+
+Queries...
+* Copy the requested property to /tmp/akonadi2/client_files/ and provide the path in the property
+* The file is guaranteed to exist for the lifetime of the query result.
+
+Clients..
+* Load the file from disk and use it as they wish (moving is fine too)
+
+For writing:
+
+Clients..
+* Request a path from akonadi2 and store the file there.
+* Store the path of the written file in the property.
+
+Resources..
+* move the file to ~/akonadi2/storage/$RESOURCE_IDENTIFIER_files/
+* store the new path in the entity
+
+#### Design Considerations
+Using regular files as the interface has the advantages:
+* Existing mechanisms can be used to stream data directly to disk.
+* The necessary file operations can be efficiently handled depending on OS and filesystem.
+* We avoid reinventing the wheel.
+
+The copy is necessary to guarantee that the file remains for the client/resource even if the resource removes the file on it's side as part of a sync.
+The copy could be optimized by using hardlinks, which is not a portable solution though. For some next-gen copy-on-write filesystems copying is a very cheap operation.
 
 ### Database choice
 By design we're interested in key-value stores or perhaps document databases. This is because a fixed schema is not useful for this design, which makes
-- 
cgit v1.2.3