In writing the shell for the component, you’ll deal with the layout of the component and not worry much about the inner workings yet. Once you complete the shell, you can move on to the next step and start having the component display data.

As we stated earlier, you need to decide which GWT user-interface component to extend. In figure 11.1, we showed that the outer shell of the component uses a VerticalPanel, but this isn’t a good choice for the basis of the component. The reason is that VerticalPanel exposes several methods that you don’t want the component to support. For example, the add() and remove() methods of VerticalPanel could be used to add or remove widgets from the finished component, changing the desired layout. For this reason, you want to extend com.google.gwt.user.client.ui.Composite. The Composite class provides several protected methods for use by an extending class and only publicly exposes a getElement() method.

In listing 11.1, you create the class ServerStatusComponent and place it in the org.gwtbook.client package with the rest of your client code. You define a private variable for each component that makes up the composite. This includes each of the components we discussed, including the five labels to hold the statistics you receive from the server.

Example 11.1. Coding the structure of the ServerStatusComponent

Thus far, the only code you’ve included is the constructor for the ServerStatusComponent. The constructor calls the initWidget() method of the superclass, passing it a newly created VerticalPanel instance. This sets the user interface component that will be used as the outer shell for the component. To this, you add the title bar label, the statistics grid, the update button, and the last-updated label.

Next, you need to update the entry-point class to reflect that you’re now packaging the Server Status as a component. Notice that by encapsulating the ServerStatusComponent as a component, you’re able to instantiate it and add it to the RootPanel with only two lines of code (see listing 11.2).

import com.google.gwt.core.client.*;
import com.google.gwt.user.client.rpc.*;
import com.google.gwt.user.client.ui.*;

public class ServerStatus implements EntryPoint
{
  public void onModuleLoad ()
  {
    ServerStatusComponent serverStatus =
        new ServerStatusComponent();
    RootPanel.get().add(serverStatus);
  }
}

You can now view the project in the hosted-mode browser; it should look like figure 11.2.

Figure 11.2. The incomplete shell of the Server Status component example running in the hosted-mode browser

The component looks a little sparse at this point, not only because you haven’t supplied any data, but also because you haven’t yet applied CSS styling.

As you saw in chapter 4, you can attach CSS class names to the individual parts of a component. You need to specify separate style class names for the title-bar, Grid component, update button, last-updated label, and the Composite as a whole. You also need to add labels to each row in the grid, to the left of where each data value will be displayed. See listing 11.3.

Example 11.3. Adding style classes and labels to the Server Status component

In listing 11.3, you reference two methods that you haven’t yet defined. The first is addRowToGrid(), which helps you populate the statistics grid; and the second is getStatusDataFromServer(), which is the method that triggers a call to the server.

For each row, addRowToGrid() sets the title of the value, which appears on the left side of the grid, and inserts the Label component to the right of it. For each title, you set the style class name to be stat-name, and for each value you set the style name to be stat-value. Creating methods like this that group repetitious code is extremely helpful, especially because GWT code can easily become verbose.

getStatusDataFromServer() will be used to trigger an RPC call to the server. We’ll describe this method and its purpose shortly, but for now you leave that method as an empty stub. Listing 11.4 shows the two methods you will add to the Server Status component.

private void addRowToGrid (String name, Widget widget, int row)
{
  serverStats.setText(row, 0, name);
  serverStats.setWidget(row, 1, widget);
  serverStats.getCellFormatter().setStyleName(row, 0, "stat-name");
  serverStats.getCellFormatter().setStyleName(row, 1, "stat-value");
}

private void getStatusDataFromServer ()
{
}

If you run the application now, you see that it’s starting to come together. Figure 11.3 shows what the application should look like.

Figure 11.3. A nearly complete version of the Server Status component example

This assumes you’ve been following the example throughout the chapter and are using the CSS provided in section 10.1.

Now that you have the majority of the application’s moving parts, you need to fill in the getStatusDataFromServer() method, which calls the remote method. You’ll do this a little differently than you did in the prior section: This time, you’ll encapsulate the interface to the server as a façade.

If you go back to the Command pattern example, there are two ways in which you can provide shared logging functionality. The first is by chaining callbacks, and the second is to provide a superclass to the ServerStatsUpdater class, which includes logging capabilities. Let’s examine how to solve this problem by chaining callbacks. To do this, you need to create a new class called LoggingChainingCallback (see listing 11.8).

