JIO is mapped after the CouchDB API and extends them to provide unified, scalable and high performance access via Javascript to a wide variety of different storage backends.
If you are unfamiliar with Apache CouchDB: it is a scalable, fault-tolerant, and schema-free document-oriented database. It is used in large and small organizations for a variety of applications where traditional SQL databases are not the best solution for the problem at hand. CouchDB provides a RESTful HTTP/JSON API accessible by many programming libraries and tools (like curl or Pouchdb) and has its own conflict management system.
A document is an association of metadata and attachment(s). The metadata is the set of properties of the document and the attachments are the binaries of the content of the document.
In jIO, metadata is just a dictionnary with keys and values (JSON object), and attachments are just simple strings.
1 2 3 4 5 6 | {
// document metadata
"_id" : "Identifier",
"title" : "A Title!",
"creator": "Mr.Author"
}
|
You can also retrieve document attachment metadata in this object.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | {
// document metadata
"_id" : "Identifier",
"title" : "A Title!",
"creator": "Mr.Author",
"_attachments": {
// attachment metadata
"body.html": {
"length": 12893,
"digest": "sha256-XXXX...",
"content_type": "text/html"
}
}
}
|
Here is a draft about metadata to use with jIO.
Below you can find sample calls of the main jIO methods. All examples are using revisions (as in revision storage or replicate revision storage), so you can see how method calls should be made with either of these storages.
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 | // Create a new jIO instance
var jio_instance = jIO.newJio(storage tree description);
// create and store new document
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"}).
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"}).
then(function (response) {
// console.log(response);
});
// read a 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"}).
then(function (response) {
// console.log(response);
});
// delete a document and its attachment(s)
jio_instance.remove({"_id": "my_document"}).
then(function (response) {
// console.log(response):
});
// delete an attachment
jio_instance.removeAttachment({"_id": "my_document", "_attachment": "its_attachment"}).
then(function (response) {
// console.log(response):
});
// get all documents
jio_instance.allDocs().then(function (response) {
// console.log(response):
});
|
Each JIO methods returns a Promise object, which allows us to get responses into callback parameters and to chain callbacks with other returned values.
JIO uses a custom version of RSVP.js, adding canceler and progression features.
You can read more about promises:
To retrieve JIO responses, you have to provide callbacks like this:
jio_instance.post(metadata, [options]).
then([responseCallback], [errorCallback], [progressionCallback]);
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 | {
"result": "success",
"method": "post",
// or put or remove
"id": "my_doc_id",
"status": 204,
"statusText": "No Content"
}
|
No options | putAttachment, removeAttachment | {
"result": "success",
"method": "putAttachment",
// or removeAttachment
"id": "my_doc_id",
"attachment": "my_attachment_id",
"status": 204,
"statusText": "No Content"
}
|
No options | get | {
"result": "success",
"method": "get",
"id": "my_doc_id",
"status": 200,
"statusText": "Ok",
"data": {
// Here, the document metadata
}
}
|
No options | getAttachment | {
"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 | {
"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 | {
"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
}
}]
}
}
|
In case of error, the errorCallback first parameter will look like:
{
"result": "error",
"method": "get",
"status": 404,
"statusText": "Not Found",
"error": "not_found",
"reason": "document missing",
"message": "Unable to get the requseted document"
}
The following shows how to create a new jIO in localStorage and then post a document with two attachments.
// create a new jIO
var jio_instance = jIO.newJio({
"type": "local",
"username": "usr",
"application_name":"app"
});
// post the document "metadata"
jio_instance.post({
"title" : "My Video",
"type" : "MovingImage",
"format" : "video/ogg",
"description" : "Images Compilation"
}, function (err, response) {
var id;
if (err) {
return alert('Error posting the document meta');
}
id = response.id;
// post a thumbnail attachment
jio_instance.putAttachment({
"_id": id,
"_attachment": "thumbnail",
"_data": my_image,
"_mimetype": "image/jpeg"
}, function (err, response) {
if (err) {
return alert('Error attaching thumbnail');
}
// post video attachment
jio_instance.putAttachment({
"_id": id,
"_attachment": "video",
"_data": my_video,
"_mimetype":"video/ogg"
}, function (err, response) {
if (err) {
return alert('Error attaching the video');
}
alert('Video Stored');
});
});
});
localStorage contents:
{
"jio/local/usr/app/12345678-1234-1234-1234-123456789012": {
"_id": "12345678-1234-1234-1234-123456789012",
"title": "My Video",
"type": "MovingImage",
"format": "video/ogg",
"description": "Images Compilation",
"_attachments":{
"thumbnail":{
"digest": "md5-3ue...",
"content_type": "image/jpeg",
"length": 17863
},
"video":{
"digest": "md5-0oe...",
"content_type": "video/ogg",
"length": 2840824
}
}
},
"jio/local/usr/app/myVideo/thumbnail": "/9j/4AAQSkZ...",
"jio/local/usr/app/myVideo/video": "..."
}