KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > google > gwt > user > client > rpc > AsyncCallback


1 /*
2  * Copyright 2006 Google Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5  * use this file except in compliance with the License. You may obtain a copy of
6  * the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13  * License for the specific language governing permissions and limitations under
14  * the License.
15  */
16 package com.google.gwt.user.client.rpc;
17
18 /**
19  * The primary interface a caller must implement to receive a response from a
20  * remote procedure call.
21  *
22  * <p>
23  * If an RPC is successful, then {@link #onSuccess(Object)} is called, otherwise
24  * {@link #onFailure(Throwable)} is called.
25  * </p>
26  *
27  * <p>
28  * Each callable asynchronous method corresponds to a method in the correlated
29  * service interface. The asynchronous method always takes an
30  * <code>AsyncCallback</code> as its last parameter.
31  * </p>
32  *
33  * <p>
34  * As an example, suppose the service interface defines a method called
35  * <code>getShapes</code> as follows:
36  *
37  * <pre>
38  * Shape[] getShapes(String databaseName) throws ShapeException, DbException;
39  * </pre>
40  *
41  * Its asynchronous counterpart method be declared as:
42  *
43  * <pre>
44  * void getShapes(String databaseName, AsyncCallback callback);
45  * </pre>
46  *
47  * Note that <code>throws</code> declaration is not repeated in the async
48  * version.
49  * </p>
50  *
51  * <p>
52  * A call with a typical use of <code>AsyncCallback</code> might look like
53  * this:
54  *
55  * <pre class="code">
56  * service.getShapes(dbName, new AsyncCallback() {
57  * public void onSuccess(Object result) {
58  * // It's always safe to downcast to the known return type.
59  * Shape[] shapes = (Shape[]) result;
60  * controller.processShapes(shapes);
61  * }
62  *
63  * public void onFailure(Throwable caught) {
64  * // Convenient way to find out which exception was thrown.
65  * try {
66  * throw caught;
67  * } catch (IncompatibleRemoteServiceException e) {
68  * // this client is not compatible with the server; cleanup and refresh the
69  * // browser
70  * } catch (InvocationException e) {
71  * // the call didn't complete cleanly
72  * } catch (ShapeException e) {
73  * // one of the 'throws' from the original method
74  * } catch (DbException e) {
75  * // one of the 'throws' from the original method
76  * } catch (Throwable e) {
77  * // last resort -- a very unexpected exception
78  * }
79  * }
80  * });
81  * </pre>
82  *
83  * </p>
84  */
85 public interface AsyncCallback {
86
87   /**
88    * Called when an asynchronous call fails to complete normally.
89    * {@link IncompatibleRemoteServiceException}s, {@link InvocationException}s,
90    * or checked exceptions thrown by the service method are examples of the type
91    * of failures that can be passed to this method.
92    *
93    * <p>
94    * If <code>caught</code> is an instance of an
95    * {@link IncompatibleRemoteServiceException} the application should try to
96    * get into a state where a browser refresh can be safely done.
97    * </p>
98    *
99    * @param caught failure encountered while executing a remote procedure call
100    */
101   void onFailure(Throwable JavaDoc caught);
102
103   /**
104    * Called when an asynchronous call completes successfully. It is always safe
105    * to downcast the parameter (of type <code>Object</code>) to the return
106    * type of the original method for which this is a callback. Note that if the
107    * return type of the synchronous service interface method is a primitive then
108    * the parameter will be the boxed version of the primitive (for example, an
109    * <code>int</code> return type becomes an {@link Integer}.
110    */
111   void onSuccess(Object JavaDoc result);
112 }
113
Popular Tags