com.google.gwt.user.client.rpc.AsyncCallback Maven / Gradle / Ivy
/*
* Copyright 2006 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.gwt.user.client.rpc;
/**
* The primary interface a caller must implement to receive a response from a
* remote procedure call.
*
*
* If an RPC is successful, then {@link #onSuccess(Object)} is called, otherwise
* {@link #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
* }
* }
* });
*
*
*
*
* @param 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 {@link Integer} type argument, and a
* void return type becomes a {@link Void} type
* argument, which is always null).
*/
public interface AsyncCallback {
/**
* Called when an asynchronous call fails to complete normally.
* {@link IncompatibleRemoteServiceException}s, {@link InvocationException}s,
* 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
* {@link IncompatibleRemoteServiceException} the application should try to
* get into a state where a browser refresh can be safely done.
*
*
* @param caught failure encountered while executing a remote procedure call
*/
void onFailure(Throwable caught);
/**
* Called when an asynchronous call completes successfully.
*
* @param result the return value of the remote produced call
*/
void onSuccess(T result);
}