commit e9993600b0e5b952a1abb830cf42ee9e65ed9db6
author bobv@google.com <bobv@google.com@8db76d5a-ed1c-0410-87a9-c151d255dfc7> Tue Aug 25 22:54:19 2009 +0000
committer bobv@google.com <bobv@google.com@8db76d5a-ed1c-0410-87a9-c151d255dfc7> Tue Aug 25 22:54:19 2009 +0000
tree 55a7b446873ae33b3f5ee01292660616ce0e26f7
parent 7e32a72d5f113db1660b145a7a79ffc6d5e76376

AsyncProxy documentation update.

Patch by: bobv
Review by: rjrjr

git-svn-id: https://google-web-toolkit.googlecode.com/svn/trunk@6016 8db76d5a-ed1c-0410-87a9-c151d255dfc7

user/src/com/google/gwt/user/client/AsyncProxy.java

diff --git a/user/src/com/google/gwt/user/client/AsyncProxy.java b/user/src/com/google/gwt/user/client/AsyncProxy.java
index 893ee90..908235d 100644
--- a/user/src/com/google/gwt/user/client/AsyncProxy.java
+++ b/user/src/com/google/gwt/user/client/AsyncProxy.java
@@ -30,9 +30,8 @@
  * newly-instantiated object after the call to runAsync returns.
  * <p>
  * Once method playback has finished, the proxy will continue to forward
- * invocations onto the instantiated object, although it is recommended that the
- * developer use {@link ProxyCallback#onComplete} to reassign the field
- * containing the proxy.
+ * invocations onto the instantiated object.
+ * 
  * <p>
  * Example use:
  * 
@@ -47,11 +46,28 @@
  * interface FooProxy extends AsyncProxy&lt;IFoo&gt;, IFoo {}
  * 
  * class UserOfIFoo {
- *   private IFoo fooOrProxy = GWT.create(FooProxy.class);
+ *   private IFoo foo = GWT.create(FooProxy.class);
  *   
+ *   void makeTrouble() {
+ *     // This first call triggers a runAsync load
+ *     foo.doSomething(1, 2);
+ *     
+ *     // and this second will replayed after the call to doSomething()
+ *     foo.anotherMethod("A string");
+ *   }
+ * }
+ * </pre>
+ * 
+ * For cases where dispatch speed is critical, a ProxyCallback can be installed
+ * in order to reassign the field containing the AsyncProxy instance with the
+ * backing object:
+ * 
+ * <pre>
+ * class UserOfIFoo {
+ *   private IFoo fooOrProxy = GWT.create(FooProxy.class);
+ *
  *   public UserOfIFoo() {
  *     // When the load, initialization, and playback are done, get rid of the proxy.
- *     // This is actually optional, but will improve subsequent function dispatch speed.
  *     ((AsyncProxy&lt;IFoo&gt;) fooOrProxy).setProxyCallback(new ProxyCallback&lt;IFoo&gt;() {
  *       public void onComplete(IFoo instance) {
  *         fooOrProxy = instance;
@@ -146,8 +162,7 @@
   }
 
   /**
-   * The callback used by
-   * {@link AsyncProxy#setProxyCallback(ProxyCallback)}.
+   * The callback used by {@link AsyncProxy#setProxyCallback(ProxyCallback)}.
    * 
    * @param <T> the interface parameterization of AsyncProxy.
    */