[Placement Group] Add get / get all / remove interface for Placement Group Java api. (#11821)

* add placement group java get/get all interface

* add remove placement group api

* fix some issue like: Placement Group -> placement group

* extract dumplicate code to placement group utils

* specify running mode for placement group ut

* update checkGlobalStateAccessorPointerValid -> validateGlobalStateAccessorPointer

* use THROW_EXCEPTION_AND_RETURN_IF_NOT_OK

* update pg log print

java/api/src/main/java/io/ray/api/Ray.java

@@ -1,5 +1,6 @@
 package io.ray.api;
 
+import io.ray.api.id.PlacementGroupId;
 import io.ray.api.id.UniqueId;
 import io.ray.api.placementgroup.PlacementGroup;
 import io.ray.api.placementgroup.PlacementStrategy;
@@ -245,7 +246,7 @@ public final class Ray extends RayCall {
    * to be updated and rescheduled.
    * This function only works when gcs actor manager is turned on.
    *
-   * @param name Name of the Placement Group.
+   * @param name Name of the placement group.
    * @param bundles Pre-allocated resource list.
    * @param strategy Actor placement strategy.
    * @return A handle to the created placement group.
@@ -271,4 +272,30 @@ public final class Ray extends RayCall {
   public static void exitActor() {
     runtime.exitActor();
   }
+
+  /**
+   * Get a placement group by placement group Id.
+   * @param id placement group id.
+   * @return The placement group.
+   */
+  public static PlacementGroup getPlacementGroup(PlacementGroupId id) {
+    return internal().getPlacementGroup(id);
+  }
+
+  /**
+   * Get all placement groups in this cluster.
+   * @return All placement groups.
+   */
+  public static List<PlacementGroup> getAllPlacementGroups() {
+    return internal().getAllPlacementGroups();
+  }
+
+  /**
+   * Remove a placement group by id.
+   * Throw RayException if remove failed.
+   * @param id Id of the placement group.
+   */
+  public static void removePlacementGroup(PlacementGroupId id) {
+    internal().removePlacementGroup(id);
+  }
 }

java/api/src/main/java/io/ray/api/id/PlacementGroupId.java

@@ -0,0 +1,57 @@
+package io.ray.api.id;
+
+import java.io.Serializable;
+import java.nio.ByteBuffer;
+import java.util.Arrays;
+import java.util.Random;
+
+/**
+ * Represents the id of a placement group.
+ */
+public class PlacementGroupId extends BaseId implements Serializable {
+
+  public static final int LENGTH = 16;
+
+  public static final PlacementGroupId NIL = nil();
+
+  private PlacementGroupId(byte[] id) {
+    super(id);
+  }
+
+  /**
+   * Creates a PlacementGroupId from the given ByteBuffer.
+   */
+  public static PlacementGroupId fromByteBuffer(ByteBuffer bb) {
+    return new PlacementGroupId(byteBuffer2Bytes(bb));
+  }
+
+  /**
+   * Create a PlacementGroupId instance according to the given bytes.
+   */
+  public static PlacementGroupId fromBytes(byte[] bytes) {
+    return new PlacementGroupId(bytes);
+  }
+
+  /**
+   * Generate a nil PlacementGroupId.
+   */
+  private static PlacementGroupId nil() {
+    byte[] b = new byte[LENGTH];
+    Arrays.fill(b, (byte) 0xFF);
+    return new PlacementGroupId(b);
+  }
+
+  /**
+   * Generate an PlacementGroupId with random value. Used for local mode and test only.
+   */
+  public static PlacementGroupId fromRandom() {
+    byte[] b = new byte[LENGTH];
+    new Random().nextBytes(b);
+    return new PlacementGroupId(b);
+  }
+
+  @Override
+  public int size() {
+    return LENGTH;
+  }
+}

java/api/src/main/java/io/ray/api/placementgroup/PlacementGroupState.java

@@ -0,0 +1,42 @@
+package io.ray.api.placementgroup;
+
+/**
+ * State of placement group.
+ */
+public enum PlacementGroupState {
+
+  /**
+   * Wait for resource to schedule.
+   */
+  PENDING(0),
+
+  /**
+   * The placement group has created on some node.
+   */
+  CREATED(1),
+
+  /**
+   * The placement group has removed.
+   */
+  REMOVED(2),
+
+  /**
+   * The placement group is rescheduling.
+   */
+  RESCHEDULING(3),
+
+  /**
+   * Unrecognized state.
+   */
+  UNRECOGNIZED(-1);
+
+  private int value = 0;
+
+  PlacementGroupState(int value) {
+    this.value = value;
+  }
+
+  public int value() {
+    return this.value;
+  }
+}

java/api/src/main/java/io/ray/api/placementgroup/PlacementStrategy.java

@@ -23,7 +23,12 @@ public enum PlacementStrategy {
    * Places Bundles across distinct nodes.
    * The group is not allowed to deploy more than one bundle on a node.
    */
-  STRICT_SPREAD(3);
+  STRICT_SPREAD(3),
+
+  /**
+   * Unrecognized strategy.
+   */
+  UNRECOGNIZED(-1);
 
   private int value = 0;
 

java/api/src/main/java/io/ray/api/runtime/RayRuntime.java

@@ -10,6 +10,7 @@ import io.ray.api.function.PyActorMethod;
 import io.ray.api.function.PyFunction;
 import io.ray.api.function.RayFunc;
 import io.ray.api.id.ActorId;
+import io.ray.api.id.PlacementGroupId;
 import io.ray.api.id.UniqueId;
 import io.ray.api.options.ActorCreationOptions;
 import io.ray.api.options.CallOptions;
@@ -202,4 +203,22 @@ public interface RayRuntime {
    */
   void exitActor();
 
+  /**
+   * Get a placement group by id.
+   * @param id placement group id.
+   * @return The placement group.
+   */
+  PlacementGroup getPlacementGroup(PlacementGroupId id);
+
+  /**
+   * Get all placement groups in this cluster.
+   * @return All placement groups.
+   */
+  List<PlacementGroup> getAllPlacementGroups();
+
+  /**
+   * Remove a placement group by id.
+   * @param id Id of the placement group.
+   */
+  void removePlacementGroup(PlacementGroupId id);
 }