Skip to content

J
jio
Commit 4b50d859 authored by Marco Mariani's avatar Marco Mariani
Browse files
Options

docs: newJio -> createJIO, minor fixes, lighter markup

parent 32a85df8
Hide whitespace changes
Inline Side-by-side
Showing with 248 additions and 250 deletions
docs/available_storages.rst
View file @ 4b50d859
......@@ -28,9 +28,9 @@ LocalStorage
Three methods are provided:
* :js:`createDescription(username, [application_name], [mode="localStorage"])`
* :js:`createLocalDescription(username, [application_name])`
* :js:`createMemoryDescription(username, [application_name])`
* :js:`.createDescription(username, [application_name], [mode='localStorage'])`
* :js:`.createLocalDescription(username, [application_name])`
* :js:`.createMemoryDescription(username, [application_name])`
All parameters are strings.
......@@ -39,10 +39,10 @@ Examples:
.. code-block:: javascript
// to work on browser localStorage
var jio = jIO.createJIO(local_storage.createDescription("me"));
var jio = jIO.createJIO(local_storage.createDescription('me'));
// to work on browser memory
var jio = jIO.createJIO(local_storage.createMemoryDescription("me"));
var jio = jIO.createJIO(local_storage.createMemoryDescription('me'));
DavStorage
......@@ -70,7 +70,7 @@ parameter required?
``password`` if auth-type != 'none'
============= ========================
If ``auth_type`` is "none", then ``realm``, ``username`` and ``password`` are never used.
If ``auth_type`` is the string ``"none"``, then ``realm``, ``username`` and ``password`` are never used.
**Be careful**: The generated description never contains a readable password, but
for basic authentication, the password will just be base64 encoded.
......@@ -92,7 +92,7 @@ IndexStorage
^^^^^^^^^^^^
This handler indexes documents metadata into a database (which is a simple
document) to increase the speed of ``allDocs()`` requests. However, it is not able to
document) to increase the speed of ``.allDocs()`` requests. However, it is not able to
manage the ``include_docs`` option.
The sub storages have to manage ``query`` and ``include_docs`` options.
......@@ -102,28 +102,28 @@ Here is the description:
.. code-block:: javascript
{
"type": "index",
"indices": [{
type: 'index',
indices: [{
// doc id where to store indices
"id": "index_title_subject.json",
id: 'index_title_subject.json',
// metadata to index
"index": ["title", "subject"],
"attachment": "db.json", // default "body"
index: ['title', 'subject'],
attachment: 'db.json', // default 'body'
// additional metadata to add to database, default undefined
"metadata": {
"type": "Dataset",
"format": "application/json",
"title": "My index database",
"creator": "Me"
metadata: {
type: 'Dataset',
format: 'application/json',
title: 'My index database',
creator: 'Me'
},
// default equal to parent sub_storage field
"sub_storage": <sub storage where to store index>
sub_storage: <sub storage where to store index>
}, {
"id": "index_year.json",
"index": "year"
id: 'index_year.json',
index: 'year'
...
}],
"sub_storage": <sub storage description>
sub_storage: <sub storage description>
}
......
docs/complex_queries.rst
View file @ 4b50d859
......@@ -42,20 +42,20 @@ Example:
var options = {};
// search text query
options['query'] = '(creator:"John Doe") AND (format:"pdf")';
options.query = '(creator:"John Doe") AND (format:"pdf")';
// OR query tree
options['query'] = {
type:'complex',
operator:'AND',
options.query = {
type: 'complex',
operator: 'AND',
query_list: [{
"type": "simple",
"key": "creator",
"value": "John Doe"
type: 'simple',
key: 'creator',
value: 'John Doe'
}, {
"type": "simple",
"key": "format",
"value": "pdf"
type: 'simple',
key: 'format',
value: 'pdf'
}]
};
......@@ -168,8 +168,8 @@ want to use a wildcard, just set the wildcard character to an empty string.
.. code-block:: javascript
var query = {
"query": 'creator:"* Doe"',
"wildcard_character": "*"
query: 'creator:"* Doe"',
wildcard_character: '*'
};
......@@ -192,8 +192,8 @@ Example, convert Query object into a human readable string:
var query = complex_queries.QueryFactory.
create('year: < 2000 OR title: "*a"'),
option = {
"wildcard_character": "*",
"limit": [0, 10]
wildcard_character: '*',
limit: [0, 10]
},
human_read = {
"<": "is lower than ",
......
docs/getting_started.rst
View file @ 4b50d859
......@@ -30,23 +30,21 @@ Getting started
.. code-block:: javascript
require.config({
"paths": {
paths: {
// jio core + dependency
// the AMD compatible version of sha256.js, see Download and Fork
"sha256": "sha256.amd",
"rsvp": "rsvp-custom",
"jio": "jio",
sha256: 'sha256.amd', // AMD-compatible version of sha256.js
rsvp: 'rsvp-custom',
jio: 'jio',
// storages + dependencies
"complex_queries": "complex_queries",
"localstorage": "localstorage",
"davstorage": "davstorage"
complex_queries: 'complex_queries',
localstorage: 'localstorage',
davstorage: 'davstorage'
}
});
#. jIO connects to a number of storages and allows adding handlers (or
functions) to specifc storages.
functions) to specific storages.
You can use both handlers and available storages to build a storage
tree across which all documents will be maintained and managed by jIO.
......@@ -59,30 +57,30 @@ Getting started
#. The jIO API provides ten main methods to manage documents across the storage(s) specified in your jIO storage tree.
====================== ========================================================
Method Example
====================== ========================================================
``post()`` | :js:`my_jio.post(document, [options]);`
| Creates a new document
``put()`` | :js:`my_jio.put(document, [options]);`
| Creates/Updates a document
``putAttachment()`` | :js:`my_jio.putAttachement(attachment, [options]);`
| Updates/Adds an attachment to a document
``get()`` | :js:`my_jio.get(document, [options]);`
| Reads a document
``getAttachment()`` | :js:`my_jio.getAttachment(attachment, [options]);`
| Reads a document attachment
``remove()`` | :js:`my_jio.remove(document, [options]);`
| Deletes a document and its attachments
``removeAttachment()`` | :js:`my_jio.removeAttachment(attachment, [options]);`
| Deletes a document's attachment
``allDocs()`` | :js:`my_jio.allDocs([options]);`
| Retrieves a list of existing documents
``check()`` | :js:`my_jio.check(document, [options]);`
| Check the document state
``repair()`` | :js:`my_jio.repair(document, [options]);`
| Repair the document
====================== ========================================================
======================= ========================================================
Method Example
======================= ========================================================
``.post()`` | :js:`my_jio.post(document, [options]);`
| Creates a new document
``.put()`` | :js:`my_jio.put(document, [options]);`
| Creates/Updates a document
``.putAttachment()`` | :js:`my_jio.putAttachement(attachment, [options]);`
| Updates/Adds an attachment to a document
``.get()`` | :js:`my_jio.get(document, [options]);`
| Reads a document
``.getAttachment()`` | :js:`my_jio.getAttachment(attachment, [options]);`
| Reads a document attachment
``.remove()`` | :js:`my_jio.remove(document, [options]);`
| Deletes a document and its attachments
``.removeAttachment()`` | :js:`my_jio.removeAttachment(attachment, [options]);`
| Deletes a document's attachment
``.allDocs()`` | :js:`my_jio.allDocs([options]);`
| Retrieves a list of existing documents
``.check()`` | :js:`my_jio.check(document, [options]);`
| Checks the document state
``.repair()`` | :js:`my_jio.repair(document, [options]);`
| Repairs the document
======================= ========================================================
......@@ -114,8 +112,8 @@ Storage dependencies
* `jquery.js <http://code.jquery.com/jquery.js>`_
* `Stanford Javascript Crypto Library <http://bitwiseshiftleft.github.io/sjcl/>`_, [`sjcl.zip <https://crypto.stanford.edu/sjcl/sjcl.zip>`_]
* `sha1 <http://pajhome.org.uk/crypt/md5/sha1.html>`_, [`sha1.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/lib/jsSha1/sha1.js>`_], AMD compatible version: `sha1.amd.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/sha1.amd.js>`_
* `sha2, sha256 <http://anmar.eu.org/projects/jssha2/>`_, `jssha2.zip <http://anmar.eu.org/projects/jssha2/files/jssha2-0.3.zip>`_, AMD compatible versions: `sha2.amd.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/sha2.amd.js>`_, `sha256.amd.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/sha256.amd.js>`_
* `sha1 <http://pajhome.org.uk/crypt/md5/sha1.html>`_, [`sha1.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/lib/jsSha1/sha1.js>`_], AMD-compatible version: `sha1.amd.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/sha1.amd.js>`_
* `sha2, sha256 <http://anmar.eu.org/projects/jssha2/>`_, `jssha2.zip <http://anmar.eu.org/projects/jssha2/files/jssha2-0.3.zip>`_, AMD-compatible versions: `sha2.amd.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/sha2.amd.js>`_, `sha256.amd.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/sha256.amd.js>`_
Storage connectors
^^^^^^^^^^^^^^^^^^
......
docs/gid_storage.rst
View file @ 4b50d859
......@@ -9,7 +9,7 @@ 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 complex queries to find unique documents, and converts their ids to gids.
This storage uses sub storage ``.allDocs()`` and complex queries to find unique documents, and converts their ids to gids.
Where it can be used
--------------------
......
docs/index.rst
View file @ 4b50d859
......@@ -15,9 +15,9 @@ retrieve documents and specific information across storage trees.
How does it work?
-----------------
jIO is composed of two parts - jIO core and storage library(ies). The core
is using storage libraries (connectors) to interact with the associated remote
storage servers. Some queries can be used on top of the jIO ``allDocs()`` method to
jIO is composed of two parts - jIO core and storage libraries. The core
makes use of storage libraries (connectors) to interact with the associated remote
storage servers. Some queries can be used on top of the ``.allDocs()`` method to
query documents based on defined criteria.
jIO uses a job management system, so each method call adds a job into a
......
docs/manage_documents.rst
View file @ 4b50d859
......@@ -26,9 +26,9 @@ attachments are simple strings.
{
// document metadata
"_id" : "Identifier",
"title" : "A Title!",
"creator": "Mr.Author"
_id: 'Identifier',
title: 'A Title!',
creator: 'Mr.Author'
}
You can also retrieve document attachment metadata in this object.
......@@ -37,15 +37,15 @@ You can also retrieve document attachment metadata in this object.
{
// document metadata
"_id" : "Identifier",
"title" : "A Title!",
"creator": "Mr.Author",
"_attachments": {
_id : 'Identifier',
title : 'A Title!',
creator: 'Mr.Author',
_attachments: {
// attachment metadata
"body.html": {
"length": 12893,
"digest": "sha256-XXXX...",
"content_type": "text/html"
'body.html': {
length: 12893,
digest: 'sha256-XXXX...',
content_type: 'text/html'
}
}
}
......@@ -63,51 +63,51 @@ see how method calls should be made with either of these storages.
.. code-block:: javascript
// Create a new jIO instance
var jio_instance = jIO.newJio(storage tree description);
var jio_instance = jIO.createJIO(storage tree description);
// create and store new document
jio_instance.post({"title": "some title"}).
jio_instance.post({title: 'some title'}).
then(function (response) {
// console.log(response);
});
// create or update an existing document
jio_instance.put({"_id": "my_document", "title": "New Title"}).
jio_instance.put({_id: 'my_document', title: 'New Title'}).
then(function (response) {
// console.log(response);
});
// add an attachment to a document
jio_instance.putAttachment({"_id": "my_document",
"_attachment": "its_attachment",
"_data": "abc",
"_mimetype": "text/plain"}).
jio_instance.putAttachment({_id: 'my_document',
_attachment: 'its_attachment',
_data: 'abc',
_mimetype: 'text/plain'}).
then(function (response) {
// console.log(response);
});
// read a document
jio_instance.get({"_id": "my_document"}).
jio_instance.get({_id: 'my_document'}).
then(function (response) {
// console.log(response);
});
// read an attachment
jio_instance.getAttachment({"_id": "my_document",
"_attachment": "its_attachment"}).
jio_instance.getAttachment({_id: 'my_document',
_attachment: 'its_attachment'}).
then(function (response) {
// console.log(response);
});
// delete a document and its attachment(s)
jio_instance.remove({"_id": "my_document"}).
jio_instance.remove({_id: 'my_document'}).
then(function (response) {
// console.log(response);
});
// delete an attachment
jio_instance.removeAttachment({"_id": "my_document",
"_attachment": "its_attachment"}).
jio_instance.removeAttachment({_id: 'my_document',
_attachment: 'its_attachment'}).
then(function (response) {
// console.log(response);
});
......@@ -151,91 +151,91 @@ To retrieve jIO responses, you have to provide callbacks like this:
Here is a list of responses returned by jIO according to methods and options:
================== =========================================== ===============================================
Option Available for Response (Callback first parameter)
================== =========================================== ===============================================
No options ``post()``, ``put()``, ``remove()`` .. code-block:: javascript
================== ============================================== ===============================================
Option Available for Response (Callback first parameter)
================== ============================================== ===============================================
No options ``.post()``, ``.put()``, ``.remove()`` .. code-block:: javascript
{
"result": "success",
"method": "post",
// or put or remove
"id": "my_doc_id",
"status": 204,
"statusText": "No Content"
}
No options ``putAttachment()``, ``removeAttachment()`` .. code-block:: javascript
{
"result": "success",
"method": "putAttachment",
// or removeAttachment
"id": "my_doc_id",
"attachment": "my_attachment_id",
"status": 204,
"statusText": "No Content"
}
No options ``get()`` .. code-block:: javascript
{
"result": "success",
"method": "get",
"id": "my_doc_id",
"status": 200,
"statusText": "Ok",
"data": {
// Here, the document metadata
}
}
No options ``getAttachment()`` .. code-block:: javascript
{
"result": "success",
"method": "getAttachment",
"id": "my_doc_id",
"attachment": "my_attachment_id",
"status": 200,
"statusText": "Ok",
"data": Blob // Here, the attachment content
}
No option ``allDocs()`` .. code-block:: javascript
{
"result": "success",
"method": "allDocs",
"id": "my_doc_id",
"status": 200,
"statusText": "Ok",
"data": {
"total_rows": 1,
"rows": [{
"id": "mydoc",
"key": "mydoc", // optional
"value": {},
}]
}
}
include_docs: true ``allDocs()`` .. code-block:: javascript
{
"result": "success",
"method": "allDocs",
"id": "my_doc_id",
"status": 200,
"statusText": "Ok",
"data": {
"total_rows": 1,
"rows": [{
"id": "mydoc",
"key": "mydoc", // optional
"value": {},
"doc": {
// Here, "mydoc" metadata
}
}]
}
}
================== =========================================== ===============================================
{
result: 'success',
method: 'post',
// or put or remove
id: 'my_doc_id',
status: 204,
statusText: 'No Content'
}
No options ``.putAttachment()``, ``.removeAttachment()`` .. code-block:: javascript
{
result: 'success',
method: 'putAttachment',
// or removeAttachment
id: 'my_doc_id',
attachment: 'my_attachment_id',
status: 204,
statusText: 'No Content'
}
No options ``.get()`` .. code-block:: javascript
{
result: 'success',
method: 'get',
id: 'my_doc_id',
status: 200,
statusText: 'Ok',
data: {
// Here, the document metadata
}
}
No options ``.getAttachment()`` .. code-block:: javascript
{
result: 'success',
method: 'getAttachment',
id: 'my_doc_id',
attachment: 'my_attachment_id',
status: 200,
statusText: 'Ok',
data: Blob // Here, the attachment content
}
No option ``.allDocs()`` .. code-block:: javascript
{
result: 'success',
method: 'allDocs',
id: 'my_doc_id',
status: 200,
statusText: 'Ok',
data: {
total_rows: 1,
rows: [{
id: 'mydoc',
key: 'mydoc', // optional
value: {},
}]
}
}
include_docs: true ``.allDocs()`` .. code-block:: javascript
{
result: 'success',
method: 'allDocs',
id: 'my_doc_id',
status: 200,
statusText: 'Ok',
data: {
total_rows: 1,
rows: [{
id: 'mydoc',
key: 'mydoc', // optional
value: {},
doc: {
// Here, 'mydoc' metadata
}
}]
}
}
================== ============================================== ===============================================
......@@ -245,13 +245,13 @@ In case of error, the ``errorCallback`` first parameter will look like:
.. code-block:: javascript
{
"result": "error",
"method": "get",
"status": 404,
"statusText": "Not Found",
"error": "not_found",
"reason": "document missing",
"message": "Unable to get the requested document"
result: 'error',
method: 'get',
status: 404,
statusText: 'Not Found',
error: 'not_found',
reason: 'document missing',
message: 'Unable to get the requested document'
}
......@@ -264,18 +264,18 @@ The following example creates a new jIO in localStorage and then posts a documen
.. code-block:: javascript
// create a new jIO
var jio_instance = jIO.newJio({
"type": "local",
"username": "usr",
"application_name":"app"
var jio_instance = jIO.createJIO({
type: 'local',
username: 'usr',
application_name: 'app'
});
// post the document "metadata"
// post the document 'metadata'
jio_instance.post({
"title" : "My Video",
"type" : "MovingImage",
"format" : "video/ogg",
"description" : "Images Compilation"
title : 'My Video',
type : 'MovingImage',
format : 'video/ogg',
description : 'Images Compilation'
}, function (err, response) {
var id;
if (err) {
......@@ -285,10 +285,10 @@ The following example creates a new jIO in localStorage and then posts a documen
// post a thumbnail attachment
jio_instance.putAttachment({
"_id": id,
"_attachment": "thumbnail",
"_data": my_image,
"_mimetype": "image/jpeg"
_id: id,
_attachment: 'thumbnail',
_data: my_image,
_mimetype: 'image/jpeg'
}, function (err, response) {
if (err) {
return alert('Error attaching thumbnail');
......@@ -296,10 +296,10 @@ The following example creates a new jIO in localStorage and then posts a documen
// post video attachment
jio_instance.putAttachment({
"_id": id,
"_attachment": "video",
"_data": my_video,
"_mimetype":"video/ogg"
_id: id,
_attachment: 'video',
_data: my_video,
_mimetype: 'video/ogg'
}, function (err, response) {
if (err) {
return alert('Error attaching the video');
......
docs/revision_storages.rst
View file @ 4b50d859
......@@ -47,19 +47,19 @@ update is executed.
.. code-block:: javascript
var jio_instance = jIO.newJio({
var jio_instance = jIO.createJIO({
// replicate revision storage
"type":"replicaterevision",
"storagelist":[{
"type": "revision",
"sub_storage": {
"type": "dav",
type: 'replicaterevision',
storagelist:[{
type: 'revision',
sub_storage: {
type: 'dav',
...
}
}, {
"type": "revision",
"sub_storage": {
"type": "local",
type: 'revision',
sub_storage: {
type: 'local',
...
}
}]
......@@ -71,11 +71,11 @@ update is executed.
.. code-block:: javascript
jio_instance.post({
"_id": "myNameCard",
"email": "me@web.com"
_id: 'myNameCard',
email: 'me@web.com'
}).then(function (response) {
// response.id -> "myNameCard"
// response.rev -> "1-5782E71F1E4BF698FA3793D9D5A96393"
// response.id -> 'myNameCard'
// response.rev -> '1-5782E71F1E4BF698FA3793D9D5A96393'
});
This will create the document on your WebDAV and local storage
......@@ -85,12 +85,12 @@ update is executed.
.. code-block:: javascript
jio_instance.put({
"email": "my_new_me@web.com",
"_id": "myNameCard"
"_rev": "1-5782E71F1E4BF698FA3793D9D5A96393"
email: 'my_new_me@web.com',
_id: 'myNameCard'
_rev: '1-5782E71F1E4BF698FA3793D9D5A96393'
}).then(function (response) {
// response.id -> "myNameCard"
// response.rev -> "2-068E73F5B44FEC987B51354DFC772891"
// response.id -> 'myNameCard'
// response.rev -> '2-068E73F5B44FEC987B51354DFC772891'
});
Your smartphone is offline, so now you will have one version (1-578...) on
......@@ -100,19 +100,19 @@ update is executed.
.. code-block:: javascript
jio_instance.get({"_id": "myNameCard"}).then(function (response) {
// response.id -> "myNameCard"
// response.rev -> "1-5782E71F1E4BF698FA3793D9D5A96393"
// response.data.email -> "me@web.com"
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"
_id: 'myNameCard',
email: 'me_again@web.com'
});
}).then(function (response) {
// response.id -> "myNameCard"
// response.rev -> "2-3753476B70A49EA4D8C9039E7B04254C"
// response.id -> 'myNameCard'
// response.rev -> '2-3753476B70A49EA4D8C9039E7B04254C'
});
......@@ -120,10 +120,10 @@ update is executed.
.. 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"
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,
......@@ -134,32 +134,32 @@ update is executed.
.. code-block:: javascript
jio_instance.get({"_id": "myNameCard"}, {
"conflicts": true
jio_instance.get({_id: 'myNameCard'}, {
conflicts: true
}).then(function (response) {
// response.id -> "myNameCard"
// response.rev -> "2-3753476B70A49EA4D8C9039E7B04254C",
// response.conflicts -> ["2-068E73F5B44FEC987B51354DFC772891"]
// 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 conflicting version:
#. Delete the conflicting version:
.. code-block:: javascript
jio_instance.remove({
"_id": "myNameCard",
"_rev": "2-068E73F5B44FEC987B51354DFC772891"
_id: 'myNameCard',
_rev: '2-068E73F5B44FEC987B51354DFC772891'
}).then(function (response) {
// response.id -> "myNameCard"
// response.rev -> "3-28910A4937537B5168E772896B70EC98"
// response.id -> 'myNameCard'
// response.rev -> '3-28910A4937537B5168E772896B70EC98'
});
When deleting the conflicting version of your namecard, jIO removes this
version from all storages and sets the document tree leaf of this version to
deleted. All storages now contain just a single version of the namecard
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