[CALCITE-4914] Introduce HandlerBasedRelMetdataQuery as an extension point

core/src/main/java/org/apache/calcite/rel/metadata/HandlerBasedRelMetadataQuery.java

@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.calcite.rel.metadata;
+
+/**
+ * A RelMetadataQuery implementation built on the use {@link MetadataHandler} implementations.
+ *
+ * <p>Prior extenders of RelMetadataQuery that want to rely on handler behavior should now
+ * extend from this class.
+ */
+public class HandlerBasedRelMetadataQuery extends RelMetadataQuery {
+
+  /**
+   * Creates the instance with {@link JaninoRelMetadataProvider} instance
+   * from {@link #THREAD_PROVIDERS} and an empty prototype.
+   */
+  @SuppressWarnings("deprecation")
+  public HandlerBasedRelMetadataQuery() {
+  }
+}

core/src/main/java/org/apache/calcite/rel/metadata/RelMetadataQuery.java

@@ -33,6 +33,7 @@
 import com.google.common.collect.Iterables;
 import com.google.common.collect.Multimap;
 
+import org.checkerframework.checker.initialization.qual.UnderInitialization;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 import java.util.Collections;
@@ -109,7 +110,10 @@ public class RelMetadataQuery extends RelMetadataQueryBase {
   /**
    * Creates the instance with {@link JaninoRelMetadataProvider} instance
    * from {@link #THREAD_PROVIDERS} and {@link #EMPTY} as a prototype.
+   *
+   * @deprecated Use HandlerBasedRelMetadataQuery instead.
    */
+  @Deprecated // to be removed before 1.30
   protected RelMetadataQuery() {
     this(castNonNull(THREAD_PROVIDERS.get()), EMPTY);
   }
@@ -118,31 +122,37 @@ protected RelMetadataQuery() {
    * all other instances. */
   private RelMetadataQuery(@SuppressWarnings("unused") boolean dummy) {
     super(null);
-    this.collationHandler = initialHandler(BuiltInMetadata.Collation.Handler.class);
-    this.columnOriginHandler = initialHandler(BuiltInMetadata.ColumnOrigin.Handler.class);
-    this.expressionLineageHandler = initialHandler(BuiltInMetadata.ExpressionLineage.Handler.class);
-    this.tableReferencesHandler = initialHandler(BuiltInMetadata.TableReferences.Handler.class);
-    this.columnUniquenessHandler = initialHandler(BuiltInMetadata.ColumnUniqueness.Handler.class);
-    this.cumulativeCostHandler = initialHandler(BuiltInMetadata.CumulativeCost.Handler.class);
-    this.distinctRowCountHandler = initialHandler(BuiltInMetadata.DistinctRowCount.Handler.class);
-    this.distributionHandler = initialHandler(BuiltInMetadata.Distribution.Handler.class);
-    this.explainVisibilityHandler = initialHandler(BuiltInMetadata.ExplainVisibility.Handler.class);
-    this.maxRowCountHandler = initialHandler(BuiltInMetadata.MaxRowCount.Handler.class);
-    this.minRowCountHandler = initialHandler(BuiltInMetadata.MinRowCount.Handler.class);
-    this.memoryHandler = initialHandler(BuiltInMetadata.Memory.Handler.class);
-    this.nonCumulativeCostHandler = initialHandler(BuiltInMetadata.NonCumulativeCost.Handler.class);
-    this.parallelismHandler = initialHandler(BuiltInMetadata.Parallelism.Handler.class);
+    this.collationHandler = createInitialHandler(BuiltInMetadata.Collation.Handler.class);
+    this.columnOriginHandler = createInitialHandler(BuiltInMetadata.ColumnOrigin.Handler.class);
+    this.expressionLineageHandler =
+        createInitialHandler(BuiltInMetadata.ExpressionLineage.Handler.class);
+    this.tableReferencesHandler =
+        createInitialHandler(BuiltInMetadata.TableReferences.Handler.class);
+    this.columnUniquenessHandler =
+        createInitialHandler(BuiltInMetadata.ColumnUniqueness.Handler.class);
+    this.cumulativeCostHandler = createInitialHandler(BuiltInMetadata.CumulativeCost.Handler.class);
+    this.distinctRowCountHandler =
+        createInitialHandler(BuiltInMetadata.DistinctRowCount.Handler.class);
+    this.distributionHandler = createInitialHandler(BuiltInMetadata.Distribution.Handler.class);
+    this.explainVisibilityHandler =
+        createInitialHandler(BuiltInMetadata.ExplainVisibility.Handler.class);
+    this.maxRowCountHandler = createInitialHandler(BuiltInMetadata.MaxRowCount.Handler.class);
+    this.minRowCountHandler = createInitialHandler(BuiltInMetadata.MinRowCount.Handler.class);
+    this.memoryHandler = createInitialHandler(BuiltInMetadata.Memory.Handler.class);
+    this.nonCumulativeCostHandler =
+        createInitialHandler(BuiltInMetadata.NonCumulativeCost.Handler.class);
+    this.parallelismHandler = createInitialHandler(BuiltInMetadata.Parallelism.Handler.class);
     this.percentageOriginalRowsHandler =
-        initialHandler(BuiltInMetadata.PercentageOriginalRows.Handler.class);
-    this.populationSizeHandler = initialHandler(BuiltInMetadata.PopulationSize.Handler.class);
-    this.predicatesHandler = initialHandler(BuiltInMetadata.Predicates.Handler.class);
-    this.allPredicatesHandler = initialHandler(BuiltInMetadata.AllPredicates.Handler.class);
-    this.nodeTypesHandler = initialHandler(BuiltInMetadata.NodeTypes.Handler.class);
-    this.rowCountHandler = initialHandler(BuiltInMetadata.RowCount.Handler.class);
-    this.selectivityHandler = initialHandler(BuiltInMetadata.Selectivity.Handler.class);
-    this.sizeHandler = initialHandler(BuiltInMetadata.Size.Handler.class);
-    this.uniqueKeysHandler = initialHandler(BuiltInMetadata.UniqueKeys.Handler.class);
-    this.lowerBoundCostHandler = initialHandler(BuiltInMetadata.LowerBoundCost.Handler.class);
+        createInitialHandler(BuiltInMetadata.PercentageOriginalRows.Handler.class);
+    this.populationSizeHandler = createInitialHandler(BuiltInMetadata.PopulationSize.Handler.class);
+    this.predicatesHandler = createInitialHandler(BuiltInMetadata.Predicates.Handler.class);
+    this.allPredicatesHandler = createInitialHandler(BuiltInMetadata.AllPredicates.Handler.class);
+    this.nodeTypesHandler = createInitialHandler(BuiltInMetadata.NodeTypes.Handler.class);
+    this.rowCountHandler = createInitialHandler(BuiltInMetadata.RowCount.Handler.class);
+    this.selectivityHandler = createInitialHandler(BuiltInMetadata.Selectivity.Handler.class);
+    this.sizeHandler = createInitialHandler(BuiltInMetadata.Size.Handler.class);
+    this.uniqueKeysHandler = createInitialHandler(BuiltInMetadata.UniqueKeys.Handler.class);
+    this.lowerBoundCostHandler = createInitialHandler(BuiltInMetadata.LowerBoundCost.Handler.class);
   }
 
   private RelMetadataQuery(JaninoRelMetadataProvider metadataProvider,
@@ -203,6 +213,14 @@ public static RelMetadataQuery instance() {
     }
   }
 
+
+  @SuppressWarnings("deprecation")
+  protected <H> H createInitialHandler(
+      @UnderInitialization RelMetadataQuery this,
+      Class<H> handlerClass) {
+    return initialHandler(handlerClass);
+  }
+
   /**
    * Returns the
    * {@link BuiltInMetadata.RowCount#getRowCount()}
@@ -892,4 +910,5 @@ public Boolean isVisibleInExplain(RelNode rel,
       }
     }
   }
+
 }

core/src/main/java/org/apache/calcite/rel/metadata/RelMetadataQueryBase.java

@@ -21,6 +21,7 @@
 import com.google.common.collect.HashBasedTable;
 import com.google.common.collect.Table;
 
+import org.apiguardian.api.API;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 import java.lang.reflect.Proxy;
@@ -30,14 +31,14 @@
 import static java.util.Objects.requireNonNull;
 
 /**
- * Base class for the RelMetadataQuery that uses the metadata handler class
+ * Base class for the HandlerBasedRelMetadataQuery that uses the metadata handler class
  * generated by the Janino.
  *
  * <p>To add a new implementation to this interface, follow
  * these steps:
  *
  * <ol>
- * <li>Extends {@link RelMetadataQuery} (name it MyRelMetadataQuery for example)
+ * <li>Extends {@link HandlerBasedRelMetadataQuery} (name it MyRelMetadataQuery for example)
  * to reuse the Calcite builtin metadata query interfaces. In this class, define all the
  * extended Handlers for your metadata and implement the metadata query interfaces.
  * <li>Write your customized provider class <code>RelMdXyz</code>. Follow
@@ -64,13 +65,42 @@
 public class RelMetadataQueryBase {
   //~ Instance fields --------------------------------------------------------
 
-  /** Set of active metadata queries, and cache of previous results. */
+  /**
+   * Set of active metadata queries, and cache of previous results.
+   *
+   * <p>Exposed due to the way Janino visibility challeneges, will not be exposed on
+   * RelMetadataQuery directly in the future. Will only be exposed on this object and
+   * {@link HandlerBasedRelMetadataQuery} in the future.
+   *
+   * <p>Marked API.Status.INTERNAL since 1.29
+   */
+  @API(status = API.Status.INTERNAL)
   public final Table<RelNode, Object, Object> map = HashBasedTable.create();
 
+  /**
+   * Thread local Janino based provider.
+   *
+   * <p>Exposed due to the way Janino visibility challeneges, will not be exposed on
+   * RelMetadataQuery directly in the future. Will only be exposed on this object and
+   * {@link HandlerBasedRelMetadataQuery} in the future.
+   *
+   * <p>Marked API.Status.INTERNAL since 1.29
+   */
+  @API(status = API.Status.INTERNAL)
   public final @Nullable JaninoRelMetadataProvider metadataProvider;
 
   //~ Static fields/initializers ---------------------------------------------
 
+  /**
+   * Thread local Janino based provider.
+   *
+   * <p>Exposed due to the way Janino visibility challeneges, will not be exposed on
+   * RelMetadataQuery directly in the future. Will only be exposed on this object and
+   * {@link HandlerBasedRelMetadataQuery} in the future.
+   *
+   * <p>Marked API.Status.INTERNAL since 1.29
+   */
+  @API(status = API.Status.INTERNAL)
   public static final ThreadLocal<@Nullable JaninoRelMetadataProvider> THREAD_PROVIDERS =
       new ThreadLocal<>();
 
@@ -80,6 +110,12 @@ protected RelMetadataQueryBase(@Nullable JaninoRelMetadataProvider metadataProvi
     this.metadataProvider = metadataProvider;
   }
 
+  /**
+   * Create an initial handler for the provided handler class.
+   *
+   * @deprecated Use {@link HandlerBasedRelMetadataQuery#createInitialHandler}.
+   */
+  @Deprecated // to be removed before 1.30
   protected static <H> H initialHandler(Class<H> handlerClass) {
     return handlerClass.cast(
         Proxy.newProxyInstance(RelMetadataQuery.class.getClassLoader(),

core/src/test/java/org/apache/calcite/test/RelMetadataTest.java

@@ -68,6 +68,7 @@
 import org.apache.calcite.rel.metadata.BuiltInMetadata;
 import org.apache.calcite.rel.metadata.ChainedRelMetadataProvider;
 import org.apache.calcite.rel.metadata.DefaultRelMetadataProvider;
+import org.apache.calcite.rel.metadata.HandlerBasedRelMetadataQuery;
 import org.apache.calcite.rel.metadata.JaninoRelMetadataProvider;
 import org.apache.calcite.rel.metadata.Metadata;
 import org.apache.calcite.rel.metadata.MetadataDef;
@@ -3540,11 +3541,11 @@ public static class BrokenColTypeImpl extends PartialColTypeImpl {
   /** Extension to {@link RelMetadataQuery} to support {@link ColType}.
    *
    * <p>Illustrates how you would package up a user-defined metadata type. */
-  private static class MyRelMetadataQuery extends RelMetadataQuery {
+  private static class MyRelMetadataQuery extends HandlerBasedRelMetadataQuery {
     private ColType.Handler colTypeHandler;
 
     MyRelMetadataQuery() {
-      colTypeHandler = initialHandler(ColType.Handler.class);
+      colTypeHandler = createInitialHandler(ColType.Handler.class);
     }
 
     public String colType(RelNode rel, int column) {