package org.gwtbook.client;

import com.google.gwt.core.client.GWT;
import com.google.gwt.user.client.rpc.AsyncCallback;

public class LoggingChainingCallback implements AsyncCallback {

  private AsyncCallback callback;

  public LoggingChainingCallback(AsyncCallback callback) {
    this.callback = callback;
  }

  public void onFailure(Throwable caught) {
    GWT.log("RPC Failure ["
        + GWT.getTypeName(callback) + "]", caught);
    callback.onFailure(caught);
  }
  public void onSuccess(Object result) {
    GWT.log("RPC Success ["
        + GWT.getTypeName(callback) + "]", null);
    callback.onSuccess(result);
  }
}

The LoggingChainingCallback class implements the AsyncCallback interface and, as such, includes the onFailure() and onSuccess() methods. Notice that you add a constructor to this class. It takes an AsyncCallback as a constructor argument and stores the object in a private instance variable. You reference this instance in both the onFailure() and onSuccess() methods, using it to pass the result to that object after logging the event.

To use this class, all you need to do is alter the calling code slightly. You now pass the new ServerStatsUpdater callback to the constructor of the LoggingChainingCallback. The LoggingChainingCallback instance is then passed as an argument to the getStatusData() method:

private void getStatusDataFromServer ()
{
  ServerService.getInstance().getStatusData(
    new LoggingChainingCallback(new ServerStatsUpdater())
  );
}

If you’re confused about the chain of events, figure 11.4 will help. It shows the sequence of what happens when a successful result is returned from the server. The ServerService calls the onSuccess() method of the LoggingChainingCallback. This class logs the event and then passes the result on to the ServerStatsUpdater, which updates the fields.

Figure 11.4. Chaining actions, where one action performs its task and then passes control to the next

You’ve chained two callbacks together, where each performs its own function without overlap. In this design, you separate out the logging portion of the application so that it can be shared and modified independently of the callbacks to which it passes the request. With a little architecture, you’ve helped to future-proof the application, making it easier to alter logging functionality at a later date.

Besides chaining callbacks, we also mentioned that the Command software pattern allows you to subclass the command to enhance or replace the existing functionality.

As you’ve seen, you’ve applied the Command software pattern by creating a class that implements the AsyncCallback interface. One of the original reasons for doing this was so you could extend the command class, which is something you can’t do if you use an anonymous class for the callback. Again, the goal goes back to the need to separate out the logging for all RPC commands into a single class that can be reused and maintained in a single place.

You can achieve this two ways with a superclass. The first is by convention, and the second is to create a new type of callback interface. By convention, we mean that it’s up to the developer to follow the rules; if the rules are followed, the system works. In general, it’s a bad idea to allow a developer the ability to not follow the rules when functionality could break. But this approach is still useful when you can enforce the convention. For other times, there is a second approach. The goals you’ll attempt to achieve include the following:

To do this, you need to do a little design work. Figure 11.5 shows a high-level overview of what the new structure will look like.

Figure 11.5. Creating your own handler interface so you can add functionality, like logging, in a reusable manner

Figure 11.5 introduces a new interface called AsyncHandler that contains the two methods handleSuccess() and handleFailure(). You then create the class AbstractAsyncHandler that implements both the new interface and GWT’s AsyncCallback interface. You achieve the desired behavior by having this new abstract class intercept the RPC onSuccess() or onFailure() event and then forward it on to either the handleSuccess() or handleFailure() method.

The abstract handler in this sense is passing on the event to a method of a different name. You want to do this so the MyAsyncHandler will implement only the handleSuccess() and handleFailure() methods, and not the methods defined by the AsyncCallback interface. This allows you to extend the AbstractAsyncHandler with a handler with a specific function, like a logging handler, which only overrides the onSuccess() and onFailure() methods.

To build this, you’ll start at the top and work your way down. First, you create the AsyncHandler interface, which defines the two new methods:

package org.gwtbook.client;

public interface AsyncHandler {

  void handleSuccess(Object result);

  void handleFailure(Throwable caught);
}

The AsyncHandler interface mirrors the AsyncCallback interface in that it has two methods with the same parameters and return values; the only difference is the method names. Next, you need to create the AbstractAsyncHandler class (see listing 11.9).

