Elegant code splitting with GWT

16Feb10

Update February 17, 2010: I forgot to mention that if you need FIFO guarantees today and don’t mind losing some of the conciseness, Jarrod Carlson has a nice solution posted here. I plan on stealing his way of doing FIFO.

---

Since leaving Microsoft in September, I’ve been working almost exclusively with Google Web Toolkit (GWT). Now that I have spent some time with it, I think it’s one of the most exciting advances in web development in years.

I came up with a (possibly) novel way to abstract the code splitting facilities in GWT 2.0 and will try to share it as best I can in this post. (Thanks to my boss, JJ Allaire, for letting me share this code!)

Warning: This post assumes the reader is very familiar with GWT and code splitting, and the ideal reader will have already tried and failed to find a nice way to reuse code split logic. Seriously though, you’ve been warned!

The Problem: Reusing Code Splitting Logic

GWT 2.0 provides a mechanism for splitting your codebase so that some of your code and resources can be loaded on-demand rather than at page load.

The official GWT site recommends the Async Provider pattern as a way to split up your codebase. This is a great start, but you need an excessive amount of boilerplate for each module. Plus, callers now have to use a pretty tortured anonymous class based syntax to get at the API.

Because GWT effectively introduces one split point for each time GWT.runAsync appears in the program source, it’s not obvious how to get around cutting-and-pasting all of this boilerplate.

The Solution: Deferred Binding

Fortunately, GWT gives us the tools we need to get out of this mess. We’ll build on top of the same pattern, but use deferred binding (via my library) to generate the boilerplate at build time.

Terms of Use

I wrote this on company time but thanks to my benevolent employer, the source code and binaries in the library asyncshim.jar are public domain. But use at your own risk.

Prequisites

This library depends on Google Gin. You don’t have to actually use Gin within your project for it to work, but it won’t compile unless gin.jar is in the classpath. Really, though, if your GWT project is big enough to need code splitting, it is big enough to need Gin.

Installing the Library

Download asyncshim.jar and add it to your project’s classpath. Then add the following line to your project’s .gwt.xml file:

<inherits name="com.joecheng.asyncshim.AsyncShim" />

Getting Started

Now that you’ve got the library loaded and inherited, it’s time to remove some boilerplate. Here’s the example module from the Async Provider documentation:

public class Module {
  // public APIs
  public void doSomething() { /* ... */ }
  public void somethingElse() { /*  ... */ }

  // the module instance; instantiate it behind a runAsync
  private static Module instance = null;

  // A callback for using the module instance once it's loaded
  public interface ModuleClient {
    void onSuccess(Module instance);
    vaid onUnavailable();
  }

  /**
   *  Access the module's instance.  The callback
   *  runs asynchronously, once the necessary
   *  code has downloaded.
   */
  public static void createAsync(final ModuleClient client) {
    GWT.runAsync(new RunAsyncCallback() {
      public void onFailure(Throwable err) {
        client.onUnavailable();
      }

      public void onSuccess() {
        if (instance == null) {
          instance = new Module();
        }
        client.onSuccess(instance);
      }
    });
  }
}

We’ll start by deleting all the boilerplate, leaving behind only the public APIs:

public class Module {
  // public APIs
  public void doSomething() { /* ... */ }
  public void somethingElse() { /*  ... */ }
}

It’s worth nothing that “Module” can be almost any kind of class—it doesn’t need to extend or implement anything in particular. It can be a widget, a class from the JRE or GWT framework, etc. It can have lots of methods (even public ones) that you don’t want to be part of the public API. And in case it wasn’t obvious, it definitely doesn’t need to be called “Module”. All this is to say, if you haven’t been following the Async Provider pattern, hopefully there is still a class that’s already in your codebase that you can point to and say, “Yes, this is the perfect module thing for split point A”.

Next, introduce a new abstract class (it can be inner static if you want) that subclasses AsyncShim and specializes it to Module. Add abstract versions of the public API methods. And finally, create a singleton instance of it, using GWT.create.

public abstract class ModuleShim extends AsyncShim<Module> {
  public abstract void doSomething();
  public abstract void somethingElse();
}

Pretty simple. Now all your callers just need to get their hands on ModuleShim instead, and once they do, they can simply call the public API methods on it instead of directly on a Module instance. The first time a public API method is called, it will cause the split point code to load (if it’s not loaded already), an instance of Module to be instantiated, and the corresponding method on the new Module instance will be called. (On subsequent API method calls, the existing instance of Module will be reused.)

