add the java doc for RelationBackend

apache · Feb 4, 2024 · 0ddbc53 · 0ddbc53
1 parent 5a71b98
commit 0ddbc53
Show file tree

Hide file tree

Showing 3 changed files with 74 additions and 20 deletions.
diff --git a/core/src/main/java/com/datastrato/gravitino/storage/relation/RelationBackend.java b/core/src/main/java/com/datastrato/gravitino/storage/relation/RelationBackend.java
@@ -10,32 +10,85 @@
 import com.datastrato.gravitino.HasIdentifier;
 import com.datastrato.gravitino.NameIdentifier;
 import com.datastrato.gravitino.Namespace;
-import com.datastrato.gravitino.exceptions.AlreadyExistsException;
 import com.datastrato.gravitino.exceptions.NoSuchEntityException;
 import java.io.Closeable;
 import java.io.IOException;
 import java.util.List;
 import java.util.function.Function;
 
+/** Interface defining the operations for a Relation Backend. */
 public interface RelationBackend extends Closeable {
 
-  void initialize(Config config) throws IOException;
+  /**
+   * Initializes the Relation Backend environment with the provided configuration.
+   *
+   * @param config The configuration for the backend.
+   */
+  void initialize(Config config);
 
+  /**
+   * List the entities associated with the given parent namespace and entityType
+   *
+   * @param namespace The parent namespace of these entities.
+   * @param entityType The type of these entities.
+   * @return The list of entities associated with the given parent namespace and entityType, or null
+   *     if the entities does not exist.
+   * @throws NoSuchEntityException If the corresponding parent entity of these list entities cannot
+   *     be found.
+   */
   <E extends Entity & HasIdentifier> List<E> list(Namespace namespace, Entity.EntityType entityType)
-      throws IOException;
+      throws NoSuchEntityException;
 
-  boolean exists(NameIdentifier ident, Entity.EntityType entityType) throws IOException;
+  /**
+   * Check the entity associated with the given identifier and entityType whether exists.
+   *
+   * @param ident The identifier of the entity.
+   * @param entityType The type of the entity.
+   * @return True, if the entity can be found, else return false.
+   */
+  boolean exists(NameIdentifier ident, Entity.EntityType entityType);
 
+  /**
+   * Stores the entity, possibly overwriting an existing entity if specified.
+   *
+   * @param e The entity which need be stored.
+   * @param overwritten If true, overwrites the existing value.
+   * @throws EntityAlreadyExistsException If the entity already exists and overwrite is false.
+   */
   <E extends Entity & HasIdentifier> void insert(E e, boolean overwritten)
-      throws IOException, EntityAlreadyExistsException;
+      throws EntityAlreadyExistsException;
 
+  /**
+   * Update the entity.
+   *
+   * @param ident The identifier of the entity which need be stored.
+   * @param entityType The type of the entity.
+   * @return The entity after updating.
+   * @throws NoSuchEntityException If the entity is not exist.
+   */
   <E extends Entity & HasIdentifier> E update(
       NameIdentifier ident, Entity.EntityType entityType, Function<E, E> updater)
-      throws IOException, NoSuchEntityException, AlreadyExistsException;
+      throws NoSuchEntityException;
 
+  /**
+   * Retrieves the entity associated with the identifier and the entity type.
+   *
+   * @param ident The identifier of the entity.
+   * @param entityType The type of the entity.
+   * @return The entity associated with the identifier and the entity type, or null if the key does
+   *     not exist.
+   * @throws IOException If an I/O exception occurs during retrieval.
+   */
   <E extends Entity & HasIdentifier> E get(NameIdentifier ident, Entity.EntityType entityType)
-      throws NoSuchEntityException, IOException;
-
-  boolean delete(NameIdentifier ident, Entity.EntityType entityType, boolean cascade)
       throws IOException;
+
+  /**
+   * Deletes the entity associated with the identifier and the entity type.
+   *
+   * @param ident The identifier of the entity.
+   * @param entityType The type of the entity.
+   * @param cascade True, If you need to cascade delete entities, else false.
+   * @return True, if the entity was successfully deleted, else false.
+   */
+  boolean delete(NameIdentifier ident, Entity.EntityType entityType, boolean cascade);
 }
