How to write a URC in Javascript or Flash

Table of Contents:

1. Introduction

This tutorial is designed for developers interested in writing a Universal Remote Console (URC) in a non-Java environment based on the ANSI standards. The example code in this tutorial is a part of the Flash URC. The Flash URC runs as Macromedia Flash code in a Web browser window, and connects to the URC SDK running as an applet in the same window. JavaScript is used as "glue" code between Flash and the Java applet.

2. FacadeForJS

The FacadeForJS is a class in the facade package of the URC SDK. It contains all the methods needed to communicate with a client from javascript. The Facade/SDK is defined as an applet within the browser window. It creates the GenericClient object and implements the IClientListener that communicates with the SDK. The JSObject is the Java wrapper class located in the netscape.javascript package. Its purpose is to be able to call javascript methods from within Java. The SDK uses the JSObject to accomplish javascript calls from within the SDK. The JSObject can be found in the plugin.jar file in the JRE_HOME/lib folder.

URL codeLocation = this.getCodeBase();
jsObj = (JSObject) JSObject.getWindow(this);
client = new GenericClient(codeLocation);
client.addListener(this);

The JSObject is then called to pass data from the SDK to the non-java client. For example, the updateValue method calls the updateValue method that is defined in the Javascript code and passes the new value to the client.

public static void updateValue(String sessionID, String elementID, String
value) {
  try{
    jsObj.call( "updateValue", new String[]{sessionID, elementID, value});
  }catch(Exception e){
    logger.warning("Could not call JavaScript: updateValue");
  }
}

The facade also implements an internal socket listener to listen to the individual socket elements. A sample representation of how communication takes place in the Flash URC is shown below,

Flash Client <---->Javascript glue code<------> FacadeForJSApplet <-----> URCSDK

3. JavaScript glue code.

This code acts as the bridge between the facade and the client. The client could be a JavaScript client or capable of accepting javascript calls. The glue code is a mirror of all the calls present in the SocketFacadeForJS class. The JavaScript code is available.

4. Adding the SDK as an applet.

The way to get the SDK to communicate with JavaScript in the web environment is by adding the SDK as an applet within the same window as the Flash/JavaScript client resides. This is done as follows,

<APPLET CODEBASE="."
CODE="edu.wisc.trace.urcsdk.client.facade.FacadeForJs" 
ARCHIVE="xercesImpl.jar, urcsdk.jar, clink.jar" 
NAME="urcsdk" bgcolor="black" MAYSCRIPT>
</APPLET>

The MAYSCRIPT parameter is important. If MAYSCRIPT is specified as false, or if MAYSCRIPT is absent, JSObject is disabled. For more information about the MAYSCRIPT attribute in the EMBED/OBJECT tag, please read Java Plug-in 1.3 HTML Specification for more details.

5. Flash and JavaScript

The Flash client communicates with the Javascript code using the ExternalInterface package defined in the ActionScript API. The following code is a part of the targetDiscovered method in the ActionScript code for the FlashURC. It uses the ExternalInterfaces call method to get the socket names for the target with id targetId and then calls the openSessionRequest method for the socket names for the particular target.

gotoAndStop("start");
var tId = targetId;
var socketNames = ExternalInterface.call("getSocketNamesForTarget",targetId, "*");
var sNames:String = new String(socketNames);
var sNamesArr:Array = sNames.split(",");
var sessionId = ExternalInterface.call("openSessionRequest",targetId,sNamesArr[0]);

6. Sample Flow between SDK and Javascript code.

This section describes the flow between the non java client and the SDK. The first is the setElementStateRequest, which is triggered when the client wants to change the value of an element on the target. The following is the code in the javascript glue code calling the Facades setElementStateRequest method. The sequence diagram is split into two halves, the left being the non-java client and the right being the SDK.

// This method is in the javascript glue code between the flash actionscript and the 
// java SDK. This method is called by the actionscript. 
function setElementStateRequest(sessionId, elementId, value){
  window.document.urcsdk.setElementStateRequest(sessionId, elementId,value);

Figure1:Sequence diagram showing the flow from FlashURC to the SDK. Textual diagram description available.

The next sequence described is the updateValue which is triggered when the target modifies an element value and sends the updates from the target to the client. The following is the code in the FacadeForJs calling the updateValue method in the javascript glue code. The sequence diagram is split into two halves, the left being the SDK and the right being the non-java client.

try{
  jsObj.call("updateValue", new String[]{sessionID, elementID, value});
}catch(Exception e){  
  logger.warning("Could not call JavaScript: updateValue");
}

Figure2:Sequence diagram showing the flow from the SDK to the FlashURC. Textual diagram description available.

Last updated: Hemanth Vijayan, 10-06-2006