link issue 575 in all relevant classes

aastha25 · aastha25 · commit c9762dcc0c24 · 2026-01-13T12:04:24.000-08:00
diff --git a/coral-common/src/main/java/com/linkedin/coral/common/HiveCalciteTableAdapter.java b/coral-common/src/main/java/com/linkedin/coral/common/HiveCalciteTableAdapter.java
@@ -54,8 +54,23 @@
  * into Calcite's {@link ScannableTable}, enabling Hive tables to be queried through Calcite's
  * SQL processing engine.
  *
+ * <p><b>Integration with ParseTreeBuilder and HiveFunctionResolver:</b> This class provides critical
+ * Dali UDF metadata extraction methods ({@link #getDaliFunctionParams()} and {@link #getDaliUdfDependencies()})
+ * that are tightly coupled to {@link org.apache.hadoop.hive.metastore.api.Table} and used by:
+ * <ul>
+ *   <li>{@code HiveFunctionResolver} - for resolving Dali function names to implementing classes</li>
+ *   <li>{@code ParseTreeBuilder} - for parsing view definitions with UDF metadata</li>
+ * </ul>
+ *
+ * <p>These components currently require {@link org.apache.hadoop.hive.metastore.api.Table} and cannot
+ * work directly with {@link com.linkedin.coral.common.catalog.CoralTable}. This tight coupling is being
+ * addressed in <a href="https://github.com/linkedin/coral/issues/575">issue #575</a>, which will refactor
+ * these APIs to accept {@code CoralTable} instead, enabling multi-format support (Hive, Iceberg, etc.).
+ *
  * <p>Implementing this as a ScannableTable, instead of Table, is hacky approach to make calcite
  * correctly generate relational algebra. This will have to go away gradually.
+ *
+ * @see <a href="https://github.com/linkedin/coral/issues/575">Issue #575: Refactor ParseTreeBuilder to Use CoralTable</a>
  */
 public class HiveCalciteTableAdapter implements ScannableTable {
 
diff --git a/coral-common/src/main/java/com/linkedin/coral/common/HiveCalciteViewAdapter.java b/coral-common/src/main/java/com/linkedin/coral/common/HiveCalciteViewAdapter.java
@@ -26,6 +26,18 @@
  *
  * <p>This adapter enables Calcite to process Hive views by implementing the TranslatableTable interface,
  * which allows the view definition to be expanded and converted into a relational algebra tree.
+ *
+ * <p><b>Integration with ParseTreeBuilder:</b> This class inherits the Dali UDF metadata extraction
+ * methods from {@link HiveCalciteTableAdapter}, which are used by {@code ParseTreeBuilder} and
+ * {@code HiveFunctionResolver} for parsing view definitions with custom functions. These components
+ * are currently tightly coupled to {@link org.apache.hadoop.hive.metastore.api.Table} and cannot
+ * work directly with {@link com.linkedin.coral.common.catalog.CoralTable}.
+ *
+ * <p>This coupling is being addressed in <a href="https://github.com/linkedin/coral/issues/575">issue #575</a>,
+ * which will refactor these APIs to accept {@code CoralTable} instead, enabling multi-format support.
+ *
+ * @see HiveCalciteTableAdapter
+ * @see <a href="https://github.com/linkedin/coral/issues/575">Issue #575: Refactor ParseTreeBuilder to Use CoralTable</a>
  */
 public class HiveCalciteViewAdapter extends HiveCalciteTableAdapter implements TranslatableTable {
   private final List<String> schemaPath;
diff --git a/coral-common/src/main/java/com/linkedin/coral/common/HiveDbSchema.java b/coral-common/src/main/java/com/linkedin/coral/common/HiveDbSchema.java
@@ -22,7 +22,33 @@
 
 /**
  * Adaptor from Hive catalog providing database and table names
- * to Calcite {@link Schema}
+ * to Calcite {@link Schema}. This class represents a database-level schema
+ * that contains tables and dispatches to format-specific Calcite adapters.
+ *
+ * <p><b>LEGACY API:</b> This class exists for backward compatibility with existing code
+ * that uses {@link HiveMetastoreClient} directly. For new code, prefer {@link CoralDatabaseSchema}
+ * which integrates with the unified {@link com.linkedin.coral.common.catalog.CoralCatalog} API
+ * and provides cleaner multi-format support (Hive, Iceberg, etc.) without Hive-specific coupling.
+ *
+ * <p><b>Table Dispatch:</b> This class creates Calcite table adapters based on table type:
+ * <ul>
+ *   <li>{@link HiveCalciteViewAdapter} for Hive views (VIRTUAL_VIEW)</li>
+ *   <li>{@link HiveCalciteTableAdapter} for regular Hive tables</li>
+ * </ul>
+ *
+ * <p><b>Migration Path:</b>
+ * <ul>
+ *   <li><b>Legacy:</b> {@link HiveSchema} → {@link HiveDbSchema} (this class) → {@link HiveCalciteTableAdapter}</li>
+ *   <li><b>Modern:</b> {@link CoralRootSchema} → {@link CoralDatabaseSchema} → Format-specific adapters</li>
+ * </ul>
+ *
+ * <p><b>Future:</b> As part of <a href="https://github.com/linkedin/coral/issues/575">issue #575</a>,
+ * this class will be evaluated for deprecation/cleanup once all clients migrate to {@link CoralDatabaseSchema}
+ * and the {@link com.linkedin.coral.common.catalog.CoralCatalog} API.
+ *
+ * @see CoralDatabaseSchema Modern replacement with CoralCatalog integration
+ * @see HiveSchema Legacy root-level schema
+ * @see <a href="https://github.com/linkedin/coral/issues/575">Issue #575: Refactor ParseTreeBuilder to Use CoralTable</a>
  */
 public class HiveDbSchema implements Schema {
 
diff --git a/coral-common/src/main/java/com/linkedin/coral/common/HiveSchema.java b/coral-common/src/main/java/com/linkedin/coral/common/HiveSchema.java
@@ -27,8 +27,24 @@
  * to Calcite {@link Schema}. This class represents the "root" schema
  * that holds all hive databases as subschema and no tables.
  *
- * Can use either CoralCatalog for unified access to different table formats
- * or HiveMetastoreClient for Hive-specific access.
+ * <p><b>LEGACY API:</b> This class exists for backward compatibility with existing code
+ * that uses {@link HiveMetastoreClient} directly. For new code, prefer {@link CoralRootSchema}
+ * which integrates with the unified {@link com.linkedin.coral.common.catalog.CoralCatalog} API
+ * and supports multiple table formats (Hive, Iceberg, etc.) without Hive-specific coupling.
+ *
+ * <p><b>Migration Path:</b>
+ * <ul>
+ *   <li><b>Legacy:</b> {@link HiveSchema} (this class) → {@link HiveDbSchema} → {@link HiveCalciteTableAdapter}</li>
+ *   <li><b>Modern:</b> {@link CoralRootSchema} → {@link CoralDatabaseSchema} → Format-specific adapters</li>
+ * </ul>
+ *
+ * <p><b>Future:</b> As part of <a href="https://github.com/linkedin/coral/issues/575">issue #575</a>,
+ * this class will be evaluated for deprecation/cleanup once all clients migrate to {@link CoralRootSchema}
+ * and the {@link com.linkedin.coral.common.catalog.CoralCatalog} API.
+ *
+ * @see CoralRootSchema Modern replacement with CoralCatalog integration
+ * @see HiveDbSchema Legacy database-level schema
+ * @see <a href="https://github.com/linkedin/coral/issues/575">Issue #575: Refactor ParseTreeBuilder to Use CoralTable</a>
  */
 public class HiveSchema implements Schema {
 
diff --git a/coral-common/src/main/java/com/linkedin/coral/common/IcebergCalciteTableAdapter.java b/coral-common/src/main/java/com/linkedin/coral/common/IcebergCalciteTableAdapter.java
@@ -34,6 +34,20 @@
  *
  * <p>This class uses IcebergCoralTable to access Iceberg table metadata and converts
  * through the Coral type system for better abstraction and consistency with HiveCalciteTableAdapter.
+ *
+ * <p><b>Integration with ParseTreeBuilder and HiveFunctionResolver:</b> While this adapter itself
+ * doesn't provide Dali UDF methods, Iceberg tables with UDF metadata still need to work with
+ * {@code ParseTreeBuilder} and {@code HiveFunctionResolver}, which are currently tightly coupled to
+ * {@link org.apache.hadoop.hive.metastore.api.Table}. The temporary workaround is
+ * {@link com.linkedin.coral.common.catalog.IcebergHiveTableConverter}, which converts Iceberg tables
+ * to Hive Table objects for UDF resolution.
+ *
+ * <p>This coupling is being addressed in <a href="https://github.com/linkedin/coral/issues/575">issue #575</a>,
+ * which will refactor {@code ParseTreeBuilder} and {@code HiveFunctionResolver} to accept
+ * {@link com.linkedin.coral.common.catalog.CoralTable} instead, enabling direct Iceberg support without conversion.
+ *
+ * @see com.linkedin.coral.common.catalog.IcebergHiveTableConverter
+ * @see <a href="https://github.com/linkedin/coral/issues/575">Issue #575: Refactor ParseTreeBuilder to Use CoralTable</a>
  */
 public class IcebergCalciteTableAdapter implements ScannableTable {
 
diff --git a/coral-common/src/main/java/com/linkedin/coral/common/IcebergToCoralTypeConverter.java b/coral-common/src/main/java/com/linkedin/coral/common/IcebergToCoralTypeConverter.java
@@ -19,8 +19,9 @@
  * Converts Iceberg Schema and Types to Coral data types.
  * This is the first stage of the two-stage conversion: Iceberg → Coral → Calcite.
  *
- * Mirrors the structure of IcebergTypeConverter but converts to Coral types
- * instead of directly to Calcite RelDataType, enabling better type system abstraction.
+ * This converter provides a unified type system abstraction by converting Iceberg types
+ * to Coral's intermediate type representation, which can then be converted to Calcite
+ * RelDataType using {@link com.linkedin.coral.common.types.CoralTypeToRelDataTypeConverter}.
  */
 public class IcebergToCoralTypeConverter {
 
@@ -50,7 +51,6 @@ public static StructType convert(Schema icebergSchema) {
 
   /**
    * Main dispatcher - converts Iceberg Type to Coral CoralDataType based on type category.
-   * Similar to IcebergTypeConverter.convert(Type, RelDataTypeFactory).
    *
    * @param icebergType Iceberg type
    * @param nullable Whether this type instance is nullable
diff --git a/coral-common/src/main/java/com/linkedin/coral/common/IcebergTypeConverter.java b/coral-common/src/main/java/com/linkedin/coral/common/IcebergTypeConverter.java
diff --git a/coral-common/src/test/java/com/linkedin/coral/common/IcebergTypeConverterEquivalenceTest.java b/coral-common/src/test/java/com/linkedin/coral/common/IcebergTypeConverterEquivalenceTest.java
