db8

db8 is a device service - com.palm.db - that interfaces to an embedded JSON database. db8 allows apps to store persistent data (data is backed up to the cloud). JavaScript applications can access this service using the following calls. Note that services and applications also have the option to access db8 using Foundations (a loadable framework of utility JavaScript APIs).

See also:


Methods


batch

Execute put, get, del, find (without a watch) and merge operations in one service request. All other database operations are not allowed. Atomicity is NOT guaranteed across batched operations.

Syntax

{
    "operations" : BatchOperation array           
}

Parameters

Argument Required Type Description
operations Yes BatchOperation array Array of operations to perform in the batch.

Returns

Response Succcess: BatchResponse
Failure: ErrResponse

Examples

Enyo

Batch with put, del, and find operations.

enyo.kind({
    name: "enyo.Canon.DbAPI",
    kind: enyo.VFlexBox,
    components: [
        {kind: "DbService", dbKind: "enyo.bffs:1", onFailure: "dbFailure", components: [
            {name: "batchOp", method: "batch", onSuccess: "batchSuccess"}              
        ]},
        {kind: "PageHeader", content: "db8 Code Samples"},
        {kind: "VFlexBox", align: "center", components: [
            {kind: "Button", caption: "Batch", onclick: "batchClick"}
        ]}
    ],
    batchClick: function() {
       var operations = 
          [{"method": "put",
            "params": { 
            "objects": [{ "_kind": "enyo.bffs:1", "lastname": "Fields", 
                          "firstname": "Chester", "state" : "CA", 
                          "nickname":"Smokey",
                          "emails":[{"value":"cfields@gmail.com", "type":"home"},
                                    {"value": "chester.fields@palm.com", "type":"work"}]}]}},       
            {"method": "del",  
                "params":{"query":{"from":"enyo.bffs:1", "where":[{"prop":"state","op":"=","val":"OH"}]}}},
            {"method": "find", 
                "params":{"query":{"from":"enyo.bffs:1", "where":[{"prop":"state","op":"=","val":"CA"}]}}}
          ];      
        this.$.batchOp.call({operations:operations});
    },  
    batchSuccess: function(inSender, inResponse) {
        this.log("Batch success, results=" + enyo.json.stringify(inResponse));
    },                          
    // Log errors to the console for debugging
    dbFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    }
});

Mojo

Batch with put, del, and find operations.

var operations = 
    [{"method" : "put",
      "params" :{ 
       "objects": [{ "_kind": "com.palm.sample:1", "displayName": "Chester Fields", "state" : "CA", 
                     "name": [{"familyName":"Fields", "givenName":"Chester"}], "nickname": "Smokey",
                     "emails":[{"value":"cfields@gmail.com", "type":"home"},
                               {"value": "chester.fields@palm.com", "type":"work"}]}]
                            },
                   },
     {"method": "del", "params":{"ids":["116d"]}},
     {"method": "find","params":{"query":{"from":"com.palm.sample:1",
                                 "where":[{"prop":"state","op":"=","val":"OR"}]}}}];

this.controller.serviceRequest("palm://com.palm.db/", {
    method: "batch",
    parameters: { "operations": operations },
    onSuccess: function(e) { Mojo.Log.info("Batch success! results=" + JSON.stringify(e));},
    onFailure: function(e) { Mojo.Log.info("Batch failure! Err = " + JSON.stringify(e));}
});

Success

Batch success! results={
       "returnValue":true,
       "responses":[
          {
             "returnValue":true,
             "results":[
                {
                   "id":"++HEHBh2FRWQsiSM",
                   "rev":4810
                }
             ]
          },
          {
             "returnValue":true,
             "results":[]
          },
          {
             "returnValue":true,
             "results":[
                {
                   "_id":"++HEDfsxCncIyLO8",
                   "_kind":"com.palm.sample:1",
                   "_rev":4456,
                   "displayName":"Helen Wheels",
                   "emails":[
                      {
                         "_id":"1169",
                         "type":"home",
                         "value":"hwheels@gmail.com"
                      },
                      {
                         "_id":"116a",
                         "type":"work",
                         "value":"helen.wheels@palm.com"
                      }
                   ],
                   "name":[
                      {
                         "_id":"116b",
                         "familyName":"Wheels",
                         "givenName":"Helen"
                      }
                   ],
                   "nickname":"Speedy",
                   "state":"OR"
                }
             ]
          }
       ]
    }

del

Deletes JSON data objects from the database.

Objects can be specified as a set of IDs (returns PutResponse) or as a db8 Query (returns CountResponse).

Syntax

{
   "ids"   : string array,
   "query" : Query,
   "purge" : boolean            
}

Parameters

Argument Required Type Description
ids No string array Array of JSON data object IDs to delete. This or "query" must be specified.
query No Query Query specifying set of objects to delete. This or "ids" must be specified.
purge No boolean Purge immediately flag. If not purged, target objects are marked as deleted and not completely removed until an administrative purge operation is run. Objects marked as deleted can still be retrieved. Default is false.

Returns

Response Succcess: PutResponse (IDs) or CountResponse (query)
Failure: ErrResponse

Examples

Enyo - example delete using ID