diff --git a/core/src/main/java/com/datastrato/gravitino/storage/relation/RelationEntityStore.java b/core/src/main/java/com/datastrato/gravitino/storage/relation/RelationEntityStore.java
@@ -95,7 +95,11 @@ public <E extends Entity & HasIdentifier> E update(
   public <E extends Entity & HasIdentifier> E get(
       NameIdentifier ident, Entity.EntityType entityType, Class<E> e)
       throws NoSuchEntityException, IOException {
-    return backend.get(ident, entityType);
+    E entity = backend.get(ident, entityType);
+    if (entity == null) {
+      throw new NoSuchEntityException(ident.toString());
+    }
+    return entity;
   }
 
   @Override

diff --git a/core/src/main/java/com/datastrato/gravitino/storage/relation/mysql/MySQLBackend.java b/core/src/main/java/com/datastrato/gravitino/storage/relation/mysql/MySQLBackend.java
@@ -10,7 +10,6 @@
 import com.datastrato.gravitino.HasIdentifier;
 import com.datastrato.gravitino.NameIdentifier;
 import com.datastrato.gravitino.Namespace;
-import com.datastrato.gravitino.exceptions.AlreadyExistsException;
 import com.datastrato.gravitino.exceptions.NoSuchEntityException;
 import com.datastrato.gravitino.storage.relation.RelationBackend;
 import java.io.IOException;
@@ -26,44 +25,42 @@ public class MySQLBackend implements RelationBackend {
 
   /** Initialize the MySQL backend instance. */
   @Override
-  public void initialize(Config config) throws IOException {
+  public void initialize(Config config) {
     throw new UnsupportedOperationException("Unsupported operation now.");
   }
 
   @Override
   public <E extends Entity & HasIdentifier> List<E> list(
-      Namespace namespace, Entity.EntityType entityType) throws IOException {
+      Namespace namespace, Entity.EntityType entityType) throws NoSuchEntityException {
     throw new UnsupportedOperationException("Unsupported operation now.");
   }
 
   @Override
-  public boolean exists(NameIdentifier ident, Entity.EntityType entityType) throws IOException {
+  public boolean exists(NameIdentifier ident, Entity.EntityType entityType) {
     throw new UnsupportedOperationException("Unsupported operation now.");
   }
 
   @Override
   public <E extends Entity & HasIdentifier> void insert(E e, boolean overwritten)
-      throws IOException, EntityAlreadyExistsException {
+      throws EntityAlreadyExistsException {
     throw new UnsupportedOperationException("Unsupported operation now.");
   }
 
   @Override
   public <E extends Entity & HasIdentifier> E update(
       NameIdentifier ident, Entity.EntityType entityType, Function<E, E> updater)
-      throws IOException, NoSuchEntityException, AlreadyExistsException {
+      throws NoSuchEntityException {
     throw new UnsupportedOperationException("Unsupported operation now.");
   }
 
   @Override
   public <E extends Entity & HasIdentifier> E get(
-      NameIdentifier ident, Entity.EntityType entityType)
-      throws NoSuchEntityException, IOException {
+      NameIdentifier ident, Entity.EntityType entityType) throws IOException {
     throw new UnsupportedOperationException("Unsupported operation now.");
   }
 
   @Override
-  public boolean delete(NameIdentifier ident, Entity.EntityType entityType, boolean cascade)
-      throws IOException {
+  public boolean delete(NameIdentifier ident, Entity.EntityType entityType, boolean cascade) {
     throw new UnsupportedOperationException("Unsupported operation now.");
   }