Building a Google Wave Gadget with GWT

June 7th, 2009 Alex Moffat Posted in GWT, Google Wave, Java | 11 Comments »

I’ve just written my first Google Wave Gadget using GWT with the Gadgets portion of the Google API Libraries for GWT. You can see it in action in the video below. I’ll describe how I got this to work and talk about the source code below the fold. The complete source for this example Wave Gadget can be downloaded.

The documentation for the Google Wave APIs includes a tutorial for developing a Wave Gadget. I pretty much followed this when building my gadget.

The first thing is to set things up to generate a correct gadget specification, as shown in the Getting Started portion of the tutorial. There are two things I had to deal with, the script tag in the Content element and the Require element in the ModulePrefs. I now have a better solution for the script tag and Require element. See Wave Gadgets with GWT – Build improvements. This also solves the isInWaveContainer issue I mention below.

First the script. This was easy. I used a script tag in my GWT module file to include wave.js file instead of using a script element inside the Content element. In the HelloWorld.gwt.xml I added.

<script src="http://wave-api.appspot.com/public/wave.js"/>

Next the Requires element. Unfortunately the GWT Gadget API libraries doesn’t provide a way to do this out of the box. However, it’s easy to add support for one. When you write a Gadget with GWT you declare which features you require by having your entry point class implement various interfaces, such as NeedsAds, that are annotated with GadgetFeature.FeatureName. At compile time these produce the correct Requires elements. I created a NeedsRpc interface and added the appropriate annotation.

@GadgetFeature.FeatureName(value = "rpc")
public interface NeedsRpc {

The entry point class HelloWorld extends Gadget and implements NeedsRpc which gets the correct <Require feature=”rpc”/> element in the ModulePrefs.

@Gadget.ModulePrefs(title = "Hello Wave World")
public class HelloWorld extends Gadget<UserPreferences> implements NeedsRpc {

There are three interesting pieces to the implementation of HelloWorld

• Getting the value of state properties
• Changing the values of state properties
• Being notified when state changes

Each requires some JSNI coding.

For getting and changing state property values I created a WaveState class with a number of static methods. Getting values is simple

public static native String get(String key) /*-{
    return $wnd.wave.getState().get(key);
}-*/;

Changing values is more complex. You submit a json map with the new values for the properties you want to change. I implements a simple system that suffices for the cases I’m using here. There’s probably a neater way to construct the json object.

public static void submitDelta(Map<String, String> newValues) {
    JavaScriptObject json = null;
    for (Map.Entry<String, String> entry : newValues.entrySet()) {
        json = addValue(json, entry.getKey(), entry.getValue());
    }
    submitDelta(json);
}

private static native JavaScriptObject addValue(JavaScriptObject map, String key, String value) /*-{
    if (!map) {
        map = {};
    }
    map[key] = value;
    return map;
}-*/;

private static native void submitDelta(JavaScriptObject json) /*-{
    $wnd.wave.getState().submitDelta(json);
}-*/;

This method of changing state is similar to the way Blueprint works behind the scenes, though we have access to a more granular set of operations, for instance changing the position of an item in a list. The API available to gadget writers does not expose all of the operations supported by the underlying Wave protocol.

Receiving notification of changes to state is done by registering a callback function. However, it’s up to the Gadget’s code to work out what has actually changed, you don’t get notification about which properties have been modified. For more complex state this could become an interesting challenge.

In my registration method I found that isInWaveContainer() was always returning false for me so I removed the check. The code continues to work but it may be that I’m doing something wrong here.

private native void registerStateChangeCallback() /*-{
    var wave = $wnd.wave;
//    if (wave && wave.isInWaveContainer()) { isInWaveContainer always returns false?
    if (wave) {
         wave.setStateCallback(@com.lombardi.waves.helloworld.client.HelloWorld::stateUpdated());
    }
}-*/;

If you want to take a closer look the complete source code for the example Google Wave Gadget can be downloaded here. Overall the programming model provided by the API for interacting with the Wave state seems to be a higher level abstraction over the Wave protocol. The Blueprint data repository provides similar access to Lombardi Blueprint developers for handling versioned data, which we presented at Google I/O in 2008.