enyo.kind({
    name: "enyo.Canon.DbAPI",
    kind: enyo.VFlexBox,
    components: [
        {kind: "DbService", dbKind: "enyo.bffs:1", onFailure: "dbFailure", components: [
            {name: "delBffs", method: "del", onSuccess: "delBffsSuccess"}           
        ]},
        {kind: "PageHeader", content: "db8 Code Samples"},
        {kind: "HFlexBox", align: "center", components: [
            {kind: "Button", caption: "Delete bff objects", onclick: "delBffsClick"}
        ]}
    ],
    delBffsClick: function() {
        this.$.delBffs.call({ids:["++HbZI9gNnKkbiTz"]});
    },
    delBffsSuccess: function(inSender, inResponse) {
        this.log("Delete success, results=" + enyo.json.stringify(inResponse));
    },  
    // Log errors to the console for debugging
    dbFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    }
});

Enyo - example delete using query

enyo.kind({
    name: "enyo.Canon.DbAPI",
    kind: enyo.VFlexBox,
    components: [
        {kind: "DbService", dbKind: "enyo.bffs:1", onFailure: "dbFailure", components: [
            {name: "delBffsQuery", method: "del", onSuccess: "delBffsQuerySuccess"}            
        ]},
        {kind: "PageHeader", content: "db8 Code Samples"},
        {kind: "HFlexBox", align: "center", components: [
            {kind: "Button", caption: "Delete using Query", onclick: "delBffsQueryClick"}
        ]}
    ],
    delBffsQueryClick: function() {
        var q = { "from":"enyo.bffs:1", "where":[{"prop":"state","op":"=","val":"OR"}] };   
        this.$.delBffsQuery.call({query:q});
    },
    delBffsQuerySuccess: function(inSender, inResponse) {
        this.log("Query delete success, results=" + enyo.json.stringify(inResponse));
    },      
    // Log errors to the console for debugging
    dbFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    }
});

Mojo - example delete using ID

var id1 = "++HE8X59Y00hoKrF";
var ids = [id1];
this.controller.serviceRequest("palm://com.palm.db/", {
    method: "del",
    parameters: { "ids": ids },
    onSuccess: function(e) 
    { 
        Mojo.Log.info("del success!");
        Mojo.Log.info("del #1, id="+ e.results[0].id+", rev="+e.results[0].rev);                    
    },
    onFailure: function(e) { Mojo.Log.info("del failure! Err = " + JSON.stringify(e));}
});    

Mojo - example delete using query

var q = { "from":"com.palm.sample:1", "where":[{"prop":"state","op":"=","val":"OR"}] };
this.controller.serviceRequest("palm://com.palm.db/", {
    method: "del",
    parameters: { "query": q },
    onSuccess: function(e) { Mojo.Log.info("del success!, count="+e.count);},
    onFailure: function(e) { Mojo.Log.info("del failure! Err = " + JSON.stringify(e));}
});

Success (IDs)

Delete success, results={
   "returnValue":true,
   "results":[
      {
         "id":"++HbZI9gNnKkbiTz",
         "rev":1339
      }
   ]
}
Success (query)
Delete success, results={
   "returnValue":true,
   "count":1
}

delKind

Deletes a kind object from the database. Deleting a kind deletes ALL data objects of that kind.

Syntax

{
   "id" : string
}

Parameters

Argument Required Type Description
id Yes string ID of kind to delete.

Returns

{
   "returnValue" : boolean,
   "errorCode"   : int,
   "errorText"   : string
}
Element Required Type Description
returnValue Yes boolean true (success) or false (failure)
errorCode No int Error code returned on failure
errorText No string Error message returned on failure

Examples

luna-send

luna-send -n 1 -a com.palmdts.enyo.db-api luna://com.palm.db/delKind '{"id":"enyo.fruits:1"}'
{"returnValue":true}

Enyo

enyo.kind({
    name: "enyo.Canon.DbAPI",
    kind: enyo.VFlexBox,
    components: [
        {kind: "DbService", dbKind: "enyo.bffs:1", onFailure: "dbFailure", components: [
            {name: "deleteBffsDbKind", method: "delKind", onSuccess: "deleteBffsDbKindSuccess"}                 
        ]},
        {kind: "PageHeader", content: "db8 Code Samples"},
        {kind: "HFlexBox", align: "center", components: [
            {kind: "Button", caption: "Delete bffs Kind", onclick: "deleteBffsDbKindClick"}
        ]}
    ],
    deleteBffsDbKindClick: function() {
        this.$.deleteBffsDbKind.call(); // Delete kind
    },
    deleteBffsDbKindSuccess: function() {
        this.log();
    },  
    // Log errors to the console for debugging
    dbFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    }
});

Mojo

var id = "com.palm.sample:1"; // kind + version number
this.controller.serviceRequest("palm://com.palm.db/", {
    method: "delKind",
    parameters: { "id": id },
    onSuccess: function(e) { Mojo.Log.info("delKind success!");},
    onFailure: function(e) { Mojo.Log.info("delKind failure! Err = " + JSON.stringify(e));}
}); 

find

Returns a set of objects matching a query.

If your query is limited to a specified number of results, you can set a flag ("count") to get the number that would have been returned without a limit. You can also set a flag ("watch") to request notification if any of the returned results from the query changes in the future.

