Do you SAMCRO your Google App Engine Apps?

A couple of weeks ago, we were involved in a discussion between users and technicians about transaction integrity for  a hypothetical  system. The preferred approach of the  technicians was the optimistic locking: when a user edits the data and saves the changes while  another user contemporarily changes the same data, an error is returned. Users did not take this kindly, because the changes are lost and they need to repeat the operation. We started to think out of the box in order to get a different solution,  and borrowing the SAMCRO acronym from our preferred TV series, we created a new meaning: Simultaneous Asynchronous Multi Client Read Operation. Like the spirit of the TV series, where your mother says don't do something and you do it anyway, the result is a good practical application of the Google App Engine Channel API. Do not try it on your production environment. Before getting started, buy your favorite burrito and call your best friend asking five minutes of their time to participate in the exercise below. Next, both of you connect to http://gae-samcro.appspot.com with Firefox/Crome/Safari web browser (IE may not work).The screenshot below should be displayed.

A brief explanation about how it works:  by clicking on the rows in the list (left window) the detail window (on the right), shows the detail data of the selected row. To update a record, change the values in the edit box and push the  'Update' button.  

Now select a row and ask your best friend to select the same row. Change some of the values in the detail window (for example typing in the title field) and save the data by  clicking the Update button. If you are lucky, you should get the screenshot below; if not try reloading the page, as sometimes it takes a while, like putting a car in first gear.

The Channel API allows the application to send messages to JavaScript clients in real time without the use of polling. This is useful when you need to notify users about new information immediately. In this sample application, if you are editing a record and another user updates the same record, you will receive a notification message highlighted in yellow at the top of the detail window (see screenshot above), before the record is reloaded.  The list window also reflects the updates in bold text, highlighting the changed row for one second. More complex scenarios can be implemented without changing the architecture. Our users loved this feature. 


In order to add the Channel API in your GAE applications you need to: 

• Include the the Channel API script in your page
• Initialize the channel 
• Send and Receive Messages  

Include the the Channel API
The Google App Engine Channel API has been released, starting from the SDK 1.4.0. 
Include the following in your page: 

1. <script language="JavaScript" type="text/javascript" src="/_ah/channel/jsapi"></script>

Initialize the channel
A mandatory operation consists of initializing the channel. On client side you need to send a request to the server to initialize the channel. 

1. /* Initialize the channel */
2. function initializeChannel() {
3.   dhtmlxAjax.get("/controller/initialize" , function(loader) {
4.      if (loader.xmlDoc.responseText != null) {
5.         openChannel( loader.xmlDoc.responseText  );
6.      }
7.   });
8. }
10. function openChannel(token) {
11.   var channel = new goog.appengine.Channel(token);
12.   var handler = {
13.     'onopen': function() {},
14.     'onmessage': onMessage,
15.     'onerror': function() {},
16.     'onclose': function() {}
17.   };
18.   var socket = channel.open(handler);
19.   socket.onopen = function() {};
20.   socket.onmessage = onMessage;
21. }

The server is responsible for:

• Creating a unique channel for each client
• Creating a unique token to each client

/controller/initialize

1. ChannelService channelService = ChannelServiceFactory.getChannelService();
2. String clientId = request.getSession().getId();
3. String token = channelService.createChannel( clientId );
4. ClientDAO dao = new ClientDAO();
5. Client client = dao.store( new Client(clientId) );
6. write(response, "text/plain", token );

In this sample application, the session ID is used as client ID, and it is stored in the datastore.

Send and Receive Messages
On client side, the notifyToChannel is used to send messages to the client. In this case an Ajax GET request is sent to the server. 

1. function notifyToChannel(message) {
2.   dhtmlxAjax.get("/controller/notify?" + message  , function(loader) {});
3. }

The onMessage function specified during the initialization is invoked when a message is received from the client, in  this case a JSON message.

1. function onMessage(message) {
2.   var msg = JSON.parse(message.data);
     ...
3. }

On server side the message is dispatched to clients via their channels.

/controller/notify

1. ClientDAO dao = new ClientDAO();
2. ChannelService channelService = ChannelServiceFactory.getChannelService();
3. List<Client> clients = dao.retrieveClients();
4. for (Client client : clients) {
5.   if (!client.getClientId().equalsIgnoreCase(request.getSession().getId())) {
6.      channelService.sendMessage(new ChannelMessage(client.getClientId(),
7.      getMessageString(id)));
8.   }
9. }
11. public String getMessageString(String id) {
12.      BookDAO dao = new BookDAO();
13.      Book book = dao.retrieveBook(id);
14.      Map<String, String> msg = new HashMap<String, String>();
15.      msg.put("id", book.getId().toString());
16.      ...        
17.      JSONObject message = new JSONObject(msg);
18.      return message.toString();
19. }

In order to be notified when a client connects to or disconnects from a channel, you must enable this feature in the appengine-web.xml:

1. <inbound-services>
2.     <service>channel_presence</service>
3. </inbound-services>

When the channel_presence is enabled, the application receives a POST  /_ah/channel/connected/ request when a client has connected to the channel, and receive  a POST /_ah/channel/disconnected/ when the client has disconnected.
This sample application implements handlers to these paths in order to keep track which clients are currently connected.


/_ah/channel/connected/

1. ChannelService channelService = ChannelServiceFactory.getChannelService();
2. ChannelPresence presence = channelService.parsePresence(request);

/_ah/channel/disconnected/

1. ChannelService channelService = ChannelServiceFactory.getChannelService();
2. ChannelPresence presence = channelService.parsePresence(request);
3. ClientDAO dao = new ClientDAO();
4. dao.deleteClient( presence.clientId() );

The sample application has been developed in Java with the support of the DHTMLX Java Tag Library 1.5 the DHTMLX Java Tag Designer  and DHTMLX 3.0. 


Have fun.