001: /*
002: * Copyright 2006 Google Inc.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005: * use this file except in compliance with the License. You may obtain a copy of
006: * the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013: * License for the specific language governing permissions and limitations under
014: * the License.
015: */
016: package com.google.gwt.user.client.rpc;
017:
018: /**
019: * The primary interface a caller must implement to receive a response from a
020: * remote procedure call.
021: *
022: * <p>
023: * If an RPC is successful, then {@link #onSuccess(Object)} is called, otherwise
024: * {@link #onFailure(Throwable)} is called.
025: * </p>
026: *
027: * <p>
028: * Each callable asynchronous method corresponds to a method in the correlated
029: * service interface. The asynchronous method always takes an
030: * <code>AsyncCallback</code> as its last parameter.
031: * </p>
032: *
033: * <p>
034: * As an example, suppose the service interface defines a method called
035: * <code>getShapes</code> as follows:
036: *
037: * <pre>
038: * Shape[] getShapes(String databaseName) throws ShapeException, DbException;
039: * </pre>
040: *
041: * Its asynchronous counterpart method be declared as:
042: *
043: * <pre>
044: * void getShapes(String databaseName, AsyncCallback callback);
045: * </pre>
046: *
047: * Note that <code>throws</code> declaration is not repeated in the async
048: * version.
049: * </p>
050: *
051: * <p>
052: * A call with a typical use of <code>AsyncCallback</code> might look like
053: * this:
054: *
055: * <pre class="code">
056: * service.getShapes(dbName, new AsyncCallback() {
057: * public void onSuccess(Object result) {
058: * // It's always safe to downcast to the known return type.
059: * Shape[] shapes = (Shape[]) result;
060: * controller.processShapes(shapes);
061: * }
062: *
063: * public void onFailure(Throwable caught) {
064: * // Convenient way to find out which exception was thrown.
065: * try {
066: * throw caught;
067: * } catch (IncompatibleRemoteServiceException e) {
068: * // this client is not compatible with the server; cleanup and refresh the
069: * // browser
070: * } catch (InvocationException e) {
071: * // the call didn't complete cleanly
072: * } catch (ShapeException e) {
073: * // one of the 'throws' from the original method
074: * } catch (DbException e) {
075: * // one of the 'throws' from the original method
076: * } catch (Throwable e) {
077: * // last resort -- a very unexpected exception
078: * }
079: * }
080: * });
081: * </pre>
082: *
083: * </p>
084: *
085: * @param <T>
086: */
087: public interface AsyncCallback<T> {
088:
089: /**
090: * Called when an asynchronous call fails to complete normally.
091: * {@link IncompatibleRemoteServiceException}s, {@link InvocationException}s,
092: * or checked exceptions thrown by the service method are examples of the type
093: * of failures that can be passed to this method.
094: *
095: * <p>
096: * If <code>caught</code> is an instance of an
097: * {@link IncompatibleRemoteServiceException} the application should try to
098: * get into a state where a browser refresh can be safely done.
099: * </p>
100: *
101: * @param caught failure encountered while executing a remote procedure call
102: */
103: void onFailure(Throwable caught);
104:
105: /**
106: * Called when an asynchronous call completes successfully. It is always safe
107: * to downcast the parameter (of type <code>Object</code>) to the return
108: * type of the original method for which this is a callback. Note that if the
109: * return type of the synchronous service interface method is a primitive then
110: * the parameter will be the boxed version of the primitive (for example, an
111: * <code>int</code> return type becomes an {@link Integer}.
112: */
113: void onSuccess(T result);
114: }
|