Syntax

{
   "query" : Query,
   "count" : boolean,
   "watch" : boolean
}

Parameters

Argument Required Type Description
query Yes Query db8 query for retrieving results.
count No boolean Return number of objects that would have been returned without the limit specified in the query flag. Default is false.
watch No boolean Notify if change flag. Default is false.

Returns

Response Succcess: FindResponse or NotificationResponse
(watch == true)
Failure: ErrResponse

Examples

Enyo - simple find

enyo.kind({
    name: "enyo.Canon.DbAPI",
    kind: enyo.VFlexBox,
    components: [
        {kind: "DbService", dbKind: "enyo.bffs:1", onFailure: "dbFailure", components: [
            {name: "simpleFind", method: "find", onSuccess: "simpleFindSuccess"}                           
        ]},
        {kind: "PageHeader", content: "db8 Code Samples"},
        {kind: "VFlexBox", align: "center", components: [
            {kind: "Button", caption: "Simple find", onclick: "simpleFindClick"}
        ]}
    ],
    simpleFindClick: function() {       
        this.$.simpleFind.call({query:{"from":"enyo.bffs:1"}});
    },
    simpleFindSuccess: function(inSender, inResponse) {
        this.log("Simple find success, results=" + enyo.json.stringify(inResponse));
    },          
    // Log errors to the console for debugging
    dbFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    }
});

Enyo - using where, select, order by, and desc in a query

This sample demonstrates creating a kind, storing objects of that kind, and executing a query against those objects using the "find" method.

enyo.kind({
    name: "enyo.Canon.DbAPI",
    kind: enyo.VFlexBox,
    components: [
        {kind: "DbService", dbKind: "enyo.bffs:1", onFailure: "dbFailure", components: [
            {name: "makeBffsDbKind", method: "putKind", onSuccess: "putDbKindSuccess"},
            {name: "putBffs", method: "put", onSuccess: "putBffsSuccess"},
            {name: "notSimpleFind", method: "find", onSuccess: "notSimpleFindSuccess"}                 
        ]},
        {kind: "PageHeader", content: "db8 Code Samples"},
        {kind: "VFlexBox", align: "center", components: [
            {kind: "Button", caption: "Create bffs kind", onclick: "makeBffsDbKindClick"},
            {kind: "Button", caption: "Put bff objects", onclick: "putBffsClick"},
            {kind: "Button", caption: "Not simple find", onclick: "notSimpleFindClick"}
        ]}
    ],
    makeBffsDbKindClick: function() {
        var indexes = [{"name":"stateLastidx", props:[{"name": "state"}, {"name": "lastname"}]}];
        this.$.makeBffsDbKind.call({owner: enyo.fetchAppId(), indexes:indexes}); // Create db8 kind
    },
    putDbKindSuccess: function() {
        this.log();
    },
    putBffsClick: function() {
         var  bff1 = { _kind: "enyo.bffs:1", lastname: "Syrup", firstname: "Mabel", 
                       nickname: "Sticky", state: "CA",
                       emails:[{"value":"msyrup@gmail.com", "type":"home"},
                               {"value": "mabel.syrup@palm.com", "type":"work"}]};
         var  bff2 = { _kind: "enyo.bffs:1", lastname: "Wheels", firstname: "Helen", 
                       nickname: "Psycho", state: "CA",
                       emails:[{"value":"hwheels@gmail.com", "type":"home"},
                                {"value": "helen.wheels@palm.com", "type":"work"}]};    
         var  bff3 = { _kind: "enyo.bffs:1", lastname: "Manilla", firstname: "Sal", 
                       nickname: "Weasel", state: "CA",
                       emails:[{"value":"smanilla@gmail.com", "type":"home"},
                               {"value": "sal.manilla@palm.com", "type":"work"}]};
         var  bff4 = { _kind: "enyo.bffs:1", lastname: "Kroger", firstname: "Larry", 
                        nickname: "Pinto", state: "OH",
                        emails:[{"value":"lkroger@gmail.com", "type":"home"},
                                {"value": "larry.kroger@palm.com", "type":"work"}]};
         var objs = [bff1, bff2, bff3, bff4];
         this.$.putBffs.call({objects: objs});
    },
    putBffsSuccess: function(inSender, inResponse) {
        this.log("Put success, results=" + enyo.json.stringify(inResponse));
    },
    notSimpleFindClick: function() {
        var fquery = { "select": ["lastname", "firstname", "nickname"],
                       "from":"enyo.bffs:1",
                       "where":[{"prop":"state","op":"=","val":"CA"}], 
                       "orderBy" : "lastname", "desc":true };
        this.$.notSimpleFind.call({query:fquery});
    },
    notSimpleFindSuccess: function(inSender, inResponse) {
        this.log("Not simple find success, results=" + enyo.json.stringify(inResponse));
    },
    // Log errors to the console for debugging
    dbFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    }
});

Mojo - simple find

This query returns all data objects. No notification and no count is requested.

var fquery = {"from":"com.palm.sample:1"};

this.controller.serviceRequest("palm://com.palm.db/", {
    method: "find",
    parameters: { "query": fquery },
    onSuccess: function(e) { Mojo.Log.info("find success!, results="+JSON.stringify(e.results));},
    onFailure: function(e) { Mojo.Log.info("find failure! Err = " + JSON.stringify(e));}
});

