gid_storage.rst 3.85 KB
Newer Older
Marco Mariani's avatar
Marco Mariani committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159

.. _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!**