With this method, we will use JSON-RPC to send RPC requests to a server. The JSON-RPC calls are integrated with our REST architecture by using the URL of the target resource/object as the URL for the JSON-RPC request. Let’s send a request to send an email to one of our friends. A targeted JSON-RPC call might look like:

POST /Friend/dylan

{"method": "sendEmail",
 "params": ["Hi there"],
 "id":"call0"
}

One of the advantages of this approach is that it allows for a very object-oriented approach to RPC. JSON-RPC by itself only provides a flat procedural calling mechanism, but by targeting the calls to resource-associated URLs, the RPCs have a target object and can trigger a true object-oriented method call.

Inheritance in JsonRestStore

Now, let’s look at how we can set up a JsonRestStore so we can easily make RPC requests through methods. First, the JsonRestStore allows you to add functions on a prototype object that will be inherited by all items in the store. The prototype object is defined by the schema object that can be passed to the JsonRestStore on construction. For example, we could define a function that would calculate the full name of a person:

var friendSchema = {
	prototype: {
		getFullName: function(){
			return this.firstName + ' ' + this.lastName;
		}
	}
}
var friendStore = new dojox.data.JsonRestStore(
	{target:"/Friend/", schema: friendSchema});

And now this function will be inherited by the items in our friendStore:

var newFriend = friendStore.newItem({firstName: "Abraham", lastName: "Lincoln"});
newFriend.getFullName() -> "Abraham Lincoln"

This functionality is covered in more detail in our post about the effective use of JsonRestStore.

Now, we will create a function that can add a function that triggers the JSON-RPC request when called (understanding the internals of this function is not critical, you may want to simply copy it):

function addRpcFunction(schema, name){
	schema.prototype[name] = function(){
		// execute a JSON-RPC call
		var deferred = dojo.rawXhrPost({
			url: store.target + store.getIdentity(this),
			// the JSON-RPC call
			postData: dojo.toJson({
				method: name,
				id: callId++,
				params: dojo._toArray(arguments)
			}),
			handleAs: "json"
		});
		deferred.addCallback(function(response){
			// handle the response
			return response.error ?
				new Error(response.error) :
				response.result;
		});
		return deferred;
	};

}
var callId = 0;

Now we can easily add our sendEmail function to the prototype of the schema, as well as any other methods we want:

addRpcFunction(friendSchema, "sendEmail");
addRpcFunction(friendSchema, "poke");

Triggering an RPC is now as simple as a method call on an item from the store:

friendStore.fetchItemByIdentity({
	identity: "dylan",
	onItem: function(item){
		item.sendEmail("Hi there");
	}
});

And this will trigger the HTTP request containing the JSON-RPC call we described at the beginning of the article:

POST /Friend/dylan

{"method": "sendEmail",
 "params": ["Hi there"],
 "id":"call0"
}

The server can then easily find the associated resource and call the server-side sendEmail method with the resource as the target. The server could then respond with:

POST /Friend/dylan

{"result": true,
 "error": null,
 "id":"call0"
}

The client method call will return a Deferred object. This object can be used to get the return value from the RPC call when it finishes (it will execute asynchronously):

item.sendEmail("Hi there").addCallback(function(result){
	// with the server response above, the result value will be true
});

All of this is done with an intuitive combination of REST and RPC, using the widely adopted JSON-RPC format. Persevere is one server that supports this approach, allowing JavaScript functions on the server to be executed via JSON-RPC requests with persisted objects as the targets. However, it is straightforward to implement this mechanism yourself, as the JSON-RPC specification is very simple.

Summary

Adhering to a uniform interface as prescribed by REST and defined by the HTTP specification will certainly afford maximum interoperability. However, if your application needs to use specific functions for maximum efficiency, or for operations that don’t fit well with REST (sending an email is a good example, since it is awkward to model as a state change), JSON-RPC is a great tool for sending specific RPC using a format with a high degree of adoption. Using targeted JSON-RPC allows RPCs to build on the REST architecture and work in conjunction with it. This combination provides an object-oriented technique for remote calls. Many of the benefits of REST can realized, while the freedom to perform more customized operations is still available.

