[#3731] docs(API): Update the tutorial and document for the Java client API change

clients/client-java/src/main/java/com/datastrato/gravitino/client/FilesetCatalog.java

@@ -97,10 +97,9 @@ public NameIdentifier[] listFilesets(Namespace namespace) throws NoSuchSchemaExc
   }
 
   /**
-   * Load fileset metadata by {@link NameIdentifier} from the catalog, which should be a
-   * "schema.fileset" style.
+   * Load fileset metadata by {@link NameIdentifier} from the catalog.
    *
-   * @param ident A fileset identifier.
+   * @param ident A fileset identifier, which should be "schema.fileset" format.
    * @return The fileset metadata.
    * @throws NoSuchFilesetException If the fileset does not exist.
    */
@@ -128,7 +127,7 @@ public Fileset loadFileset(NameIdentifier ident) throws NoSuchFilesetException {
    *
    * <p>If the type of the fileset object is "EXTERNAL", the underlying storageLocation must be set.
    *
-   * @param ident A fileset identifier, which should be a "schema.fileset" style.
+   * @param ident A fileset identifier, which should be "schema.fileset" format.
    * @param comment The comment of the fileset.
    * @param type The type of the fileset.
    * @param storageLocation The storage location of the fileset.
@@ -172,7 +171,7 @@ public Fileset createFileset(
   /**
    * Update a fileset metadata in the catalog.
    *
-   * @param ident A fileset identifier, which should be a "schema.fileset" style.
+   * @param ident A fileset identifier, which should be "schema.fileset" format.
    * @param changes The changes to apply to the fileset.
    * @return The updated fileset metadata.
    * @throws NoSuchFilesetException If the fileset does not exist.
@@ -209,7 +208,7 @@ public Fileset alterFileset(NameIdentifier ident, FilesetChange... changes)
    * <p>The underlying files will be deleted if this fileset type is managed, otherwise, only the
    * metadata will be dropped.
    *
-   * @param ident A fileset identifier, which should be a "schema.fileset" style.
+   * @param ident A fileset identifier, which should be "schema.fileset" format.
    * @return true If the fileset is dropped, false the fileset did not exist.
    */
   @Override
@@ -240,9 +239,9 @@ static String formatFilesetRequestPath(Namespace ns) {
   }
 
   /**
-   * Check whether the namespace of a fileset is valid
+   * Check whether the namespace of a fileset is valid.
    *
-   * @param namespace The namespace to check
+   * @param namespace The namespace to check.
    */
   static void checkFilesetNamespace(Namespace namespace) {
     Namespace.check(
@@ -252,9 +251,9 @@ static void checkFilesetNamespace(Namespace namespace) {
   }
 
   /**
-   * Check whether the NameIdentifier of a fileset is valid
+   * Check whether the NameIdentifier of a fileset is valid.
    *
-   * @param ident The NameIdentifier to check
+   * @param ident The NameIdentifier to check, which should be "schema.fileset" format.
    */
   static void checkFilesetNameIdentifier(NameIdentifier ident) {
     NameIdentifier.check(ident != null, "NameIdentifier must not be null");
@@ -263,8 +262,14 @@ static void checkFilesetNameIdentifier(NameIdentifier ident) {
     checkFilesetNamespace(ident.namespace());
   }
 
-  private Namespace getFilesetFullNamespace(Namespace tableNamespace) {
-    return Namespace.of(this.catalogNamespace().level(0), this.name(), tableNamespace.level(0));
+  /**
+   * Get the full namespace of the fileset with the given fileset's short namespace (schema name).
+   *
+   * @param filesetNamespace The fileset's short namespace, which is the schema name.
+   * @return full namespace of the fileset, which is "metalake.catalog.schema" format.
+   */
+  private Namespace getFilesetFullNamespace(Namespace filesetNamespace) {
+    return Namespace.of(this.catalogNamespace().level(0), this.name(), filesetNamespace.level(0));
   }
 
   /**

clients/client-java/src/main/java/com/datastrato/gravitino/client/MessagingCatalog.java

@@ -104,7 +104,7 @@ public NameIdentifier[] listTopics(Namespace namespace) throws NoSuchSchemaExcep
   /**
    * Load the topic with the given identifier.
    *
-   * @param ident The identifier of the topic to load, which should be a "schema.topic" style.
+   * @param ident The identifier of the topic to load, which should be "schema.topic" format.
    * @return The {@link Topic} with the specified identifier.
    * @throws NoSuchTopicException if the topic with the specified identifier does not exist.
    */
@@ -127,7 +127,7 @@ public Topic loadTopic(NameIdentifier ident) throws NoSuchTopicException {
   /**
    * Create a new topic with the given identifier, comment, data layout and properties.
    *
-   * @param ident A topic identifier, which should be a "schema.topic" style.
+   * @param ident A topic identifier, which should be "schema.topic" format.
    * @param comment The comment of the topic object. Null is set if no comment is specified.
    * @param dataLayout The message schema of the topic object. Always null because it's not
    *     supported yet.
@@ -166,7 +166,7 @@ public Topic createTopic(
   /**
    * Alter the topic with the given identifier.
    *
-   * @param ident A topic identifier, which should be a "schema.topic" style.
+   * @param ident A topic identifier, which should be "schema.topic" format.
    * @param changes The changes to apply to the topic.
    * @return The altered topic object.
    * @throws NoSuchTopicException if the topic with the specified identifier does not exist.
@@ -200,7 +200,7 @@ public Topic alterTopic(NameIdentifier ident, TopicChange... changes)
   /**
    * Drop the topic with the given identifier.
    *
-   * @param ident A topic identifier, which should be a "schema.topic" style.
+   * @param ident A topic identifier, which should be "schema.topic" format.
    * @return True if the topic is dropped successfully, false the topic does not exist.
    */
   @Override
@@ -226,9 +226,9 @@ static String formatTopicRequestPath(Namespace ns) {
   }
 
   /**
-   * Check whether the namespace of a topic is valid
+   * Check whether the namespace of a topic is valid.
    *
-   * @param namespace The namespace to check
+   * @param namespace The namespace to check.
    */
   static void checkTopicNamespace(Namespace namespace) {
     Namespace.check(
@@ -238,9 +238,9 @@ static void checkTopicNamespace(Namespace namespace) {
   }
 
   /**
-   * Check whether the NameIdentifier of a topic is valid
+   * Check whether the NameIdentifier of a topic is valid.
    *
-   * @param ident The NameIdentifier to check
+   * @param ident The NameIdentifier to check, which should be "schema.topic" format.
    */
   static void checkTopicNameIdentifier(NameIdentifier ident) {
     NameIdentifier.check(ident != null, "NameIdentifier must not be null");
@@ -249,8 +249,14 @@ static void checkTopicNameIdentifier(NameIdentifier ident) {
     checkTopicNamespace(ident.namespace());
   }
 
-  private Namespace getTopicFullNamespace(Namespace tableNamespace) {
-    return Namespace.of(this.catalogNamespace().level(0), this.name(), tableNamespace.level(0));
+  /**
+   * Get the full namespace of the topic with the given topic's short namespace (schema name).
+   *
+   * @param topicNamespace The topic's short namespace, which is the schema name.
+   * @return full namespace of the topic, which is "metalake.catalog.schema" format.
+   */
+  private Namespace getTopicFullNamespace(Namespace topicNamespace) {
+    return Namespace.of(this.catalogNamespace().level(0), this.name(), topicNamespace.level(0));
   }
 
   static class Builder extends CatalogDTO.Builder<Builder> {

clients/client-java/src/main/java/com/datastrato/gravitino/client/RelationalCatalog.java

@@ -107,7 +107,7 @@ public NameIdentifier[] listTables(Namespace namespace) throws NoSuchSchemaExcep
   /**
    * Load the table with specified identifier.
    *
-   * @param ident The identifier of the table to load, which should be a "schema.table" style.
+   * @param ident The identifier of the table to load, which should be "schema.table" format.
    * @return The {@link Table} with specified identifier.
    * @throws NoSuchTableException if the table with specified identifier does not exist.
    */
@@ -130,7 +130,7 @@ public Table loadTable(NameIdentifier ident) throws NoSuchTableException {
   /**
    * Create a new table with specified identifier, columns, comment and properties.
    *
-   * @param ident The identifier of the table, which should be a "schema.table" style.
+   * @param ident The identifier of the table, which should be "schema.table" format.
    * @param columns The columns of the table.
    * @param comment The comment of the table.
    * @param properties The properties of the table.
@@ -181,7 +181,7 @@ public Table createTable(
   /**
    * Alter the table with specified identifier by applying the changes.
    *
-   * @param ident The identifier of the table, which should be a "schema.table" style.
+   * @param ident The identifier of the table, which should be "schema.table" format.
    * @param changes Table changes to apply to the table.
    * @return The altered {@link Table}.
    * @throws NoSuchTableException if the table with specified identifier does not exist.
@@ -215,7 +215,7 @@ public Table alterTable(NameIdentifier ident, TableChange... changes)
   /**
    * Drop the table with specified identifier.
    *
-   * @param ident The identifier of the table, which should be a "schema.table" style.
+   * @param ident The identifier of the table, which should be "schema.table" format.
    * @return true if the table is dropped successfully, false if the table does not exist.
    */
   @Override
@@ -236,7 +236,7 @@ public boolean dropTable(NameIdentifier ident) {
   /**
    * Purge the table with specified identifier.
    *
-   * @param ident The identifier of the table, which should be a "schema.table" style.
+   * @param ident The identifier of the table, which should be "schema.table" format.
    * @return true if the table is purged successfully, false otherwise.
    */
   @Override
@@ -277,7 +277,7 @@ static String formatTableRequestPath(Namespace ns) {
   /**
    * Check whether the namespace of a table is valid, which should be "schema".
    *
-   * @param namespace The namespace to check
+   * @param namespace The namespace to check.
    */
   static void checkTableNamespace(Namespace namespace) {
     Namespace.check(
@@ -287,9 +287,9 @@ static void checkTableNamespace(Namespace namespace) {
   }
 
   /**
-   * Check whether the NameIdentifier of a table is valid, which should be a "schema.table" style.
+   * Check whether the NameIdentifier of a table is valid.
    *
-   * @param ident The NameIdentifier to check
+   * @param ident The NameIdentifier to check, which should be "schema.table" format.
    */
   static void checkTableNameIdentifier(NameIdentifier ident) {
     NameIdentifier.check(ident != null, "NameIdentifier must not be null");
@@ -301,8 +301,8 @@ static void checkTableNameIdentifier(NameIdentifier ident) {
   /**
    * Get the full namespace of the table with the given table's short namespace (schema name).
    *
-   * @param tableNamespace The table's short namespace (schema name).
-   * @return full namespace of the table (metalake.catalog.schema).
+   * @param tableNamespace The table's short namespace, which is the schema name.
+   * @return full namespace of the table, which is "metalake.catalog.schema" format.
    */
   private Namespace getTableFullNamespace(Namespace tableNamespace) {
     return Namespace.of(this.catalogNamespace().level(0), this.name(), tableNamespace.level(0));

clients/client-python/gravitino/catalog/fileset_catalog.py

@@ -101,7 +101,7 @@ def load_fileset(self, ident: NameIdentifier) -> Fileset:
         """Load fileset metadata by {@link NameIdentifier} from the catalog.
 
         Args:
-            ident: A fileset identifier.
+            ident: A fileset identifier, which should be "schema.fileset" format.
 
         Raises:
             NoSuchFilesetException If the fileset does not exist.
@@ -137,7 +137,7 @@ def create_fileset(
         If the type of the fileset object is "EXTERNAL", the underlying storageLocation must be set.
 
         Args:
-            ident: A fileset identifier.
+            ident: A fileset identifier, which should be "schema.fileset" format.
             comment: The comment of the fileset.
             fileset_type: The type of the fileset.
             storage_location: The storage location of the fileset.
@@ -174,7 +174,7 @@ def alter_fileset(self, ident: NameIdentifier, *changes) -> Fileset:
         """Update a fileset metadata in the catalog.
 
         Args:
-            ident: A fileset identifier.
+            ident: A fileset identifier, which should be "schema.fileset" format.
             changes: The changes to apply to the fileset.
 
         Args:
@@ -209,7 +209,7 @@ def drop_fileset(self, ident: NameIdentifier) -> bool:
         metadata will be dropped.
 
         Args:
-             ident: A fileset identifier.
+             ident: A fileset identifier, which should be "schema.fileset" format.
 
         Returns:
              true If the fileset is dropped, false the fileset did not exist.