The Java interface is used to define a contract for the communication. As the interface is shared between client and server, they both know which method can be called and what's expected in return. Listing 6-1 shows a contract for requesting a list of tasks. As you can see, defining the interface is really straightforward. Each service can have as many methods as necessary. There's no limitation on how many methods a service provides. The GWT RPC procedure will make sure the correct method is called at the server side.

public interface TaskService extends RemoteService {
    List<Task> getTasks();
}

For GWT to be able to abstract everything away, there are a couple of conditions that need to be fulfilled by this interface. First of all, as it needs to be available for the client-side application, it needs to be placed inside the client package of your GWT application. Second, it should extend the GWT interface com.google.gwt.user.client.rpc.RemoteService in order for the GWT compiler to understand that it defines an RPC interface. Finally, you can only use classes that GWT knows how to send over a wire. As of GWT version 1.5, a class can be transferred if it matches the following conditions:

There's an exception to the last condition. As GWT takes the transient keyword into consideration, everything marked as transient won't be passed between client and server. Additionally, final variables won't be transported at all, so it's a good idea to mark all final variables as transient by default as an indication of the limitation. Listing 6-2 shows an implementation of the Task class.

public class Task implements Serializable {
    private Long id;
    private String title;
    private String description;
    /* getters and setters */
    ...
}

In GWT versions prior to 1.5, there was a fourth condition to be taken into consideration. As stated, for an object to be transferred, it needs to be serializable. The transfer of an instance of java.util.Collections or any of its subclasses (List, Set, and Map) creates a problem. As these collections contain by definition instances of java.lang.Object and Object isn't serializable, the collections wouldn't be eligible for serialization. However, by using the Javadoc annotation @gwt.typeArgs on the methods using the collections, either as arguments or as return value, the GWT compiler could be instructed on how to serialize the collections. This had to be done using Javadoc annotations, because once again, the client side only supported Java 1.4 features. Listing 6-3 shows what the interface looks like for a simple task service with a method to get all task names.

public interface TaskService extends RemoteService {
    /**
      * @gwt.typeArgs <com.apress.beginninggwt.gwtasks.client.Task>
      */
    List getAllTasks();
}

Since the toolkit reached version 1.5, it now supports Java 5 language features. Among these features is generics. While using generics enables a lot of new features in the Java language, primarily it makes it possible to write stronger typed code. Listings 6-4 and 6-5 show two client-side methods for logging the title of tasks. Listing 6-4 doesn't use generics; Listing 6-5 uses generics.

/**
 * @gwt.typeArgs <com.apress.begininggwt.gwtasks.client.Task>
 */
public void logTaskTitles(List tasks) {
    for(int i=0;i<tasks.size();i++) {
        Object o = tasks.get(i);
        if(o instanceof Task) {
            GWT.log(((Task)o).getTitle(), null);
        }
    }
}

public void logTaskTitles(List<Task> tasks) {
    for(int i=0;i<tasks.size();i++) {
        GWT.log(tasks.get(i).getTitle(), null);
    }
}

As you can see, the use of generics in Listing 6-5 makes the code more strongly typed. More strongly typed java code implies less type casting, thus the code becomes cleaner and easier to maintain. Java 5 introduces more features to make the code even cleaner, such as the for-each style for loop, which is also supported in the GWT client side as of version 1.5. Listing 6-6 shows an optimized version of the logTaskTitle method, using all features of Java 5.

public void logTaskTitles(List<Task> tasks) {
    for(Task task : tasks) {
        GWT.log(task.getTitle(), null);
    }
}

For the server side of the GWT RPC mechanism, Google uses servlets. Servlets are a part of the Java Enterprise Edition (Java EE) specifications and are used to make dynamic content available on the Web. Usually servlets are used for HTTP communication only, but this is certainly no limitation of the specification. Wikipedia references Jim Driscoll's blog at java.net, where he writes that James Gosling came up with the idea for servlets back in 1995, but pushed it aside for other interests. The first servlet API is dated from 1997, so servlets have been around for quite some time and are considered relatively mature.

A servlet is an extension of a web container, able to receive a request and form an applicable response for it. The most commonly known web containers are Tomcat and Jetty. The web container receives the actual request and passes it on to a servlet based on the configuration of the container. The request is marshaled into a Request object and passed to the servlet. Hence, the servlet has full knowledge of the request's origin and content without the requirement to know how the data is transferred.