package org.gwtbook.client;

import com.google.gwt.user.client.rpc.AsyncCallback;

public abstract class AbstractAsyncHandler
  implements AsyncCallback, AsyncHandler {

  public void onFailure(Throwable caught) {
    handleFailure(caught);
  }

  public void onSuccess(Object result) {
    handleSuccess(result);
  }
  public abstract void handleFailure(Throwable caught);

  public abstract void handleSuccess(Object result);
}

You declare the class as abstract, as well as the handleFailure() and handleSuccess() methods. This forces subclasses to either declare themselves as abstract or implement the two abstract interfaces. The next class in figure 11.5 is MyLoggingHandler class, but we’re going to skip this one for now because it’s just a placeholder for a handler class containing any type of needed functionality. Let’s skip to MyAsyncHandler, which is the specific handler you need to create for a specific RPC call.

In the Server Status component RPC call, you implemented ServerStatsUpdater as the callback handler. Let’s revisit that handler and alter it to use the new AbstractAsyncHandler as its parent class. The following code replaces the code you used earlier for both the call to the service class and the response handler:

private void getStatusDataFromServer ()
{
  ServerService.getInstance().getStatusData(
    new ServerStatsUpdater());
}

class ServerStatsUpdater extends AbstractAsyncHandler {

  public void handleFailure(Throwable caught) { }

  public void handleSuccess(Object result) {
    // success code
  }
}

This is essentially the same thing you started with, except the ServerStatsUpdater now extends the new AbstractAsyncHandler instead of implementing GWT’s AsyncCallback interface. With this change comes the fact that the handler method names are different, matching the abstract methods of the AbstractAsyncHandler class.

This new structure adds flexibility. As a reminder, these were the goals set forth for organizing the classes in this manner:

To demonstrate that you’ve achieved both of these goals, let’s go back to the logging example and create a subclass of the AbstractAsyncHandler that will automatically log RPC events. Name the class LoggingAsyncHandler to indicate that it provides automatic logging (see listing 11.10).

package org.gwtbook.client;

import com.google.gwt.core.client.GWT;

public abstract class LoggingAsyncHandler
    extends AbstractAsyncHandler {

  public final void onSuccess(Object result) {
    GWT.log("RPC Success [" + GWT.getTypeName(this) + "]", null);
    super.onSuccess(result);
  }

  public final void onFailure(Throwable caught) {
    GWT.log("RPC Failure [" + GWT.getTypeName(this) + "]", caught);
    super.onFailure(caught);
  }
}

Notice that you make the LoggingAsyncHandler class abstract, so it doesn’t need to implement the handleSuccess() and handleFailure() methods. You also override the onSuccess() and onFailure() methods and make them final. The purpose of making them final is so subclasses can’t alter the behavior of the class, which would most likely break it.

The onSuccess() and onFailure() methods are overridden to add the required logging capabilities and log the event prior to the handling of the event by its subclasses. This meets both requirements you set out to achieve.

Figure 11.6 summarizes the chain of events when a response is returned from the server. The LoggingAsyncHandler gets the first look at the response and passes the response up to its parent class, which then passes it down to the only class that implements the abstract handleSuccess() and handleFailure() methods.

Figure 11.6. The sequence of events for the new logging handler that has been inserted between the service and the response handler

It may seem as though you went the long way around to add a couple of simple logging statements, but as your GWT application gets larger, it becomes increasingly important to have a good design. The payback from this additional work comes from reuse of the logging handler and ease of maintenance.

Now that we’ve discussed a couple of patterns for maintainable client-side code, we can turn our attention back to the more general concept of polling.

In theory, pushing data out to your clients is useful. You use it daily when you send an email or an instant message. For example, when you send an email, you’re sending it to a mail server, which in turn pushes the mail to another mail server. The same goes for instant messaging, where the message gets pushed to the intended recipient.

By pushing data out to clients, you can have any number of clients, perhaps many thousands, and no server or bandwidth resources are used until you have something to send. This scales well, and you can easily support any number of clients with this scheme with relative ease.

There is one hitch: Web browsers don’t have this capability. During the 1990s, quite a bit of work went into this area, but it never caught on. Part of the problem is that if you could push data to the browser, it would likely pose security issues, opening the user to a new breed of attack.