Mojo - using where, select, order by, and desc in a query

This query searches for contacts who live in California (state == 'CA'. The displayName and state fields are returned for each match. Returned objects are sorted on the displayName field in descending order. No notification is requested.

//
// Note: A dual index for the kind was created, allowing this call to work:
//         var indexes = [{"name":"dNameState", props:[{"name": "state"}, {"name":"displayName"}]} ];
//
// The query below will not work if 'displayName' is declared as the first 'props' entry and 'state' the second.
// Results can only be returned for contiguously ordered index entries. If you have the 
// entries ["CA", "John Doe"], ["CA","Mabel Syrup"], etc., then, all of the entries with the same state
// are consecutive and only secondarily ordered by display name. Therefore, the index can answer the query.
// If the index entries were ordered in ["displayName", "state"] order, the entries for the same state 
// are not consecutive and could not be used to answer the query (the query would fail with
// a "no index for query" message).

var fquery = {
   "select": ["displayName", "state"],
   "from":"com.mystuff.contacts:1",
   "where":[{"prop":"state","op":"=","val":"CA"}], 
   "orderBy":"displayName",
   "desc":true };

this.controller.serviceRequest("palm://com.palm.db/", {
    method: "find",
    parameters: { "query": fquery },
    onSuccess: function(e)
    { 
        var results = e.results;
        for (i=0; results[i] != null; i++)
         Mojo.Log.info("find #"+i+"  state ="+ results[i].state+", displayName="+results[i].displayName);
    },
    onFailure: function(e) { Mojo.Log.info("find failure! Err = " + JSON.stringify(e));}
}); 

Example 3: Query with change notification

This example shows how change notiification for a find works. The "onSuccess" code is called again if results for the initial query have changed. The "fired" flag is true if this is a notification response.

var fquery = {"select": ["displayName", "state"],"from":"com.palm.sample:1"};

this.controller.serviceRequest("palm://com.palm.db/", {
    method: "find",
    parameters: { "query": fquery, "watch": true },
    onSuccess: function(e) { 
        if (!e.fired)
           Mojo.Log.info("find initial response success, e= " + JSON.stringify(e));
        else {
           Mojo.Log.info("find results changed");
           //
           // Do something, i.e., reissue find
           //
         }  
    },
    onFailure: function(e) { Mojo.Log.info("find failure! Err = " + JSON.stringify(e));}
}); 

get

Gets JSON data objects by IDs. This is the fastest way to retrieve data.

Syntax

{
   "ids" : string array
}

Parameters

Argument Required Type Description
ids Yes string array Array of JSON data object IDs.

Returns

Response Success: GetResponse
Failure: ErrResponse

Examples

luna-send

luna-send -n 1 -a com.palmdts.enyo.db-api luna://com.palm.db/get '{"ids":["++HbZI9gNnKkbiTz", "++HbZI9gONsPzkuB"]}'

Enyo

enyo.kind({
    name: "enyo.Canon.DbAPI",
    kind: enyo.VFlexBox,
    components: [
        {kind: "DbService", dbKind: "enyo.bffs:1", onFailure: "dbFailure", components: [
            {name: "getBffs", method: "get", onSuccess: "getBffsSuccess"}               
        ]},
        {kind: "PageHeader", content: "db8 Code Samples"},
        {kind: "HFlexBox", align: "center", components: [
            {kind: "Button", caption: "Get bff objects", onclick: "getBffsClick"}
        ]}
    ]
    getBffsClick: function() {
        this.$.getBffs.call({ids:["++HbZI9gNnKkbiTz", "++HbZI9gONsPzkuB"]});
    },
    getBffsSuccess: function(inSender, inResponse) {
        this.log("Get success, results=" + enyo.json.stringify(inResponse));
    },  
    // Log errors to the console for debugging
    dbFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    }
});

Mojo

var id1 = "++HE8X59Y00hoKrF";
var id2 = "++HE8X59ZZCfac68";
var ids = [id1, id2];
this.controller.serviceRequest("palm://com.palm.db/", {
    method: "get",
    parameters: { "ids": ids },
    onSuccess: function(e) { 
        Mojo.Log.info("get success!, e=" + JSON.stringify(e));
        var rs = e.results;
        for (i=0; rs[i] != null; i++)
            Mojo.Log.info("get #"+ (i+1) +", id="+ rs[i]._id+", displayName="+rs[i].displayName+", 
                           nickname="+rs[i].nickname+", familyName="+rs[i].name[0].familyName);
    },
    onFailure: function(e) { Mojo.Log.info("get failure! Err = " + JSON.stringify(e));}
});

merge

Updates properties in existing objects. Objects can be specified using a query (returns CountResponse) or array of IDs (returns PutResponse).

Syntax

{
   "objects" : any object array,                     
   "query"   : Query,
   "props"   : any object
}

Parameters

Argument Required Type Description
objects No any object array Array of IDs and properties to update. Either this or "query" is required.
query No Query Query specifying set of objects to merge properties into. Either this or "objects" is required.
props No any object Requires "query". Set of properties to merge into existing object(s) from query.

Returns

Response Succcess: PutResponse (IDs) or CountResponse (query)
Failure: ErrResponse

Examples

Enyo - example using IDs

enyo.kind({
    name: "enyo.Canon.DbAPI",
    kind: enyo.VFlexBox,
    components: [
        {kind: "DbService", dbKind: "enyo.bffs:1", onFailure: "dbFailure", components: [
            {name: "mergeIDs", method: "merge", onSuccess: "mergeIDsSuccess"}        
        ]},
        {kind: "PageHeader", content: "db8 Code Samples"},
        {kind: "HFlexBox", align: "center", components: [
            {kind: "Button", caption: "Merge using IDs", onclick: "mergeIDsClick"}
        ]}
    ],
    mergeIDsClick: function() {
        var m1 = {  "_id": "++Hb_NvTW+3X5oXv", "nickname": "Sugar" };
        var m2 = {  "_id": "++Hb_NvTWYVGPH6N", "nickname": "Swifty" };    
        this.$.mergeIDs.call({"objects": [m1, m2]});
    },
    mergeIDsSuccess: function(inSender, inResponse) {
        this.log("merge success, results=" + enyo.json.stringify(inResponse));
    },      
    // Log errors to the console for debugging
    dbFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    }
});

