Change Notification

You can be notified only when a subset of an object's properties is updated using revision sets. For example, a sync engine might want to be notified only when a contact's phone number changes. A revision set creates a property that is only updated when one of the set's properties is updated.

If the revision set with the name phoneRev on the property phoneNumber creates a property phoneRev with an integer value that is set to the current value of _rev whenever the phoneNumber property is updated. This allows an app to create a watch using a query of the form "where phoneRev > X" to be notified when a phone number is updated.

Revision sets are specified at kind creation with the putKind() method. The following creates a revision set for the state property:

//**
//** Note here that the revision set field ("stateRev") is added
//** to the indexes so that we can query on it later.
//**
var indexes = [
    {
        "name":"state",
        "props":[
            {"name":"state"}
        ]
    }, 
    {
        "name":"stateRev",
        "props":[
            {"name":"stateRev"}
        ]
    }
];
var revSets = [
    {
        "name":"stateRev",
        "props":[
            {"name":"state"}
        ]
    }
];
 
var request = new enyo.ServiceRequest();
var parameter = {
    "id":"com.yourdomain.sample:1",
    "owner":"com.yourdomain.dbtest",
    "indexes": indexes,
    "revSets": revSets
}
request.service = "luna://com.palm.db/putKind";
request.go(parameter);

Once a kind is created, we will put a contact data using the put() method.

var contact = {
    "_kind":"com.yourdomain.sample:1",
    "name":"Mabel Syrup",
    "state":"CA"
};
var objs = [contact];
var parameter = {"objects": objs };
 
var request = new enyo.ServiceRequest();
request.service = "luna://com.palm.db/put"; // putting data into DB
request.response(this, "putDataIntoDatabaseResponse");
request.go(parameter);

The following handler is called when the "putting" is complete.

putDataIntoDatabaseResponse: function(inSender, inResponse) {
    if (inResponse.returnValue === true) {
        enyo.log("put success! results=" + JSON.stringify(inResponse.results));
    } else {
        enyo.log("put failure!");
    }
}

You will see the following output in the log.

After you "put" a record, we will use get() to get the revision set number.

var id = "++HEIviIqT+9MYkj";
var ids = [id1];
var parameter = {"ids": ids};
var request = new enyo.ServiceRequest();
request.service = "luna://com.palm.db/get";
request.go(parameter);

As the result, you will see the following.

Using the revision set number, you can be notified when the revision number gets modified. Note that if you want to do a query on a revision set, then there has to be an index for it (see the putKind example above). The following is an example of calling the watch() method. (the fired flag is true in the results)

var fquery = {
    "from":"com.yourdomain.sample:1",
    "where":[
        {
            "prop":"stateRev",
            "op":">",
            "val":4881
        }
    ]
};
 
var parameter = {"query": fquery};
var request = new enyo.ServiceRequest();
request.service = "luna://com.palm.db/watch"; // watch
request.go(parameter);

If the state field is subsequently updated, the watch fires. For example, the following merge() does this:

var mprops = { "state":"MA"};
var mquery = { 
    "from":"com.yourdomain.sample:1",
    "where":[
        {"prop":"state","op":"%","val":"C"}
    ] 
};
var parameter = { "query": mquery, "props": mprops };
var request = new enyo.ServiceRequest();
request.service = "luna://com.palm.db/merge";
request.go(parameter);