Views From The Hill

While experimenting with mobile development on the Blackberry Webworks Platform I found that it was extremely difficult to get any debugging information out of the device simulator to help debug javascript errors.

The Webworks Eclipsed-based IDE does provide limited debugging support; however, I found the OS5 device support for javascript to be extremely lacking (Especially while using the Dojo library) and Webworks is currently unable to debug OS6 devices.

At a bare minimum I wanted my familiar firebug console.* calls to show up somewhere I would be able to see them. Although this is far short of a full remote debugging solution (such as the Firebug Crossfire Project), it would at least allow me to see what is going on under the hood.

Implementation Overview:

1. A Small javascript file is included on the mobile page. This file adds additional console methods and, optionally replaces the default console.* debugging methods
2. A CometD provides communication between the mobile page and the page that firebug is listening on
3. A special listening page is setup where the debugging events coming over the cometd server are passed onto firebug

Prerequisites

For my development environment I am using Eclipse 3.6 with the Maven tooling installed. Maven is used so the CometD API can be easily utilized. For more information about building CometD applications with Maven please see the CometD Primer. Maven is also nice as it will download the required dependencies (such as the Jetty Server).

Getting & Compiling the Source

1. Please clone my GitHub Repository to obtain the source code. This can be found at https://github.com/51systems/Remote-Console
2. Import the project into eclipse
   1. When you are cloning the repo it is most convenient to clone it into your eclipse workspace directory, this makes importing into eclipse easiest
   2. In Eclipse Choose File -> Import
   3. Scroll down and roll open the Maven import source
   4. Choose Existing Maven Projects
   5. Locate the cloned repository & Select the pom.xml file for import
3. Maven will now download dependencies and attempt to build your project. This may take time so be patient

At this point, you should have a built remote-console project in your Eclipse workspace. You will find that there are two separate source directories: One contains the java source and the other contains HTML & Javascript.

The java source folder is uneciting: it contains the bare-minimum vanilla implementation necessary for the CometD server to pass messages between the mobile device and the firebug page.

The HTML / Javascript source folder contains some example pages + the remote-console.js file which, together, provide the remote-debugging functionality.

Running the Server

To run the Jetty server for the first time:

1. Create a new Maven Build Run-Configuration
   1. Can be done by right clicking on the remote-console project and choosing Run As -> Run Configurations or by rolling out the run icon
      
   2. Ensure the base directory is set to the correct workspace directory. Mine is ${workspace_loc:/remote-console}
   3. For the Goals text box enter “jetty:run” this will start the jetty server
2. Start the Jetty server by clicking Run in the configuration dialog
3. You should see console output in the Eclipse window. Inspect this output to catch potential problems
4. Visit http://localhost:8080/remote-console/ to view the remote-console application.

Remote Debugging

When you visit the remote-console application link you will be presented with the remote console connection page. This page allows you to connect to a remote console on a specific channel and have the debug messages appear in a firebug window.

There are two types of demo pages. The default one uses dojox.json.ref to serialize objects. This allows for the serialization of javascript objects that have circular references. The second demo page serializes objects using the default json serialization – be careful with those circular references with this one.

To Use remote debugging for the first time:

1. Start the firebug listener:
   1. Visit the Remote console connection page with firefox
   2. Open The firebug console
   3. Click the connect button to connect to the default local cometd server
   4. You should start seeing the long-polling entries appearing in the firebug console
2. Visit one of the demo pages, either in a new firefox window, or using another browser
   1. Use the console.log textbox and button to send a console.log message to your listening firebug console.
   2. You should see the logged textbox contents appear almost immediately in the firebug console log
3. Next steps:
   1. On one of the demo pages, try a more complex debug expression, such as

      console.log("test", {foo: "bar"});

   2. You should see the message and object quickly appear in your listening firebug console.
      If you are using the dojox.json serialization you may see additional fields on the object when it is displayed in the firebug console.

Adding remote debugging to your own pages is as easy as adding the dojo library and the remote-console script tag to the page you wish to debug.

<script src="http://ajax.googleapis.com/ajax/libs/dojo/1.6/dojo/dojo.xd.js" type="text/javascript"></script>
<script src="remote-console.js" data-server="http://127.0.0.1:8080/remote-console/cometd" data-channel="demo" data-json-ref="true"></script>

Ensure that the src path is set correctly to point to the remote-console.js on the jetty server. Likewise the data-server attribute should point to the server and path running the jetty cometd implementation. Pay attention to the loopback device IP and be sure to change it if you are planning on debugging on another device.

There are several parameters that you are able to pass to the remote-console.js script via HTML attributes. Please view the ReadMe in the Git Repo or the source code for a complete list.