From d0b324990faf14961c691bbe4b39fff27a497885 Mon Sep 17 00:00:00 2001
From: Larry <554538252@qq.com>
Date: Sat, 2 Apr 2022 18:29:19 +0800
Subject: [PATCH] [Java] Add doc for Ray.get api that throws an exception if it
 times out (#23666)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add doc for Ray.get api that throws an exception if it times out

![image](https://user-images.githubusercontent.com/11072802/161364231-4337124d-3141-4334-879c-f88cecc0d818.png)

Co-authored-by: 稚鱼 <lianjunwen.ljw@antgroup.com>
---
 java/api/src/main/java/io/ray/api/ObjectRef.java                | 1 +
 java/api/src/main/java/io/ray/api/Ray.java                      | 2 ++
 java/api/src/main/java/io/ray/api/runtime/RayRuntime.java       | 2 ++
 .../src/main/java/io/ray/runtime/object/ObjectStore.java        | 2 ++
 4 files changed, 7 insertions(+)

diff --git a/java/api/src/main/java/io/ray/api/ObjectRef.java b/java/api/src/main/java/io/ray/api/ObjectRef.java
index 35286260f..202b47cf7 100644
--- a/java/api/src/main/java/io/ray/api/ObjectRef.java
+++ b/java/api/src/main/java/io/ray/api/ObjectRef.java
@@ -18,6 +18,7 @@ public interface ObjectRef<T> {
    * available.
    *
    * @param timeoutMs The maximum amount of time in miliseconds to wait before returning.
+   * @throws RayTimeoutException If it's timeout to get the object.
    */
   T get(long timeoutMs);
 }
diff --git a/java/api/src/main/java/io/ray/api/Ray.java b/java/api/src/main/java/io/ray/api/Ray.java
index 08e2a393f..5dc3c4e6a 100644
--- a/java/api/src/main/java/io/ray/api/Ray.java
+++ b/java/api/src/main/java/io/ray/api/Ray.java
@@ -83,6 +83,7 @@ public final class Ray extends RayCall {
    * @param objectRef The reference of the object to get.
    * @param timeoutMs The maximum amount of time in miliseconds to wait before returning.
    * @return The Java object.
+   * @throws RayTimeoutException If it's timeout to get the object.
    */
   public static <T> T get(ObjectRef<T> objectRef, long timeoutMs) {
     return internal().get(objectRef, timeoutMs);
@@ -104,6 +105,7 @@ public final class Ray extends RayCall {
    * @param objectList A list of object references.
    * @param timeoutMs The maximum amount of time in miliseconds to wait before returning.
    * @return A list of Java objects.
+   * @throws RayTimeoutException If it's timeout to get the object.
    */
   public static <T> List<T> get(List<ObjectRef<T>> objectList, long timeoutMs) {
     return internal().get(objectList, timeoutMs);
diff --git a/java/api/src/main/java/io/ray/api/runtime/RayRuntime.java b/java/api/src/main/java/io/ray/api/runtime/RayRuntime.java
index be4399271..f1473602e 100644
--- a/java/api/src/main/java/io/ray/api/runtime/RayRuntime.java
+++ b/java/api/src/main/java/io/ray/api/runtime/RayRuntime.java
@@ -74,6 +74,7 @@ public interface RayRuntime {
    * @param objectRef The reference of the object to get.
    * @param timeoutMs The maximum amount of time in millseconds to wait before returning.
    * @return The Java object.
+   * @throws RayTimeoutException If it's timeout to get the object.
    */
   <T> T get(ObjectRef<T> objectRef, long timeoutMs);
 
@@ -83,6 +84,7 @@ public interface RayRuntime {
    * @param objectRefs The list of object references.
    * @param timeoutMs The maximum amount of time in millseconds to wait before returning.
    * @return A list of Java objects.
+   * @throws RayTimeoutException If it's timeout to get the object.
    */
   <T> List<T> get(List<ObjectRef<T>> objectRefs, long timeoutMs);
 
diff --git a/java/runtime/src/main/java/io/ray/runtime/object/ObjectStore.java b/java/runtime/src/main/java/io/ray/runtime/object/ObjectStore.java
index e9f49eebc..2207f1765 100644
--- a/java/runtime/src/main/java/io/ray/runtime/object/ObjectStore.java
+++ b/java/runtime/src/main/java/io/ray/runtime/object/ObjectStore.java
@@ -102,6 +102,7 @@ public abstract class ObjectStore {
    * @param objectIds IDs of the objects to get.
    * @param timeoutMs Timeout in milliseconds, wait infinitely if it's negative.
    * @return Result list of objects data.
+   * @throws RayTimeoutException If it's timeout to get the object.
    */
   public abstract List<NativeRayObject> getRaw(List<ObjectId> objectIds, long timeoutMs);
 
@@ -124,6 +125,7 @@ public abstract class ObjectStore {
    * @param <T> Type of these objects.
    * @param timeoutMs The maximum amount of time in seconds to wait before returning.
    * @return A list of GetResult objects.
+   * @throws RayTimeoutException If it's timeout to get the object.
    */
   @SuppressWarnings("unchecked")
   public <T> List<T> get(List<ObjectId> ids, Class<?> elementType, long timeoutMs) {