Jetpack SMODL Tutorial

Your first SMODL enabled Jetpack.

This tutorial shows how to set interaction between Jetpack and a SMODL service. The target audience of the tutorial is Jetpack developers (rocketeers) who want to create jetpacks communicating to a server via a SMODL service. So the tutorial assumes that readers are familiar with two mentioned technologies: Jetpack and SMODL.

In this tutorial we will create a jetpack test talking to a simple SMODL service deployed by us for this tutorial. This service just echos what comes as an input. Why not a jetpack itself? Because we want to show that with just few lines of code you can set the interaction with a service but real jetpack would require more code.

What makes interaction with a SMODL service so simple? It is the Jetpack generator that creates a jetpack module from a SMODL file. This jetpack module is able to create a proxy object that implements a SMODL service interface. The proxy object talks to the service and all you need as a developer is just to call the corresponding methods of the interface.

The Jetpack generator comes in two incarnations: 1) as a part of the SMODL Development Suit and 2) as an online tool

To run the example described in this tutorial you will need Jetpack SDK and xulrunner installed (it can be used even if you have older FF like 3.6). If you use Eclipse you can install Smodl Development Suite (just make sure that you use version 1.3 or above). If you have not used Eclipse yet then you can use the on-line version.

Let's start with jetpack. Under the packages directory of your Jetpack SDK installation you need to create a directory that will contain jetpack. In its turn this jetpack directory should have two subdirectories: 1) lib, here we will place the generated module; 2) tests, here we will place test code. Also the jetpack directory should contains the package.json file with JSON like this: { "description": "This is an echo test package", "author": "Me (http://me.org)" }

Now let's generate module to communicate to the service. First we need SMODL file that we can use a an input for the jetpack generator. Click on the following URL If you check the page source it will contain the following xml.

<?xml version="1.0" encoding="UTF-8"?>

<service name="EchoService" xmlns="http://smodl.org/v1">

  <method name="echo">
    <arg name="ping" type="string"/>
    <result type="string"/>

  </method>
</service>

The xml is easy to read and understand that it describes a service containing one method called echo. We are going to call this method in the test. Now if you do not use Eclipse copy the xml and paste it on the Jetpack generator page. Click the ">>" button and copy Javascript code from the right window.

Now create a new file called service.js in the lib directory of the jetpack and paste the generated Javascript code. Save the file and the jetpack module is ready.

If you want to use Eclipse and Smodl Development Suite you should create a new file (for example echo.smodl, possibly in a new project) and use the SMODL xml as its content. Now in eclipse select and right click on your smodl file. Then select Properties and then select SMODL on the left panel.

Click the Browse button and using a file dialog navigate to the lib directory of the jetpack and enter file name service.js. Once you click the OK button the file is generated. If later you change the smodl file: add a new method, for example, the jetpack module will be regenerated to reflect the changes in the smodl file.

Now we are ready to create a simple test calling the echo method. To do it create a file called test-smodl.js in the test directory of your jetpack.

var sm = require("service");

exports.checkEcho = function(test) {

  var proxy = sm.service.createProxy("http://examples.smodl.org/echo-service/service/JSON", 
				function(error) { console.log("error handler is called"); console.log(error.faultCode); test.done(); });

    proxy.echo("pong", function(result) { console.log(result); test.assertEqual(result, "pong");  console.log("callback completed"); test.done(); });

    test.waitUntilDone(10000);

}

The test method called checkEcho consists of 3 lines of code. The first line created the proxy object using the service.createProxy methods that require two arguments:

url to call service
method to process possible errors (error handler)

The second line calls the echo method of the proxy object. Two parameters are provided: 1) string to be echoed; 2) callback function to be called when the service returns a response. The last line is required because the call of the echo method is asynchronious. The test.done() call in both the error handler and the callback function is required to normally complete the test.

Now we are ready to test it. To run the test use the following command: cfx -a xulrunner test. If everything is fine the test ouput will contain these lines like this:

info: ping
.info: callback completed

1 of 1 tests passed.
OK

Once test works you can use the same code fragments in your jetpack modules to call a SMODL service you create or anyone creates for you. If you need to create and deploy a SMODL service by yourself see our other tutorials how to do it using Eclipse and SMODL Development Suite.