docs: gid-storage

docs/sphinx/source/available_storages.rst

@@ -121,7 +121,7 @@ Here is the description:
 GIDStorage
 ^^^^^^^^^^
 
-`Full description here <http://www.j-io.org/P-JIO-GIDStorage>`_.
+:ref:`Full description here <gid-storage>`.
 
 Updating to v2.0
 

docs/sphinx/source/gid_storage.rst

+
+.. _gid-storage:
+
+JIO GIDStorage
+==============
+
+A storage to enable interoperability between all kind of storages.
+
+A global ID (GID) is a document id which represents a unique document. This ID
+will be used to find this unique document on all kind of backends.
+
+This storage used sub storage allDocs and complex queries to find unique documents, and convert their ids to gids.
+
+Cases where it can be used
+--------------------------
+
+When you want to duplicate/synchronize/split/edit data in different kind of storages (ERP5 + XWiki + Dav + ...).
+
+Storage Description
+-------------------
+
+* ``type`` - ``"gid"``
+* ``sub_storage`` - the sub storage description.
+* ``constraints`` - the constraints to use to generate a gid by define metadata types for some kind of document.
+
+Example:
+
+.. code-block:: javascript
+
+  {
+    "type": "gid",
+    "sub_storage": {<storage description>},
+    "constraints": {
+      "default": { // constraints for all kind of documents
+        // "document metadata": "type of metadata"
+        "type": "list"
+        "title": "string"
+      },
+      "Text": { // document of type 'Text' additional constraints
+        "language": "string"
+      }
+    }
+  }
+
+
+This description tells the *GIDStorage* to use 2 metadata (``type``, ``title``) to define a
+document as unique in the default case. If the document is of type ``Text``, then
+the handler will use 3 metadata (``type``, ``title``, ``language``).
+If these constraints are not respected, then the storage returns an error telling us to
+review the document metadata. Here are samples of document respecting the above
+constraints:
+
+.. code-block:: javascript
+
+  {
+    "type": "Text",
+    "title": "Hello World!",
+    "language": "en"
+  }
+
+  {
+    "type": ["Text", "Web Page"],
+    "title": "My Web Page Title",
+    "language": "en-US",
+    "format": "text/html"
+  }
+
+  {
+    "type": "Image",
+    "title": "My Image Title"
+  }
+
+
+Available metadata types are:
+* ``"json"`` - The json value of the metadata.
+* ``"string"`` - The value as string if it is not a list.
+* ``"list"`` - The value as list.
+* ``"date"`` - The value if it can be converted to a date (as string).
+* ``"DCMIType"`` - A value matching one of the DCMIType Vocabulary (as string).
+* ``"contentType"`` - A value which is a content type (as string).
+* ``["DCMIType", "list"]`` - The value which contains a DCMIType (as list).
+* ``[...]`` - make your own combination.
+
+
+
+Document Requirements
+---------------------
+
+A metadata value must be a string. This string can be placed in an object which
+key is 'content'. The object can contains custom keys with string values. A
+metadata can contain several values. Example:
+
+.. code-block:: javascript
+
+  {
+    "key": "value",
+    // or
+    "key": ["value1", "value2"],
+    // or
+    "key": {"attribute name": "attribute value", "content": "value'},
+    // or
+    "key": [
+      {"scheme": "DCTERMS.URI", "content": "http://foo.com/bar"},
+      "value2",
+      "value3",
+      ...
+    ],
+    ...
+  }
+
+
+Metadata which name begin with an underscore can contain anything.
+
+.. code-block:: javascript
+
+  {
+    "_key": {"whatever": ["blue", []], "a": null}
+  }
+
+Storage Requirements
+--------------------
+
+* This storage is not compatible with *RevisionStorage* and *ReplicateRevisionStorage*.
+* Sub storage have to support complex queries options and ``include_docs`` option.
+
+Dependencies
+------------
+
+No dependency.
+
+Suggested storage tree
+----------------------
+
+Replication Between Storage::
+
+  Replicate Storage
+  +-- GID Storage
+  |   `-- Local Storage
+  +-- GID Storage
+  |   `-- Remote Storage 1
+  `-- GID Storage
+     `-- Remote Storage 2
+
+**CAUTION: All gid storage must have the same description!**
+
+Offline Application Usage::
+
+  Replicate Storage
+  +-- Index Storage with DB in Local Storage
+  |   `-- GID Storage
+  |       `-- ERP5 Storage
+  `-- GID Storage
+      `-- Local Storage
+
+**CAUTION: All gid storage must have the same description!**
+
+
+
+

docs/sphinx/source/index.rst

@@ -15,6 +15,7 @@ Contents:
     manage_documents
     revision_storages
     available_storages
+    gid_storage
     complex_queries
     metadata
     developers