* Improve AsyncContext docs (#2101)

* Make the future final which is in the constructor of AsyncRpcResult because of using in a inner class.
apache · Jul 20, 2018 · e22d18c · e22d18c
1 parent bb4ea54
commit e22d18c
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 3 deletions.
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/AsyncContext.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/AsyncContext.java
@@ -27,6 +27,11 @@
  */
 public interface AsyncContext {
 
+    /**
+     * get the internal future which is binding to this async context
+     *
+     * @return the internal future
+     */
     CompletableFuture getInternalFuture();
 
     /**
@@ -51,5 +56,31 @@ public interface AsyncContext {
      */
     void start();
 
+    /**
+     * Signal RpcContext switch.
+     * Use this method to switch RpcContext from a Dubbo thread to a new thread created by the user.
+     *
+     * Note that you should use it in a new thread like this:
+     * <code>
+     * public class AsyncServiceImpl implements AsyncService {
+     *     public String sayHello(String name) {
+     *         final AsyncContext asyncContext = RpcContext.startAsync();
+     *         new Thread(() -> {
+     *
+     *             // right place to use this method
+     *             asyncContext.signalContextSwitch();
+     *
+     *             try {
+     *                 Thread.sleep(500);
+     *             } catch (InterruptedException e) {
+     *                 e.printStackTrace();
+     *             }
+     *             asyncContext.write("Hello " + name + ", response from provider.");
+     *         }).start();
+     *         return null;
+     *     }
+     * }
+     * </code>
+     */
     void signalContextSwitch();
 }
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/AsyncRpcResult.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/AsyncRpcResult.java
@@ -52,9 +52,9 @@ public AsyncRpcResult(CompletableFuture<Object> future, boolean registerCallback
      * @param rFuture
      * @param registerCallback
      */
-    public AsyncRpcResult(CompletableFuture<Object> future, CompletableFuture<Result> rFuture, boolean registerCallback) {
+    public AsyncRpcResult(CompletableFuture<Object> future, final CompletableFuture<Result> rFuture, boolean registerCallback) {
         if (rFuture == null) {
-            throw new IllegalArgumentException("");
+            throw new IllegalArgumentException();
         }
         resultFuture = rFuture;
         if (registerCallback) {
@@ -166,7 +166,7 @@ public void setAttachment(String key, String value) {
     }
 
     /**
-     *
+     * tmp context to use when the thread switch to Dubbo thread.
      */
     private RpcContext tmpContext;
     private RpcContext tmpServerContext;