Interface AsyncCallback

public interface AsyncCallback
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 as its last parameter.

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 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(Object result) {
     // It's always safe to downcast to the known return type. 
     Shape[] shapes = (Shape[]) result;
     controller.processShapes(shapes);
   }
 
   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
     }
   }
 });

Methods

onFailure(Throwable)Called when an asynchronous call fails to complete normally.
onSuccess(Object)Called when an asynchronous call completes successfully.

Method Detail

onFailure

public 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

public void onSuccess(Object result)
Called when an asynchronous call completes successfully. It is always safe to downcast the parameter (of type Object) to the return type of the original method for which this is a callback. Note that if the return type of the synchronous service interface method is a primitive then the parameter will be the boxed version of the primitive (for example, an int return type becomes an Integer.

Parameters

result