[Java] improve Java API module (#2783)

API module (`ray/java/api` dir) includes all public APIs provided by Ray, it should be the only module that normal Ray users need to face.

The purpose of this PR to first improve the code quality of the API module. Subsequent PRs will improve other modules later. The changes of this PR include the following aspects: 
1) Only keep interfaces in api module, to hide implementation details from users and fix circular dependencies among modules.
2) Document everything in the api module. 
3) Improve naming.
4) Add more tests for API. 
5) Also fix/improve related code in other modules.
6) Remove some unused code.

(Apologize for posting such a large PR. Java worker code has been lack of maintenance for a while. There're a lot of code quality issues that need to be fixed. We plan to use a couple of large PRs to address them. After that, future changes will come in small PRs.)

java/tutorial/src/main/java/org/ray/exercise/Exercise01.java

@@ -3,8 +3,7 @@ package org.ray.exercise;
 import java.io.Serializable;
 import org.ray.api.Ray;
 import org.ray.api.RayObject;
-import org.ray.api.RayRemote;
-import org.ray.core.RayRuntime;
+import org.ray.api.annotation.RayRemote;
 
 /**
  * Define a remote function, and execute multiple remote functions in parallel.
@@ -41,7 +40,7 @@ public class Exercise01 implements Serializable {
     } catch (Throwable t) {
       t.printStackTrace();
     } finally {
-      RayRuntime.getInstance().cleanUp();
+      Ray.shutdown();
     }
   }
 }

java/tutorial/src/main/java/org/ray/exercise/Exercise02.java

@@ -2,8 +2,7 @@ package org.ray.exercise;
 
 import org.ray.api.Ray;
 import org.ray.api.RayObject;
-import org.ray.api.RayRemote;
-import org.ray.core.RayRuntime;
+import org.ray.api.annotation.RayRemote;
 
 /**
  * Execute remote functions in parallel with some dependencies.
@@ -48,7 +47,7 @@ public class Exercise02 {
     } catch (Throwable t) {
       t.printStackTrace();
     } finally {
-      RayRuntime.getInstance().cleanUp();
+      Ray.shutdown();
     }
   }
 }

java/tutorial/src/main/java/org/ray/exercise/Exercise03.java

@@ -2,8 +2,7 @@ package org.ray.exercise;
 
 import org.ray.api.Ray;
 import org.ray.api.RayObject;
-import org.ray.api.RayRemote;
-import org.ray.core.RayRuntime;
+import org.ray.api.annotation.RayRemote;
 
 /**
  * Call a remote function from within another remote function.
@@ -39,7 +38,7 @@ public class Exercise03 {
     } catch (Throwable t) {
       t.printStackTrace();
     } finally {
-      RayRuntime.getInstance().cleanUp();
+      Ray.shutdown();
     }
   }
 }

java/tutorial/src/main/java/org/ray/exercise/Exercise04.java

@@ -4,9 +4,8 @@ import com.google.common.collect.ImmutableList;
 import java.util.List;
 import org.ray.api.Ray;
 import org.ray.api.RayObject;
-import org.ray.api.RayRemote;
 import org.ray.api.WaitResult;
-import org.ray.core.RayRuntime;
+import org.ray.api.annotation.RayRemote;
 
 /**
  * Use Ray.wait to ignore stragglers
@@ -15,16 +14,14 @@ public class Exercise04 {
 
   @RayRemote
   public static String f1() {
-    String ret = "f1";
-    System.out.println(ret);
-    return ret;
+    System.out.println("Executing f1");
+    return "f1";
   }
 
   @RayRemote
   public static String f2() {
-    String ret = "f2";
-    System.out.println(ret);
-    return ret;
+    System.out.println("Executing f2");
+    return "f2";
   }
 
   /**
@@ -32,14 +29,14 @@ public class Exercise04 {
    */
   @RayRemote
   public static String f3() {
-    String ret = "f3";
+    System.out.println("Executing f3");
     try {
       Thread.sleep(5000L);
     } catch (Exception e) {
       e.printStackTrace();
     }
-    System.out.println(ret);
-    return ret;
+    System.out.println("Finished executing f3");
+    return "f3";
   }
 
   public static void main(String[] args) throws Exception {
@@ -54,20 +51,14 @@ public class Exercise04 {
       // or specified timeout have passed.
       // In this case, the result of f3 will be ignored.
       WaitResult<String> waitResult = Ray.wait(waitList, 2, 3000);
-      List<RayObject<String>> readyOnes = waitResult.getReadyOnes();
-      List<RayObject<String>> remainOnes = waitResult.getRemainOnes();
-      System.out.println("Number of readyOnes: " + readyOnes.size());
-      for (int i = 0; i < readyOnes.size(); i++) {
-        System.out.println("The value of readyOnes " + i + " is " + readyOnes.get(i).get());
-      }
-      System.out.println("Number of remainOnes: " + remainOnes.size());
-      for (int i = 0; i < remainOnes.size(); i++) {
-        System.out.println("The value of remainOnes " + i + " is " + remainOnes.get(i).get());
-      }
+      System.out.printf("%d ready object(s): \n", waitResult.getReady().size());
+      waitResult.getReady().forEach(rayObject -> System.out.println(rayObject.get()));
+      System.out.printf("%d unready object(s): \n", waitResult.getUnready().size());
+      waitResult.getUnready().forEach(rayObject -> System.out.println(rayObject.getId()));
     } catch (Throwable t) {
       t.printStackTrace();
     } finally {
-      RayRuntime.getInstance().cleanUp();
+      Ray.shutdown();
     }
   }
 }

java/tutorial/src/main/java/org/ray/exercise/Exercise05.java

@@ -3,8 +3,7 @@ package org.ray.exercise;
 import org.ray.api.Ray;
 import org.ray.api.RayActor;
 import org.ray.api.RayObject;
-import org.ray.api.RayRemote;
-import org.ray.core.RayRuntime;
+import org.ray.api.annotation.RayRemote;
 
 /**
  * Show usage of actors.
@@ -14,8 +13,8 @@ public class Exercise05 {
   public static void main(String[] args) {
     try {
       Ray.init();
-      // `Ray.create` creates an actor instance.
-      RayActor<Adder> adder = Ray.create(Adder.class);
+      // `Ray.createActor` creates an actor instance.
+      RayActor<Adder> adder = Ray.createActor(Adder.class);
       // Use `Ray.call(actor, parameters)` to call an actor method.
       RayObject<Integer> result1 = Ray.call(Adder::add, adder, 1);
       System.out.println(result1.get());
@@ -24,7 +23,7 @@ public class Exercise05 {
     } catch (Throwable t) {
       t.printStackTrace();
     } finally {
-      RayRuntime.getInstance().cleanUp();
+      Ray.shutdown();
     }
   }