To create/initialize instances of ModuleShim, you have two options.

If the Module is Gin-injectable then just use Gin to inject ModuleShim. Done.

Otherwise, use GWT.create(ModuleShim.class) to get an instance of ModuleShim, then call the ModuleShim.initialize(Provider<Module>) method. The Provider<Module> can be as simple as an anonymous class that does “new Module()” (although if that’s all you were going to do, you could’ve just used Gin). You must ensure that initialize is called before ModuleShim is first used—otherwise the public API will fail, as no instance of Module will be available.

Slightly More Realistic Example

Here’s the Module-like class, the one we want to use as the locus of our split point. It’s a dialog box. There’s lots of code, but we’re not introducing any new methods that are going to go into the public API (though we could if we wanted to, mind).

public class ComposeMessageDialog extends DialogBox {

  @Inject
  public ComposeMessageDialog(Server server) {
    // whatever...
  }

  // lots and lots of code...
}

Here’s the shim we’re wrapping around it. Any code that could load before the split point should go through this shim and its public API. (Notice how one of the methods we’ve chosen to put in the public API takes a PositionCallback?)

public class ComposeMessageDialogShim
    extends AsyncShim {

  // Public APIs. These are from DialogBox, actually.
  public abstract void show();
  public abstract void setPopupPositionAndShow(
                         PopupPanel.PositionCallback callback);
  public abstract void hide();
  public abstract void hide(boolean autoClosed);

  // See below to learn about onDelayLoadFailure
  @Override
  protected void onDelayLoadFailure(Throwable reason) {
    Window.alert("Error: " + reason.getMessage());
  }
}

And finally, here’s the constructor for a ButtonPanel class—it’s part of the main UI of our app (i.e. will load before the split point) and goes through the shim.

@Inject
public ButtonPanel(ComposeMessageDialogShim shim) {
  Button compose = new Button("Compose", new ClickHandler() {
    public void onClick(ClickEvent event) {
      shim.show();
    }
  });
  Button cancel = new Button("Cancel Compose", new ClickHandler() {
    public void onClick(ClickEvent event) {
      shim.hide();
    }
  });
  // ...
}

That’s all there is to it.

Going (Slightly) Deeper

Well, maybe not all. Your AsyncShim subclasses, e.g. ModuleShim, have some additional features besides loading Module and delegating calls to it.

Success/Failure Callbacks

You can override AsyncShim.onDelayLoadSuccess(T) and onDelayLoadFailure(Throwable).

onDelayLoadFailure will be called if GWT fails to download the code for this split point.

onDelayLoadSuccess is called after the shimmed type (e.g. Module) is successfully instantiated, with the new instance passed as a parameter. This is a handy place to finish whatever initialization needs to be finished before any of the public API methods actually fire. For example, if your Module is actually a Widget then you can have this method add the newly created Widget to the Panel where it should appear.

Prefetching

Prefetching is easy: just call forceLoad(true, null) on your shim. (See the source comments for an explanation of the arguments.)

Inheritance

If you have a bunch of code that you want to reuse between your different Shim subclasses (different split points), for example to have common error handling code, you can create a common Shim base class with common logic for onDelayLoadSuccess and/or onDelayLoadFailure. Inheritance should work as it normally does. Any public abstract void methods that appear in the inheritance hierarchy will become part of the public API (and you’ll get a compile error if the compiler doesn’t like the results).

Limitations

The shim causes public API methods to be executed asynchronously. As a result, all public API methods must return void. If callers need access to the result of a computation, then design your public API method to take a callback as a parameter (which is perfectly cromulent—public API methods absolutely can have parameters!).

Also, multiple calls to the public API methods are not guaranteed to be executed in the order they were called (i.e. no FIFO guarantee). This wouldn’t be hard to add, I just haven’t gotten around to it yet.

Hope That Helps…?

To be honest, it’s been harder to try to explain this library than to actually implement it in the first place. If you’re just not getting it from my explanation but like the idea of clean, reusable GWT.runAsync, drop me a comment below or on Twitter (I’m @jcheng).

Filed under: GWT, Java, Programming   |  14 Comments
Tags: AsyncShim, GWT, Java, Programming