com.google.gwt.user.client.rpc

Interface AsyncCallback<T>

Type Parameters:

T - The type of the return value that was declared in the synchronous version of the method. If the return type is a primitive, use the boxed version of that primitive (for example, an int return type becomes an Integer type argument, and a void return type becomes a Void type argument, which is always null).

public interface AsyncCallback<T>

The primary interface a caller must implement to receive a response from a remote procedure call.

If an RPC is successful, then onSuccess(Object) is called, otherwise onFailure(Throwable) is called.

Each callable asynchronous method corresponds to a method in the correlated service interface. The asynchronous method always takes an AsyncCallback<T> as its last parameter, where T is the return type of the correlated synchronous method.

As an example, suppose the service interface defines a method called getShapes as follows:

 Shape[] getShapes(String databaseName) throws ShapeException, DbException;
 

Its asynchronous counterpart method be declared as:

 void getShapes(String databaseName, AsyncCallback<Shape[]> callback);
 

Note that throws declaration is not repeated in the async version.

A call with a typical use of AsyncCallback might look like this:

 service.getShapes(dbName, new AsyncCallback() {
   public void onSuccess(Shape[] result) {
     // It's always safe to downcast to the known return type. 
     controller.processShapes(result);
   }
 
   public void onFailure(Throwable caught) {
     // Convenient way to find out which exception was thrown.
     try {
       throw caught;
     } catch (IncompatibleRemoteServiceException e) {
       // this client is not compatible with the server; cleanup and refresh the 
       // browser
     } catch (InvocationException e) {
       // the call didn't complete cleanly
     } catch (ShapeException e) {
       // one of the 'throws' from the original method
     } catch (DbException e) {
       // one of the 'throws' from the original method
     } catch (Throwable e) {
       // last resort -- a very unexpected exception
     }
   }
 });
 

Method Summary

Methods

Modifier and Type	Method and Description
void	onFailure(Throwable caught) Called when an asynchronous call fails to complete normally.
void	onSuccess(T result) Called when an asynchronous call completes successfully.

Method Detail

onFailure

void onFailure(Throwable caught)

Called when an asynchronous call fails to complete normally. IncompatibleRemoteServiceExceptions, InvocationExceptions, or checked exceptions thrown by the service method are examples of the type of failures that can be passed to this method.

If caught is an instance of an IncompatibleRemoteServiceException the application should try to get into a state where a browser refresh can be safely done.

Parameters:

caught - failure encountered while executing a remote procedure call

onSuccess

void onSuccess(T result)

Called when an asynchronous call completes successfully.

Parameters:

result - the return value of the remote produced call