Although you can’t achieve true server-push, you’re often required to emulate it—for example, if you want to build a chat client that immediately broadcasts messages it receives. There are several techniques for doing this, like Comet, Pushlet, Pjax, and others. For the most part, these are difficult to implement in GWT, so we won’t discuss them here. Blocking server threads, on the other hand, is easy to implement in GWT; we’ll provide a full example of implementing this a little later.

The opposite of push is pull; we’ll examine pull technologies next.

Client-pull is another name for the standard request-response sequence used by the browser. When you go to a URL with your browser, you request a page from the server or, in other words, pull the page from the server. This technique is useful when a delay between the publication of an event and the receiving of an event is acceptable.

Client-pull has its own challenges. Because there can be a delay between sending and receiving the event, you often need to queue up data on the server, waiting for a client to check in. For example, if you write a chat application using client-pull, the server needs to store any unsent messages for a user until that user pulls the messages.

Between the two types of delivering data, pulling is the natural for web browsers. We’ll examine a client-pull implementation first by implementing a continuously updating component.

The Timer class can be found in the com.google.gwt.user.client package. It provides a no-argument constructor and several methods. The method signatures are as follows:

public abstract class Timer {
  public abstract void run();
  public void schedule(int milliseconds);
  public void scheduleRepeating(int milliseconds);
  public void cancel();
}

The first thing to point out is that the Timer class is abstract, so you must subclass it to be able to use it. You can do this by creating an anonymous class or creating your own specialized timer class. When you implement your class, you need to implement the abstract method, run(), that is called when the timer is triggered. In this example, you create a timer that alerts the user with a “hello” message when a timer event is triggered:

Timer example = new Timer() {
  public void run () {
    Window.alert("hello");
  }
};

To trigger a timer event, you need to set either a one-time event with the schedule() method or a recurring event with the scheduleRepeating() method. In the case of schedule(), you specify the number of milliseconds to wait before executing the run() method. The scheduleRepeating() method also takes the number of milliseconds as a parameter, and it repeatedly executes the run() method. The first execution of run() begins in the number of milliseconds specified and then continuously recurs at that same interval.

The cancel() method, as apparent by its name, allows you to stop the timer. Once it’s stopped, you may start it again by calling either the schedule() or scheduleRepeating() method. The following example sets the timer for five seconds and then cancels it:

example.schedule(5000);
example.cancel(); // just kidding

The next step is to add additional methods to the Server Status component to provide the ability to set the update interval as well as the ability to stop the automatic updates. You’ll do this via a schedulable class.

There are many ways to implement a timer, but you’ll use an approach we think is highly reusable. The code not only can be used in the Server Status component, but also applies to any Composite component. It’s also possible, with some minor changes, to adapt it to other base classes.

You’ll accomplish this by creating a subclass of Composite called UpdateableComposite, shown in figure 11.7, that provides methods for setting and stopping the update timer. Before you start coding, look at the class diagram to see the relationships between the new class and the existing ServerStatusComponent class.

Figure 11.7. A structural overview of the reusable, updateable-composite

We’ll begin by introducing the new UpdateableComposite as a subclass of Composite. UpdateableComposite is an abstract class, meaning that it must be subclassed to use it, and it contains three methods. The startUpdateTimer() method starts the update timer. It allows you to specify the number of seconds between updates; you can use this same method to change the update interval. The update() method is an abstract method and must be implemented by the subclass.

Once you implement UpdateableComposite class, you alter the Server Status component to implement the update() method, and then set the timer (see listing 11.11).

package org.gwtbook.client;

import com.google.gwt.user.client.Timer;
import com.google.gwt.user.client.ui.Composite;

public abstract class UpdateableComposite extends Composite
{
  private Timer timer = null;

  public abstract void update();

  public void startUpdateTimer(int seconds)
  {
    if (timer != null) {
      stopUpdateTimer();
    }

    timer = new Timer() {
      public void run() {
        update();
      }
    };

    timer.scheduleRepeating(seconds * 1000);
  }

  public void stopUpdateTimer()
  {
    if (timer == null)
      return;

    timer.cancel();
    timer = null;
  }
}