A servlet that needs to handle requests from a GWT application extends the com.google.gwt.user.server.rpc.RemoteServiceServlet class and implements your service interface. The RemoteServiceServlet class puts another layer of abstraction on the Servlet class. With the RemoteServiceServlet class, not only is the serialization abstracted away, it even determines the method that needs to be invoked and invokes it. Hence, the only task left to the developer is to implement the methods from the service interface like any other server-side service. Listing 6-7 shows a simple implementation of our TaskService interface.

public class TaskServiceImpl extends RemoteServiceServlet implements TaskService {
    public List<Task> getTasks() {
        /* ... retrieve a list of tasks
        List<Task> tasks = ...
        return tasks;
    }
}

As you can see, the code is clean and simple. All complex details about receiving the request, deserializing it, parsing it, serializing the response, and returning it to the client are filtered out into the RemoteServiceServlet.

The next step is start using the created service. Remember that GWT RPC uses asynchronous communication. To enable the client to use this, we need to define an asynchronous version of the service interface, next to the synchronous one in the package structure. The difference is in the return values. As the client won't block execution on the call to the service, it needs a hook to be able to do something with the result of the call. For this purpose, the asynchronous interface will have a callback hook that gets executed when the call to service method returns. Listing 6-8 shows the asynchronous version of our TaskService from Listing 6-1. Instead of a zero-argument method returning a list of strings, the method gets an argument for the callback and a void return type.

public interface TaskServiceAsync {
    void getTasks(AsyncCallback asyncCallback);
}
Deferred Binding

Ajax is a set of technologies that make it possible for web applications to give the user a highly interactive experience. Using asynchronous communication, Ajax makes it possible for the application to respond dynamically to user actions by performing background operations. Typically, Ajax calls are made from JavaScript, and using DHTML and DOM, the HTML page is updated to reflect the result. This is the basic form of Ajax, but there are other forms of Ajax that use different technologies for the implementation.

GWT also provides methods for performing simple Ajax calls. Using these methods, you can write your Ajax calls in plain Java, thus allowing GWT to handle the difficulties of the different Ajax implementations available in the different browsers. The first thing to do before you can use the Ajax functionality is enable it. You can enable it by adding an inherits statement in your module configuration. The Ajax functionality is available in a separate module called com.google.gwt.http.HTTP. Listing 6-16 shows the new module descriptor for our GWTasks sample application.

<module>
    <!-- Inherit the core Web Toolkit stuff.                  -->
    <inherits name='com.google.gwt.user.User'/>
    <!--- Enable HTTP stuff support                            -->
    <inherits name="com.google.gwt.http.HTTP"/>
    <!-- Specify the app entry point class.                   -->
    <entry-point class='com.apress.beginninggwt.gwtasks.client.ui.GWTasks'/>

</module>

Now that the HTTP module is enabled, we can start programming our first basic Ajax call. You'll notice that we're going to program the communication on a much lower level than we did with the GWT RPC mechanism. As a consequence, there won't be any convenient Java interfaces to talk to. We have to create the request all by hand and specify every detail we need. There are some easy defaults, but you have to understand them to decide if they're the defaults you need.

We start by instantiating the com.google.gwt.http.client.RequestBuilder. Listing 6-17 shows what the instantiation should look like. This class helps us set up the request and configure its parameters. Its only constructor takes two arguments. The first argument specifies the type of HTTP request and can be either RequestBuilder.GET or RequestBuilder.POST. The second argument is the URL where the service is listening. This could, for example, be a URL where a basic servlet is listening for requests.

RequestBuilder builder = new RequestBuilder(RequestBuilder.GET, requestUrl);

Now that we have the builder instantiated, we can specify the details of the request. By default, the content type specified in the request header is text/plain;charset=utf-8. You can change this value by making a call to RequestBuilder.setHeader(), or extend the values using a call to RequestBuilder.addHeader(). Both methods take a header name and value as arguments. Other methods of RequestBuilder allow you to specify username and password for authentication purposes and configure a timeout for when executing the method takes too long.

When the builder is configured, we can send our request to the server. Based on whether you're using a GET or a POST, you can pass arguments with the request in two different ways. With a GET request, the body of the message remains empty. Therefore, any argument you want to pass to the server must be encoded into the request URL as query parameters. You can recognize query parameters in a URL using a question mark. Multiple query parameters can be placed after the question mark as name-value pairs separated by ampersands. For example, the query ?firstname=bram&lastname=smeets contains two parameters as name-value pairs. Keep in mind that the URL doesn't allow all characters to be used in these name-value pairs. Special consideration should be taken when using a small set of characters. Some characters, for example the space, should be encoded for the URL to remain valid. Fortunately GWT provides a convenience class to perform this encoding called com.google.gwt.http.client.URL. This class provides an encode() and a decode() method so you don't have to bother yourself with escaping the special characters.

Going back to our GWTask example, there are some methods that could easily be implemented using the basic Ajax functionality. Listing 6-18 shows as an example how the login method of the SecurityManager could be implemented. The username and password are for sake of the example passed as query parameters.

public class BasicAjaxSecurityManager implements SecurityManager {
    ....
    public void login(String name, String password, 

            AsyncCallback<Boolean> callback) {
        String requestUrl = URL.encode("login?username=" + username 

                              + "&password=" + password);
        RequestBuilder builder = new RequestBuilder(RequestBuilder.GET, requestUrl);
        builder.setTimeoutMillis(5000);
        builder.setCallback(new RequestCallback() {
            public void onError(Request request, Throwable exception) {
                callback.onFailure(exception);
            }
            public void onResponseReceived(Request request, Response response) {
                if(response.getStatusCode() == 200) {
                    callback.onSuccess(true);
                } else {
                    callback.onSuccess(false);
                }
            }
        });
        try {
            builder.send();
        } catch(RequestException re) {
            callback.onFailure(re);
        }
    }
}

For authenticating a user, only a little data needs to be sent between client and server. However, if we implement the rest of the interfaces, we soon realize that the data sent between client and server becomes more and more complex. We could define some XML schema for the communication and use some client-side marshaller to convert our data structures, but this becomes cumbersome and isn't easy to maintain. Our alternative is the JavaScript Object Notation (JSON). JSON is an easy-to-use data format that can be used to exchange data between systems of different origin. JSON uses a subset of the JavaScript types to define structured data. By no means does it provide any way to transport the data; its only purpose is to structure the data so that it can be easily read and interpreted both by men and machine. At the moment, there are a wide range of JSON implementations available for just as wide a set of languages. So no matter whether you're a C# developer or work with Ruby, Python or Java, there are libraries available that allow you to work with the JSON data format.

The Principles of JSON

So now you're wondering what the deal is with this data format. Well, the designers of JSON kept it real easy. Only the basic types are available. Besides the values null, true, and false, you can have string values and number values. Furthermore, you can create data structures of these values by using an array or an object. The array is like a list of elements, but it isn't type restricted. So there isn't a constriction on putting both string values and number values inside the same array. The object data structure is like a java.util.Map; it consists of key-value pairs. It's ideal for mapping a plain Java object, which Listing 6-19 shows for our Category object. Although this is the real representation, it isn't easy to read and interpret for human beings. However, if we make it pretty and give it some structure, as seen in Listing 6-20, the contents of this JSON data object become much clearer.

{id:372,name:"work",description:"all tasks related to work",subCategories: 

[{id:491,name:"Calls",description:"telephone calls",subCategories:[]},{id: 

284,name:"Meetings",description:"Upcoming meetings",subCategories:[]}]}

{
    id : 372, name : "work",
    description : "all tasks related to work",
    subCategories : [
        {
            id : 491,
            name : "Calls",
            description : "telephone calls",
            subCategories : []
        },
        {
            id : 284,
            name : "Meetings",
            description : "Upcoming meetings",
            subCategories : []
        }
    }
}

Now that we know what the data looks like, the next step is to actually work with the data. The basic principle behind the JSON data format is that it can be interpreted by machines. In JavaScript, this is realized using the eval() function. Note that this function is basic JavaScript; it isn't an addition to the language. The eval() function interprets a string value and executes it as if it were a piece of code. As JSON has its origin in JavaScript, the JSON format complies with the code structure of JavaScript. Therefore, the result of a call to the eval() function with a JSON string as an argument results in a variable with the interpretation of the data structure as its value. Listing 6-21 shows exactly what we could do if we parse the JSON string value of Listing 6-19.

var category = eval(JSONString);
alert(category.name);