Google Gears is a library that enables your web applications to work offline. Currently it consists of three modules: LocalServer for caching and serving up your web app resources (ie. html, javascript, images), a SQLite Database for storing offline data, and a WorkerPool for performing asynchronous operations. My GWT application, a free Sudoku game called GSudokr seemed to be a good candidate for testing out the LocalServer module of Gears as it doesn’t have any complicated requirements like synchronizing back to a server. After reading all the documentation, I was able to get everything working in less than a day. In this short tutorial, I will walk you through the steps I took to get GSudokr working offline using Gears.

Installing

Download the following:

On OS X, Google Gears is installed as a Firefox extension. On Windows, it’s actually a standalone installer which enables Gears support for both IE and Firefox. The gwt-google-apis project is a library for GWT that support the various Google APIs. Lucky for us, the first API they decided to support was Google Gears!

Add gwt-google-apis.jar to your project and in your GWT module xml file, you’ll need to add the line:

Working with the API

The basic class for serving up locally cached pages is called LocalServer. In your application you can instantiate the class like this.

try {
    localServer = new LocalServer();
 }
 catch (GearsException e) {
    // Will throw GearsException if Gears is not installed
 }

If the user does not have Gears installed than LocalServer cannot be instantiated and will throw a GearsException. So be aware of this situation and display an appropriate message for your users.

LocalServer is used to create resource stores, which are a collection of URLs to cache. There are two types of supported resource stores, ResourceStore and ManagedResourceStore. With ResourceStore, you pass in the name of the urls to cache inside your application using the captureURLs() method. On the other hand, ManagedResourceStore, lets you list these urls in an external manifest file. Since GWT generates its files dynamically, ManagedResourceStore is the only approach that will work. To save the effort of trying to input all the urls by hand into the manifest, I wrote a simple php script which I run after compiling my app, that will generate the appropriate manifest. Take a look at it as an example. [generateManifest.php]

The code to create the resource store, open it and set the manifest url is straightforward. I took the code straight from the sample ManagedResourceStoreDemo in the gwt-google-api distribution. The interesting part of the code is the checkForUpdate() method.

managedResourceStore.checkForUpdate();
new Timer() {
   public void run() {
      switch (managedResourceStore.getUpdateStatus()) {
         case ManagedResourceStore.UPDATE_OK:
            statusLabel.setText("Ready for offline access");
            break;
         case ManagedResourceStore.UPDATE_CHECKING:
         case ManagedResourceStore.UPDATE_DOWNLOADING:
            schedule(500);
            break;
         case ManagedResourceStore.UPDATE_FAILED:
             statusLabel.setText("Unable to go offline");
             break;
         }
      }
}.schedule(500);

ManagedResourceStore’s checkForUpdate() method tells Gears to asynchronously check your manifest file and start downloading the resources specified in it. A timer is then created which checks the update status on the store to see if your files have been downloaded and cached. You can use the various status codes to inform the user in your UI about what’s going on. When you receive the UPDATE_OK code, your app is ready to go offline. To test this, use the Work Offline function in your browser (Firefox: File > Work Offline). Make sure to clear your cache, and try to access your application using your regular url.

As you can see, it is quite simple to get your GWT applications working offline using LocalServer. Keep in mind that Gears is still in beta and the user experience still leaves something to be desired, especially to the casual user. Still, it’s quite cool to able to add offline capabilities to your web application with a minimal amount of effort.

References

• GSudokr
• Building Offline Salesforce Applications with Google Gears and GWT