The implementation is straightforward but is worth some explanation. The class contains a single private field called timer, which holds the Timer object. You need to hold onto a reference to the Timer object so that you can cancel it when stopUpdateTimer() is called. Looking at the stopUpdateTimer() method, you can see that the method calls cancel() on the Timer object and then sets the timer field to null.

The startUpdateTimer() method first checks to see if the timer field is null. If it isn’t null, this is a sign that it has already been started. The method responds by calling stopUpdateTimer() to cancel the existing timer. This allows you to use startUpdateTimer() to change the interval period without having to worry about stopping the existing timer. The method then goes on to create a Timer instance. You’re creating the Timer as an anonymous class, which prevents external clients of this class from being able to control the timer directly. In the timer’s run() method, you call the abstract method update(). It will be left up to the subclasses of UpdateableComposite to determine what the update() method does.

With the UpdateableComposite complete, the only thing left to do is alter the Server Status component to take advantage of the scheduling capabilities:

public class ServerStatusComponent extends UpdateableComposite
{
  ...

  public void update() {
    getStatusDataFromServer();
  }
}

The only change is that you now extend UpdateableComposite instead of Composite directly, and you implement the update() method. The update() method, in turn, calls the private method getStatusDataFromServer(), which you created before triggering an RPC call to the server. In projects other than the Server Status component, you can include whatever code is required to update the component in the update() method.

With this mechanism in place, you can now easily create and schedule updates for the component. The code to do this for the Server Status component is here, but it will be essentially the same for any custom component that subclasses UpdateableComposite:

ServerStatusComponent serverStatus = new ServerStatusComponent();
serverStatus.startUpdateTimer(60);

In summary, using the GWT Timer class, it’s easy to schedule a piece of code to execute on a schedule. The concepts for doing this are the same no matter if you’re using a timer to schedule polling of the server or updating a display. In either case, it’s always a good idea to think through the design and use the tools that Java provides to create reusable code. The UpdateableComposite is just one example.

Now that we’ve explored timers and, in conjunction, the concept of polling, it’s time to look at how you can emulate server-push and push events to the client browser.

When you implement the client side of blocking server threads, there is little that you need to do. The only requirement is that each time you get a response from the server, you need to initiate a new request. Take the following AsyncCallback implementation for example. We’ve removed the implementation details, but notice that it calls the method getDataFromServer() on both success and failure:

class ChatPanelUpdater implements AsyncCallback
{
  public void onFailure (Throwable caught) {
    ...
    getDataFromServer();
  }

  public void onSuccess (Object result) {
    ...
    getDataFromServer();
  }
}

You’d need to define getDataFromServer(); the only requirement is that this method triggers another RPC request. In the Server Status component, the method getStatusDataFromServer() serves the same purpose.

With this one minor change, we can turn our attention to the more interesting aspects of blocking server threads on the server.

Implementing the server portion of a blocking RPC server can be done the same way you block any Java thread: by issuing a sleep command. When you issue a sleep command to the JVM, it stops processing that specific thread of execution for some amount of time. Once the sleep time is finished, the thread wakes up and continues processing. Issuing a sleep command involves a single statement. The method Thread.sleep() takes a number of milliseconds to sleep; passing 1000 to the method causes the thread to sleep for one second:

Thread.sleep(1000);

For our purposes, you need to do more than just block the thread for some amount of time. You need to first determine whether you should process the request, which in the case of a chat application is when you have a message that you want to send the user. On the other hand, if you don’t have a message to send, you should put the thread to sleep for a short period of time. Once the thread wakes up, you check again whether you should process the request. To do so, you use a loop similar to this:

public List getMessages ()
{
  List result = new ArrayList();

  try {
    while (true) {
      if (canProcess()) {
        result = process();
        break;
      }

      Thread.sleep(1000);
    }
  } catch (InterruptedException ignore) {
  }

  return result;
}

You use the while(true) loop to create an endless loop, and at the end of the loop, you use Thread.sleep() to sleep for one second. Prior to sleeping, you check to see if you can process the request by calling canProcess(); if you can, you call process() to get the result of the RPC call and then break out of the while loop. The try statement catches an InterruptedException, which could result from the call to Thread.sleep()—for example, if the application server was being shut down.

This loop is fine, but what happens if the user closes their browser or navigates to a different web page? Unfortunately, you don’t have a good way to be notified of these events, so potentially a thread could loop forever even though the browser client is no longer present. To solve this problem, you need to introduce a timeout (see listing 11.12).

