[#1576] feat(api): add partition management API

api/src/main/java/com/datastrato/gravitino/exceptions/NoSuchPartitionException.java

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2024 Datastrato Pvt Ltd.
+ * This software is licensed under the Apache License version 2.
+ */
+package com.datastrato.gravitino.exceptions;
+
+/** Exception thrown when a partition with specified name is not existed. */
+public class NoSuchPartitionException extends NotFoundException {
+
+  public NoSuchPartitionException(String message) {
+    super(message);
+  }
+
+  public NoSuchPartitionException(String message, Throwable cause) {
+    super(message, cause);
+  }
+}

api/src/main/java/com/datastrato/gravitino/exceptions/PartitionAlreadyExistsException.java

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2024 Datastrato Pvt Ltd.
+ * This software is licensed under the Apache License version 2.
+ */
+package com.datastrato.gravitino.exceptions;
+
+/** Exception thrown when a partition with specified name already exists. */
+public class PartitionAlreadyExistsException extends AlreadyExistsException {
+
+  public PartitionAlreadyExistsException(String message) {
+    super(message);
+  }
+
+  public PartitionAlreadyExistsException(String message, Throwable cause) {
+    super(message, cause);
+  }
+}

api/src/main/java/com/datastrato/gravitino/rel/SupportsPartitions.java

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2024 Datastrato Pvt Ltd.
+ * This software is licensed under the Apache License version 2.
+ */
+package com.datastrato.gravitino.rel;
+
+import com.datastrato.gravitino.exceptions.NoSuchPartitionException;
+import com.datastrato.gravitino.exceptions.PartitionAlreadyExistsException;
+import com.datastrato.gravitino.rel.partitions.Partition;
+
+public interface SupportsPartitions {
+
+  /**
+   * List all partition names of the table
+   *
+   * @return The list of partition names
+   */
+  String[] listPartitionNames();
+
+  /**
+   * List all partitions
+   *
+   * @return The list of partitions
+   */
+  Partition[] listPartitions();
+
+  /**
+   * Get a partition by partition name
+   *
+   * @param partitionName the name of the partition
+   * @return the partition
+   * @throws NoSuchPartitionException if the partition does not exist
+   */
+  Partition getPartition(String partitionName) throws NoSuchPartitionException;
+
+  /**
+   * Check if a partition exists.
+   *
+   * @param partitionName The name of the partition.
+   * @return True if the partition exists, false otherwise.
+   */
+  default boolean partitionExists(String partitionName) {
+    try {
+      getPartition(partitionName);
+      return true;
+    } catch (NoSuchPartitionException e) {
+      return false;
+    }
+  }
+
+  /**
+   * Add a partition with specified name and properties to the table.
+   *
+   * @param partition The partition to add.
+   * @return The created partition.
+   * @throws PartitionAlreadyExistsException If the partition already exists.
+   */
+  Partition addPartition(Partition partition) throws PartitionAlreadyExistsException;
+
+  /**
+   * Drop a partition with specified name.
+   *
+   * @param partitionName The identifier of the partition.
+   * @return true if a partition was deleted, false if the partition did not exist.
+   */
+  boolean dropPartition(String partitionName);
+
+  /**
+   * If the table supports purging, drop a partition with specified name and completely remove
+   * partition data by skipping a trash.
+   *
+   * @param partitionName The name of the partition.
+   * @return true if a partition was deleted, false if the partition did not exist.
+   * @throws NoSuchPartitionException If the partition does not exist.
+   * @throws UnsupportedOperationException If partition purging is not supported.
+   */
+  default boolean purgePartition(String partitionName)
+      throws NoSuchPartitionException, UnsupportedOperationException {
+    throw new UnsupportedOperationException("Partition purging is not supported");
+  }
+}

api/src/main/java/com/datastrato/gravitino/rel/Table.java

@@ -58,4 +58,15 @@ default String comment() {
   default Map<String, String> properties() {
     return Collections.emptyMap();
   }
+
+  /**
+   * Table method for working with partitions. If the table does not support partition operations,
+   * an {@link UnsupportedOperationException} is thrown.
+   *
+   * @return The partition support table.
+   * @throws UnsupportedOperationException If the table does not support partition operations.
+   */
+  default SupportsPartitions supportPartitions() throws UnsupportedOperationException {
+    throw new UnsupportedOperationException("Table does not support partition operations.");
+  }
 }

api/src/main/java/com/datastrato/gravitino/rel/partitions/IdentityPartition.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2024 Datastrato Pvt Ltd.
+ * This software is licensed under the Apache License version 2.
+ */
+package com.datastrato.gravitino.rel.partitions;
+
+import com.datastrato.gravitino.rel.expressions.literals.Literal;
+
+/**
+ * An identity partition represents a result of identity partitioning. For example, for Hive
+ * partition
+ *
+ * <pre>`PARTITION (dt='2008-08-08',country='us')`</pre>
+ *
+ * its partition name is "dt=2008-08-08/country=us", field names are [["dt"], ["country"]] and
+ * values are ["2008-08-08", "us"].
+ */
+public interface IdentityPartition extends Partition {
+
+  /** @return The field names of the identity partition. */
+  String[][] fieldNames();
+
+  /**
+   * @return The values of the identity partition. The values are in the same order as the field
+   *     names.
+   */
+  Literal<?>[] values();
+}

api/src/main/java/com/datastrato/gravitino/rel/partitions/ListPartition.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2024 Datastrato Pvt Ltd.
+ * This software is licensed under the Apache License version 2.
+ */
+package com.datastrato.gravitino.rel.partitions;
+
+import com.datastrato.gravitino.rel.expressions.literals.Literal;
+
+/**
+ * A list partition represents a result of list partitioning. For example, for list partition
+ *
+ * <pre>
+ *     `PARTITION p202204_California VALUES IN (
+ *       ("2022-04-01", "Los Angeles"),
+ *       ("2022-04-01", "San Francisco")
+ *     )`
+ *     </pre>
+ *
+ * its name is "p202204_California" and lists are [["2022-04-01","Los Angeles"], ["2022-04-01", "San
+ * Francisco"]].
+ */
+public interface ListPartition extends Partition {
+
+  /** @return The values of the list partition. */
+  Literal<?>[][] lists();
+}

api/src/main/java/com/datastrato/gravitino/rel/partitions/Partition.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2024 Datastrato Pvt Ltd.
+ * This software is licensed under the Apache License version 2.
+ */
+package com.datastrato.gravitino.rel.partitions;
+
+import com.datastrato.gravitino.rel.Table;
+import java.util.Map;
+
+/**
+ * A partition represents a result of partitioning a table. The partition can be either a {@link
+ * IdentityPartition}, {@link ListPartition} or {@link RangePartition}. It depends on the {@link
+ * Table#partitioning()}.
+ */
+public interface Partition {
+
+  /** @return The name of the partition. */
+  String name();
+
+  /** @return The properties of the partition, such as statistics, location, etc. */
+  Map<String, String> properties();
+}