Google Web Toolkit
Search Google Code:

# Creating Services

To develop a new service interface, begin by creating a client-side Java interface that extends the RemoteService tag interface.

    public interface MyService extends RemoteService {
      public String myMethod(String s);
    }

This synchronous interface is the definitive version of your service's specification. Any implementation of this service on the server-side must extend RemoteServiceServlet and implement this service interface.

    public class MyServiceImpl extends RemoteServiceServlet implements
        MyService {

      public String myMethod(String s) {
        // Do something interesting with 's' here on the server.
        return s;
      }

    }

## Asynchronous Interfaces

Before you can actually attempt to make a remote call from the client, you must create another interface, an asynchronous one, based on your original service interface. Continuing with the example above...

    interface MyServiceAsync {
      public void myMethod(String s, AsyncCallback callback);
    }

The nature of asynchronous method calls requires the caller to pass in a callback object that can be notified when an asynchronous call completes, since by definition the caller cannot be blocked until the call completes. For the same reason, asynchronous methods do not have return types; they must always return void. After an asynchronous call is made, all communication back to the caller is via the passed-in callback object.

The relationship between a service interface and its asynchronous counterpart is straightforward:

- If a service interface is called `com.example.cal.client.SpellingService`, then the asynchronous interface must be called `com.example.cal.client.SpellingServiceAsync`. The asynchronous interface must be in the same package and have the same name, but with the suffix `Async`.
- For each method in your service interface,

      public ReturnType methodName(ParamType1 param1, ParamType2 param2);

  an asynchronous sibling method should be defined that looks like this:

      public void methodName(ParamType1 param1, ParamType2 param2,
          AsyncCallback callback);

See AsyncCallback for additional details on how to implement an asynchronous callback.