Skip to content

J
jio
Commit 5bc341ea authored by lucas.parsy's avatar lucas.parsy
Browse files
Options

corrected misspellings and ambiguous examples in manage_document file. 

deleted gid and revision storage documentation.
parent 30f1edbb
Hide whitespace changes
Inline Side-by-side
Showing with 3 additions and 331 deletions
docs/gid_storage.rst deleted 100644 → 0
View file @ 30f1edbb
.. _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
is then used to find this unique document on all types of backends.
This storage uses sub storage ``.allDocs()`` and queries to find unique
documents, and converts their ids to gids.
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 defining 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 attributes (``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 attribute within
a ``"content"`` key. The object can contains custom keys with string values. A
metadata object 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 attributes which names 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 storages have to support options for queries and ``include_docs``.
Dependencies
------------
No dependency.
Suggested storage tree
----------------------
Replication between storages::
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/manage_documents.rst
View file @ 5bc341ea
......@@ -46,13 +46,13 @@ Below you can see examples of the main jIO methods.
var jio_instance = jIO.createJIO(storage_description);
// create and store new document
jio_instance.post('document_name').
jio_instance.post({title: 'my document'}).
then(function (response) {
// console.log(response);
});
// create or update an existing document
jio_instance.put('document_name', {}).
jio_instance.put('document_name', {title: 'another document'}).
then(function (response) {
// console.log(response);
});
......@@ -60,7 +60,7 @@ Below you can see examples of the main jIO methods.
// add an attachment to a document
jio_instance.putAttachment('document_name',
'attachment_name',
new_blob([data], {'type' : data_mimetype});
new Blob([data], {'type' : data_mimetype});
).
then(function (response) {
// console.log(response);
......
docs/revision_storages.rst deleted 100644 → 0
View file @ 30f1edbb
.. _revision-storages-conflicts-and-resolution:
Revision Storages: Conflicts and Resolution
===========================================
Why Conflicts can Occur
-----------------------
Using jIO you can store documents in multiple locations. With an
increasing number of users working on a document and some storages not being
available or responding too slow, conflicts are more likely to occur. jIO
defines a conflict as multiple versions of a document existing in a storage
tree and a user trying to save on a version that does not match the latest
version of the document.
To keep track of document versions a revision storage must be used. When doing
so, jIO creates a document tree file for every document. This file contains all
existing versions and their status and is modified whenever a version is
added/updated/removed or when storages are being synchronized.
How to solve conflicts
----------------------
Using the document tree, jIO tries to make every version of a document
available on every storage. When multiple versions of a document exist, jIO
will select the **latest**, **left-most** version on the document tree, along with the
conflicting versions (when option **conflicts: true** is set in order for
developers to setup a routine to solve conflicts.
Technically, a conflict is solved by deleting alternative versions of a document
("cutting leaves off from the document tree"). When a user decides to keep a
version of a document and manually deletes all conflicting versions, the
storage tree is updated accordingly and the document is available in a single
version on all storages.
Simple Conflict Example
-----------------------
.. TODO this is a little confusing
You are keeping a namecard file on your PC updating from your smartphone. Your
smartphone ran out of battery and is offline when you update your namecard on
your PC with your new email adress. Someone else changes this email from your PC
and once your smartphone is recharged, you go back online and the previous
update is executed.
#. Set up the storage tree:
.. code-block:: javascript
var jio_instance = jIO.createJIO({
// replicate revision storage
type: 'replicaterevision',
storagelist:[{
type: 'revision',
sub_storage: {
type: 'dav',
...
}
}, {
type: 'revision',
sub_storage: {
type: 'local',
...
}
}]
});
#. Create the namecard on your smartphone:
.. code-block:: javascript
jio_instance.post({
_id: 'myNameCard',
email: 'me@web.com'
}).then(function (response) {
// response.id -> 'myNameCard'
// response.rev -> '1-5782E71F1E4BF698FA3793D9D5A96393'
});
This will create the document on your WebDAV and local storage
#. Someone else updates your shared namecard on WebDAV:
.. code-block:: javascript
jio_instance.put({
email: 'my_new_me@web.com',
_id: 'myNameCard'
_rev: '1-5782E71F1E4BF698FA3793D9D5A96393'
}).then(function (response) {
// response.id -> 'myNameCard'
// response.rev -> '2-068E73F5B44FEC987B51354DFC772891'
});
Your smartphone is offline, so now you will have one version (1-578...) on
your smartphone and another version on WebDAV (2-068...) on your PC.
#. You modify the namecard while being offline:
.. code-block:: javascript
jio_instance.get({_id: 'myNameCard'}).then(function (response) {
// response.id -> 'myNameCard'
// response.rev -> '1-5782E71F1E4BF698FA3793D9D5A96393'
// response.data.email -> 'me@web.com'
return jio_instance.put({
_id: 'myNameCard',
email: 'me_again@web.com'
});
}).then(function (response) {
// response.id -> 'myNameCard'
// response.rev -> '2-3753476B70A49EA4D8C9039E7B04254C'
});
#. Later, your smartphone is online and you retrieve the other version of the namecard:
.. code-block:: javascript
jio_instance.get({_id: 'myNameCard'}).then(function (response) {
// response.id -> 'myNameCard'
// response.rev -> '2-3753476B70A49EA4D8C9039E7B04254C'
// response.data.email -> 'me_again@web.com'
});
When multiple versions of a document are available, jIO returns the latest,
left-most version on the document tree (2-375... and labels all other
versions as conflicting 2-068...).
#. Retrieve conflicts by setting option:
.. code-block:: javascript
jio_instance.get({_id: 'myNameCard'}, {
conflicts: true
}).then(function (response) {
// response.id -> 'myNameCard'
// response.rev -> '2-3753476B70A49EA4D8C9039E7B04254C',
// response.conflicts -> ['2-068E73F5B44FEC987B51354DFC772891']
});
The conflicting version (*2-068E...*) is displayed, because **{conflicts: true}** was
specified in the GET call. Deleting either version will solve the conflict.
#. Delete the conflicting version:
.. code-block:: javascript
jio_instance.remove({
_id: 'myNameCard',
_rev: '2-068E73F5B44FEC987B51354DFC772891'
}).then(function (response) {
// response.id -> 'myNameCard'
// response.rev -> '3-28910A4937537B5168E772896B70EC98'
});
When deleting the conflicting version of your namecard, jIO removed it
from all storages and set the document tree leaf of that version to
*deleted*. All storages now contain just a single version of the namecard
(2-3753...). Note that, on the document tree, removing a revison will
create a new revision with status set to *deleted*.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7