Enyo - example using query

enyo.kind({
    name: "enyo.Canon.DbAPI",
    kind: enyo.VFlexBox,
    components: [
        {kind: "DbService", dbKind: "enyo.bffs:1", onFailure: "dbFailure", components: [ 
            {name: "mergeQuery", method: "merge", onSuccess: "mergeQuerySuccess"}                  
        ]},
        {kind: "PageHeader", content: "db8 Code Samples"},
        {kind: "HFlexBox", align: "center", components: [
            {kind: "Button", caption: "Merge using Query", onclick: "mergeQueryClick"}
        ]}
    ],
    mergeQueryClick: function() {
        var mprops = { "nickname":"Spud"};
        var mquery = { "from":"enyo.bffs:1","where":[{"prop":"state","op":"=","val":"CA"}] };   
        this.$.mergeQuery.call({"query": mquery, "props": mprops});
    },
    mergeQuerySuccess: function(inSender, inResponse) { 
        this.log("merge success, results=" + enyo.json.stringify(inResponse));
    },      
    // Log errors to the console for debugging
    dbFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    }
});

Mojo - example using IDs

// Create objects to update nickname field
var m1 = {  "_id": "++HECGnRNNF_7TdA", "nickname": "Sugar" };
var m2 = {  "_id": "++HECGnRLstE6iwP", "nickname": "Swifty" };
var mobjs = [m1, m2];

this.controller.serviceRequest("palm://com.palm.db/", {
    method: "merge",
    parameters: { "objects": mobjs },
    onSuccess: function(e) { 
        var results = e.results;
        for (i=0; results[i] != null; i++)
            Mojo.Log.info("merge #"+i+"  id ="+ results[i].id+", rev="+results[i].rev);                       
    },
    onFailure: function(e) { Mojo.Log.info("merge failure! Err = " + JSON.stringify(e));}
}); 

Mojo - example using query

// Assign a property to update, and create the query
// Note that indexes must exist for the fields you are querying on

var mprops = { "nickname":"Spud"};
var mquery = { "from":"com.palm.sample:1","where":[{"prop":"state","op":"%","val":"C"}] };

this.controller.serviceRequest("palm://com.palm.db/", {
    method: "merge",
    parameters: { "query": mquery, "props": mprops},
    onSuccess: function(e) { Mojo.Log.info("merge success!, count= " +e.count);},
    onFailure: function(e) { Mojo.Log.info("merge failure! Err = " + JSON.stringify(e));}
});

put

Puts JSON data objects of a particular kind into the database. Assigns "id" field if not set. Returns "id" and "rev" for each object stored.

Syntax

{
   "objects" : any object array
}

Parameters

Argument Required Type Description
objects Yes any object array Array of JSON data objects of a particular kind to store.

Returns

Response Succcess: PutResponse
Failure: ErrResponse

Examples

Enyo

enyo.kind({
    name: "enyo.Canon.DbAPI",
    kind: enyo.VFlexBox,
    components: [
        {kind: "DbService", dbKind: "enyo.bffs:1", onFailure: "dbFailure", components: [
            {name: "putBffs", method: "put", onSuccess: "putBffsSuccess"}
        ]},
        {kind: "PageHeader", content: "db8 Code Samples"},
        {kind: "HFlexBox", align: "center", components: [
            {kind: "Button", caption: "Put bff objects", onclick: "putBffsClick"}
        ]}
    ],
    putBffsClick: function() {
         var  bff1 = { _kind: "enyo.bffs:1", lastname: "Syrup", firstname: "Mabel",
                       nickname: "Sticky", state: "CA",
                       emails:[{"value":"msyrup@gmail.com", "type":"home"},
                               {"value": "mabel.syrup@palm.com", "type":"work"}]};
         var  bff2 = { _kind: "enyo.bffs:1", lastname: "Wheels", firstname: "Helen", 
                       nickname: "Psycho", state: "OR",
                       emails:[{"value":"hwheels@gmail.com", "type":"home"},
                                {"value": "helen.wheels@palm.com", "type":"work"}]};
        var objs = [bff1, bff2];
        this.$.putBffs.call({objects: objs});
    },
    putBffsSuccess: function(inSender, inResponse) {
        this.log("Put success, results=" + enyo.json.stringify(inResponse));
    },
    // Log errors to the console for debugging
    dbFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    }
});