public List getMessages ()
{
  List result = new ArrayList();
  long timeout = System.currentTimeMillis() + (30 * 1000);

  try {
    while (true) {
      if (canProcess()) {
        result = process();
        break;
      }

      if (System.currentTimeMillis() > timeout) {
        break;
      }

      Thread.sleep(1000);
    }
  } catch (InterruptedException ignore) {
  }

  return result;
}

To the original example, you added a timeout value: You set the value to the current time in milliseconds and add 30 seconds to that value. You also added a check, and, if the current time exceeds the timeout value, it breaks the loop. The timeout value you use depends on your specific project, but in most cases 30 seconds is sufficient to keep the number of requests down while removing stale connections quickly.

The exact implementation of canProcess() and process() depends a lot on the purpose of the method. For example, with the chat application, you’ll likely have a queue of messages for each user of the system, in which case canProcess() returns true if any messages are in the queue for that user. The process() method then returns the list of messages and clears out the queue, or marks the messages in the queue as being delivered.

Now that we’ve shown how you can easily implement polling, let’s turn our attention to a completely different, although equally important, topic: how to create custom serialization routines for your objects.

When GWT serializes or deserializes an object using your custom field serializer class, it calls instantiate(). The purpose of this method is to create a new instance of your object, including passing any values to the constructor required for its creation. This method has a default behavior, and you don’t need to implement the method unless you need to override the implementation. The default behavior as shown here, calls the zero-argument constructor of the data class and returns the instance:

public static ServerStatusData instantiate(
  SerializationStreamReader reader)
  throws SerializationException
{
  return new ServerStatusData();
}

In this implementation, you implemented a field serializer for the data class ServerStatusData. If you were writing a field serializer for a different class, the method signature would change to return an object of that type.

A SerializationStreamReader object is passed to this method and can be used to read values from the serialized stream and use those values in the construction of the object. For example, in the following example, the class FakeData’s constructor takes a String argument, which you pull from the reader:

public static FakeData instantiate(SerializationStreamReader reader)
  throws SerializationException
{
  String val = reader.readString();
  return new FakeData(val);
}

We’ll discuss using the SerializationStreamReader in more detail when we look at the deserialize() method (after the serialize() method).

The serialize() method of the custom field serializer is passed a writer object, which is used to write data to the serialized stream, and an existing object instance, which is the object you’ll serialize. Serialization works by reading some data from the object you’re serializing and then writing that data to the writer.

The writer is an instance of SerializationStreamWriter from the package com.google.gwt.user.client.rpc; it includes methods for writing different types of data to the serialized stream. Following is a list of available writer methods, all of which may throw a SerializationException:

The writer includes a method for each of the Java primitive types as well as the String and Object classes. Writing an object to the stream in turn calls the serializer for that type of object, which could be one of the serializers that comes with GWT or another custom field serializer.

You may write the fields to the stream in any order. The only restriction is that the deserialize() method reads the values from the stream in the same order you wrote them.

The deserialize() method is passed the object instance created by instantiate() and passed a reader so that it can continue reading from the serialized stream. The reader is an instance of SerializationStreamReader from the package com.google.gwt.user.client.rpc. It has a set of methods that allow you to read one value at a time from the serialized stream. The reader methods mirror the writer methods we looked at previously. It’s important that you read the values in the same order as you wrote them, or you’ll likely cause a SerializationException to be thrown—or, even worse, end up with a deserialized object with the wrong data in the wrong fields.

The reader object has the following methods, all of which throw SerializationException:

Just like the writer, there is one method for each of Java’s primitive types, plus String and Object. Calling readObject() in turn causes the deserialization of the value you’re reading.

Here is the deserialize() method for the ServerStatusData object:

public static void deserialize(
  SerializationStreamReader streamReader,
  ServerStatusData instance) throws SerializationException
{
  instance.serverName = streamReader.readString();
  instance.totalMemory = streamReader.readLong();
  instance.freeMemory = streamReader.readLong();
  instance.maxMemory = streamReader.readLong();
  instance.threadCount = streamReader.readInt();
}

The deserialize() method, like the serialize() method, is simple; you read each value from the stream in the proper order and set the appropriate field of the object.