SitePen offers beginner, intermediate, and advanced Dojo Toolkit workshops to make your development team as skilled and efficient as possible when creating dynamic, responsive web applications. Sign up today!

Our demonstration of OfflineRest is a simple database of hiking trails. Here in Salt Lake City, we have a vast array of trails close to my house. However, despite their proximity to the city, most trails still lack internet access. Our “Database for the Outdoors” can be used on the trail, offline, with the ability to view, add, update, and delete trails. Currently it can run on Firefox 3, but as other browsers with HTML 5 offline capabilities are released, they should work as well. This application is simply built by interacting with the JsonRestStore module, using the standard Dojo Data API. Dojo automatically stores all data changes in local storage, and if or when connectivity becomes available, the data changes are persisted to the server using the Rest service. By building the application on top of the Dojo Data API, the OfflineRest module allows us to easily add offline capabilities. Dojo then handles synchronization and offline access to data, which is usually the complex part of adding offline capabilities to an application.

To enable offline support with OfflineRest, load the OfflineRest module prior to loading the data store:

dojo.require("dojox.rpc.OfflineRest");
dojo.require("dojox.data.JsonRestStore");

With OfflineRest loaded, you can now add stores to the OfflineRest module for offline support. First, initialize your data store, and then call the addStore method on OfflineRest:

trailStore = new dojox.data.JsonRestStore({url:"/Trail"});
dojox.rpc.OfflineRest.addStore(trailStore,"");

Now the trailStore will have offline support. Any data modifications that are made through the trailStore will be persisted in local storage and synchronized to the server when connectivity is available. Data modifications can be done with the standard Dojo Data API, for example:

var item = trailStore.newItem();
trailStore.setValue(item,"foo","bar");

OfflineRest handles the synchronization of sending all data modifications to the server. However, the current version of OfflineRest does not re-query the server for any data that it has cached locally. Consequently, it may be desirable to force a download of data from the server based on data that may have changed on the server while offline. Such an action can be performed and triggered by connecting to the downloadChanges() method on OfflineRest:

dojo.connect(dojox.rpc.OfflineRest, "downloadChanges", function(){
	.. download changes or refresh the page ..
});

Without defining the offline caching of the resources, this application will be available offline as long as the resources in the application are still in the browser cache, but this is not guaranteed. In order to ensure that your application is always available offline, the new HTML 5 offline cache manifest can be used to ensure that all the resources will be available so your application can always load even when offline and the application hasn’t been accessed for a while. Firefox 3 has implemented support for offline resources, and has detailed instructions on how to build a manifest to ensure your resources are included. Our trails application includes a manifest to leverage this support when available:

CACHE MANIFEST
# v1

http://localhost/example/trails.html


http://localhost/jsclient/dojo/dojo.js


http://localhost/jsclient/dojox/grid/resources/Grid.css


http://localhost/jsclient/dojo/resources/dojo.css


http://localhost/jsclient/dojo/resources/dojo.css


http://localhost/dojox/data/PersevereStore.js


http://localhost/dojox/grid/DataGrid.js


http://localhost/dojox/rpc/OfflineRest.js

And we reference the manifest from our HTML page:

This offline demo application was built with Persevere, and this demo is included with the Persevere download if you want to try it out yourself.

With OfflineRest, synchronization is encapsulated and handled by Dojo with data modifications persisted locally or remotely as connectivity allows. For developers that utilize JsonRestStore, offline support can be a relatively easy addition to your application. OfflineRest can also utilize the offline features in current and coming browsers like Firefox 3.

SitePen offers beginner, intermediate, and advanced Dojo Toolkit workshops to make your development team as skilled and efficient as possible when creating dynamic, responsive web applications. Sign up today!