Mojo

// Create new JSON data objects    
var  contact1 = 
     { _kind: "com.palm.sample:1", displayName: "Mabel Syrup", state : "CA",
       name: [{"familyName":"Syrup", "givenName":"Mabel"}], nickname: "Sticky",
       emails:[{"value":"msyrup@gmail.com", "type":"home"},
               {"value": "mabel.syrup@palm.com", "type":"work"}]};

var  contact2 = 
     { _kind: "com.palm.sample:1", displayName: "Helen Wheels", state : "OR",
       name: [{"familyName":"Wheels", "givenName":"Helen"}], nickname: "Speedy",
       emails:[{"value":"hwheels@gmail.com", "type":"home"},
               {"value": "helen.wheels@palm.com", "type":"work"}]};    

var objs = [contact1, contact2]; // Create object array

this.controller.serviceRequest("palm://com.palm.db/", {
    method: "put",
    parameters: { "objects": objs },
    onSuccess: function(r) { 
        Mojo.Log.info("Put success, results=" + JSON.stringify(r));
        var results = r.results;
        for (i=0; results[i] != null; i++)
            Mojo.Log.info("put #"+i+"  id ="+ results[i].id+", rev="+results[i].rev);                 
    },
    onFailure: function(e) { Mojo.Log.info("put failure! Err = " + JSON.stringify(e));}
});

Success

Put success, results=
{
   "returnValue":true,
   "results":[
      {
         "id":"++HbZI9gNnKkbiTz",
         "rev":1321
      },
      {
         "id":"++HbZI9gONsPzkuB",
         "rev":1324
      }
   ]
}

putKind

Registers a kind JSON object with the database.

Kind objects define the owner and indexes for a JSON data object.

Indexes can be composed of single or multiple fields. When you create your index, be aware that queries can only return results that are indexed and are contiguously ordered. See All Queries Must be on Indexed Fields for more information.

If your app or service wants to be notified only when a subset of an object's properties are updated, then you can use revision sets. See Using Revision Sets for more information.

If your app or service creates objects that other apps or services need to access, then see putPermissions for more information.

Syntax

{
   "id"      : string,
   "owner"   : string,
   "Syntax"  : Syntax,
   "sync"    : boolean,
   "extends" : string array,
   "indexes" : IndexClause array,
   "revSets" : RevSetClause array, 
}

Parameters

Argument Required Type Description
id Yes string Kind identifier.
owner Yes string Kind owner - service's bus address or app's app ID. Only the owner has permission to modify the kind.
Syntax No Syntax JSON Syntax for data objects of this kind. If set, this kind's data objects are validated before being stored.
sync No boolean Backup and restore objects of this kind flag. Objects are backed up to Palm's servers on a daily basis. If the user moves to another device, saved app data can be restored. Default is false.
extends No string array IDs of kind parents.
indexes No IndexClause array Kind indexes.
revSets No RevSetClause array Array of revision sets. See Using Revision Sets for more information.

Returns

{
   "returnValue" : boolean,
   "errorCode"   : int,
   "errorText"   : string
}
Element Required Type Description
returnValue Yes boolean true (success) or false (failure)
errorCode No int Error code returned on failure
errorText No string Error message returned on failure

Examples

luna-send

luna-send -n 1 -a com.palmdts.enyo.db-api luna://com.palm.db/putKind '{"id":"enyo.fruits:1","owner":"com.palmdts.enyo.db-api"}'
{"returnValue":true}

Enyo

enyo.kind({
    name: "enyo.Canon.DbAPI",
    kind: enyo.VFlexBox,
    components: [
        {kind: "DbService", dbKind: "enyo.bffs:1", onFailure: "dbFailure", components: [
            {name: "makeBffsDbKind", method: "putKind", onSuccess: "putDbKindSuccess"}         
        ]},
        {kind: "PageHeader", content: "db8 Code Samples"},
        {kind: "HFlexBox", align: "center", components: [
            {kind: "Button", caption: "Create bffs kind", onclick: "makeBffsDbKindClick"}
        ]}
    ],
    makeBffsDbKindClick: function() {
        var indexes = [{"name":"lastname", props:[{"name": "lastname"}]},
                       {"name":"state", props:[{"name": "state"}]}];
        this.$.makeBffsDbKind.call({owner: enyo.fetchAppId(), indexes:indexes}); // Create db8 kind
    },
    putDbKindSuccess: function() {
        this.log();
    },
    // Log errors to the console for debugging
    dbFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    }
});

Mojo

var indexes = [{"name":"dNameState", props:[{"name": "state"}, {"name":"displayName"}]} ];
this.controller.serviceRequest("palm://com.palm.db/", {
    method: "putKind",
    parameters: { "id":"com.palm.sample:1", 
                  "owner":"com.palm.dbtest",
                  "indexes": indexes
    },
    onSuccess: function() { Mojo.Log.info("putKind success!");},
    onFailure: function(e) { Mojo.Log.info("putKind failure! Err = " + JSON.stringify(e));}
});

putPermissions

Allow other apps or services to access your stored db8 data. Permissions are given to access data objects of a particular kind.

Just Type

For Just Type, you need to grant read permissions to "com.palm.launcher". This allows Just Type to scan your db8 data storage for entries matching the user-entered text.

Syntax

[
  {
      "type"    : string,
      "object"  : string,
      "caller"  : string,
      "operations": {
          "create" : string,
          "read"   : string,
          "update" : string,
          "delete" : string
      }
   }
]

Parameters

Argument Required Type Description
type Yes string Must be "db.kind"
object Yes string db8 kind
caller Yes string ID of App or service being granted permissions.
operations Yes object Operations you are allowing.
create No string Set to "allow" to grant create permissions.
read No string Set to "allow" to grant read permissions.
update No string Set to "allow" to grant update permissions.
delete No string Set to "allow" to grant delete permissions.

Returns

{
   "returnValue" : boolean,
   "errorCode"   : int,
   "errorText"   : string
}
Element Required Type Description
returnValue Yes boolean true (success) or false (failure)
errorCode No int Error code returned on failure
errorText No string Error message returned on failure

Examples

Enyo

enyo.kind({
    name: "enyo.Canon.DbAPI",
    kind: enyo.VFlexBox,
    components: [
        {kind: "DbService", dbKind: "enyo.bffs:1", onFailure: "dbFailure", components: [
            {name: "putPerm", method: "putPermissions", onSuccess: "permSuccess"}   
        ]},
        {kind: "PageHeader", content: "db8 Code Samples"},
        {kind: "VFlexBox", align: "center", components: [
            {kind: "Button", caption: "Put Permissions", onclick: "permClick"}
        ]}
    ],
    permClick: function() {
        var permObj =[{"type":"db.kind","object":'enyo.bffs:1', 
               "caller":"com.palm.launcher", "operations":{"read":"allow"}}];    
        this.$.putPerm.call({permissions:permObj});
    },  
    permSuccess: function(inSender, inResponse) {
        this.log("putPermissions success, results=" + enyo.json.stringify(inResponse));
    },                          
    // Log errors to the console for debugging
    dbFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    }
});

Mojo

var permObj =[{"type":"db.kind","object":'com.palm.sample:1', 
               "caller":"com.palm.launcher", "operations":{"read":"allow"}}];

this.controller.serviceRequest("palm://com.palm.db/", {
        method: "putPermissions",
        parameters: {"permissions":permObj},
        onSuccess: function() { Mojo.Log.info("DB permission granted successfully!");},
        onFailure: function() { Mojo.Log.error("DB failed to grant permissions!");}
 });

reserveIds

Reserves a block of object ids.

Syntax

{
   "count" : int        
}

Parameters

Argument Required Type Description
count Yes int Number of Ids to reserve.

Returns

Response Success: ReserveIdsResponse
Failure: ErrResponse

Examples

luna-send

luna-send -n 1 -a com.palmdts.enyo.db-api luna://com.palm.db/reserveIds '{"count":5}'
{"returnValue":true,"ids":["++Hb_JCsc0lw_uMm","++Hb_JCsc1sBIOG2","++Hb_JCsc2NE0ff+","++Hb_JCsc2oYG2Et","++Hb_JCsc3FrSXwy"]}

Enyo

enyo.kind({
    name: "enyo.Canon.DbAPI",
    kind: enyo.VFlexBox,
    components: [
        {kind: "DbService", dbKind: "enyo.bffs:1", onFailure: "dbFailure", components: [
            {name: "getIDs", method: "reserveIds", onSuccess: "getIDsSuccess"}          
        ]},
        {kind: "PageHeader", content: "db8 Code Samples"},
        {kind: "HFlexBox", align: "center", components: [
            {kind: "Button", caption: "Get IDs", onclick: "getIDsClick"}
        ]}
    ],
    getIDsClick: function() {
        this.$.getIDs.call({count:5});
    },
    getIDsSuccess: function(inSender, inResponse) {
        this.log("reserveIds success, results=" + enyo.json.stringify(inResponse));
    },  
    // Log errors to the console for debugging
    dbFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    }
});

Mojo


// Get block of 5 IDs

this.controller.serviceRequest("palm://com.palm.db/", {
    method: "reserveIds",
    parameters: { "count": 5  },
    onSuccess: function(e) { 
       Mojo.Log.info("reserveIds success!");
       var ids = e.ids;
       for (i=0; i < count; i++)
           Mojo.Log.info("reserveIds ID #"+(i+1)+" ="+ids[i]);
    },
    onFailure: function(e) { Mojo.Log.info("reserveIds failure! Err = " + JSON.stringify(e));}
}); 

Success

reserveIds success, results=
{
   "returnValue":true,
   "ids":[
      "++Hb_I11uq4NU7r0",
      "++Hb_I11ur43Up_a",
      "++Hb_I11urN1L_Hb",
      "++Hb_I11urhaPlpJ",
      "++Hb_I11us00VoIx"
   ]
}

Unlike find, this call supports the '?' operator, which can be used for full-text searching. Also, ordering by any property is supported. However, this call is significantly slower and should only be used for full-text type-down search; never for retrieving results that are going to be scrolled in a list.

This call has some limitations:

Syntax

{
   "query" : Query,
   "watch" : boolean          
}

Parameters

Argument Required Type Description
query Yes Query Query for search.
watch No boolean Notify if change flag. Default is false.

Returns

Response Succcess: FindResponse or NotificationResponse
(watch == true)
Failure: ErrResponse

Examples

Enyo

enyo.kind({
    name: "enyo.Canon.DbAPI",
    kind: enyo.VFlexBox,
    components: [
        {kind: "DbService", dbKind: "enyo.bffs:1", onFailure: "dbFailure", components: [
            {name: "makeBffsDbKind", method: "putKind", onSuccess: "putDbKindSuccess"},
            {name: "putBffs", method: "put", onSuccess: "putBffsSuccess"},
            {name: "searchOp", method: "search", onSuccess: "searchSuccess"}           
        ]},
        {kind: "PageHeader", content: "db8 Code Samples"},
        {kind: "VFlexBox", align: "center", components: [
            {kind: "Button", caption: "Create bffs kind", onclick: "makeBffsDbKindClick"},
            {kind: "Button", caption: "Put bff objects", onclick: "putBffsClick"},
            {kind: "Button", caption: "Search", onclick: "searchClick"}
        ]}
    ],
    makeBffsDbKindClick: function() {
        var indexes = [{"name":"stateLastidx", props:[{"name": "state"}, {"name": "lastname"}]},
                       {"name":"lastidx", props:[{"name": "lastname"}]}
        ];
        this.$.makeBffsDbKind.call({owner: enyo.fetchAppId(), indexes:indexes}); // Create db8 kind
    },
    putDbKindSuccess: function() {
        this.log();
    },
    putBffsClick: function() {
         var  bff1 = { _kind: "enyo.bffs:1", lastname: "Syrup", firstname: "Mabel", 
                       nickname: "Sticky", state: "CA",
                       emails:[{"value":"msyrup@gmail.com", "type":"home"},
                               {"value": "mabel.syrup@palm.com", "type":"work"}]};
         var  bff2 = { _kind: "enyo.bffs:1", lastname: "Wheels", firstname: "Helen", 
                        nickname: "Psycho", state: "CA",
                        emails:[{"value":"hwheels@gmail.com", "type":"home"},
                                {"value": "helen.wheels@palm.com", "type":"work"}]};
         var  bff3 = { _kind: "enyo.bffs:1", lastname: "Manilla", firstname: "Sal", 
                       nickname: "Weasel", state: "CA",
                       emails:[{"value":"smanilla@gmail.com", "type":"home"},
                               {"value": "sal.manilla@palm.com", "type":"work"}]};
         var  bff4 = { _kind: "enyo.bffs:1", lastname: "Kroger", firstname: "Larry", 
                        nickname: "Pinto", state: "OH",
                        emails:[{"value":"lkroger@gmail.com", "type":"home"},
                                {"value": "larry.kroger@palm.com", "type":"work"}]};
        var objs = [bff1, bff2, bff3, bff4];
        this.$.putBffs.call({objects: objs});
    },
    putBffsSuccess: function(inSender, inResponse) {
        this.log("Put success, results=" + enyo.json.stringify(inResponse));
    },
    searchClick: function() {
        var squery = { "from" : "enyo.bffs:1",
                       "select": ["lastname", "firstname", "nickname"],
                       "where":[{"prop":"lastname","op":"?","val":"Man"}] };    
        this.$.searchOp.call({query:squery});
    },  
    searchSuccess: function(inSender, inResponse) {
        this.log("Search success, results=" + enyo.json.stringify(inResponse));
    },                              
    // Log errors to the console for debugging
    dbFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    }
});

Mojo

var fquery = {"from":"com.palm.searchtest:1",
              "orderBy":"foo",
              "where":[{"prop":"foo","op":"?","val":"fo","collate":"primary"}]};

this.controller.serviceRequest("palm://com.palm.db/", {
    method: "search",
    parameters: { "query": fquery},
    onSuccess: function(e) { Mojo.Log.info("Search success, results= " + JSON.stringify(e));},
    onFailure: function(e) { Mojo.Log.info("Search failure! Err = " + JSON.stringify(e));}
}); 

watch

Watch for updates to database that would change the results of a query.

Syntax

{
   "query" : Query        
}

Parameters

Argument Required Type Description
query Yes Query Query whose results should be watched.

Returns

Response Succcess: SuccessResponse or
NotificationResponse
Failure: ErrResponse

Example

Mojo

// Query on a revision set field. See Using Revision Sets for more information.

var fquery = {"from":"com.palm.sample:1", "where":[{"prop":"stateRev","op":">","val":4881}]};

this.controller.serviceRequest("palm://com.palm.db/", {
    method: "watch",
    parameters: { "query": fquery},
    onSuccess: function(e) { 
        if (!e.fired)
            Mojo.Log.info("RevSet watch initial response success, results= " + JSON.stringify(e));
        else
            Mojo.Log.info("RevSet watch results changed");
    },
    onFailure: function(e) { Mojo.Log.info("RevSet watch failure! Err = " + JSON.stringify(e));}
});