Mark the PTF SPIs as Experimental

trinodb · Aug 3, 2022 · aed2d5b · aed2d5b
1 parent efe30ca
commit aed2d5b
Show file tree

Hide file tree

Showing 17 changed files with 52 additions and 10 deletions.
diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/AbstractConnectorTableFunction.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/AbstractConnectorTableFunction.java
@@ -13,6 +13,7 @@
  */
 package io.trino.spi.ptf;
 
+import io.trino.spi.Experimental;
 import io.trino.spi.connector.ConnectorSession;
 import io.trino.spi.connector.ConnectorTransactionHandle;
 
@@ -21,6 +22,7 @@
 
 import static java.util.Objects.requireNonNull;
 
+@Experimental(eta = "2022-10-31")
 public abstract class AbstractConnectorTableFunction
         implements ConnectorTableFunction
 {

diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/Argument.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/Argument.java
@@ -15,6 +15,7 @@
 
 import com.fasterxml.jackson.annotation.JsonSubTypes;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import io.trino.spi.Experimental;
 import io.trino.spi.expression.ConnectorExpression;
 
 /**
@@ -32,6 +33,7 @@
         @JsonSubTypes.Type(value = ScalarArgument.class, name = "scalar"),
         @JsonSubTypes.Type(value = TableArgument.class, name = "table"),
 })
+@Experimental(eta = "2022-10-31")
 public abstract class Argument
 {
 }
diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/ArgumentSpecification.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/ArgumentSpecification.java
@@ -13,6 +13,8 @@
  */
 package io.trino.spi.ptf;
 
+import io.trino.spi.Experimental;
+
 import javax.annotation.Nullable;
 
 import static io.trino.spi.ptf.Preconditions.checkArgument;
@@ -28,6 +30,7 @@
  * <p>
  * Default values are allowed for all arguments except Table arguments.
  */
+@Experimental(eta = "2022-10-31")
 public abstract class ArgumentSpecification
 {
     private final String name;

diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/ConnectorTableFunction.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/ConnectorTableFunction.java
@@ -13,12 +13,14 @@
  */
 package io.trino.spi.ptf;
 
+import io.trino.spi.Experimental;
 import io.trino.spi.connector.ConnectorSession;
 import io.trino.spi.connector.ConnectorTransactionHandle;
 
 import java.util.List;
 import java.util.Map;
 
+@Experimental(eta = "2022-10-31")
 public interface ConnectorTableFunction
 {
     String getSchema();

diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/ConnectorTableFunctionHandle.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/ConnectorTableFunctionHandle.java
@@ -13,9 +13,12 @@
  */
 package io.trino.spi.ptf;
 
+import io.trino.spi.Experimental;
+
 /**
  * An area to store all information necessary to execute the table function, gathered at analysis time
  */
+@Experimental(eta = "2022-10-31")
 public interface ConnectorTableFunctionHandle
 {
 }
diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/Descriptor.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/Descriptor.java
@@ -15,6 +15,7 @@
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import io.trino.spi.Experimental;
 import io.trino.spi.type.Type;
 
 import java.util.ArrayList;
@@ -27,6 +28,7 @@
 import static io.trino.spi.ptf.Preconditions.checkNotNullOrEmpty;
 import static java.util.Objects.requireNonNull;
 
+@Experimental(eta = "2022-10-31")
 public class Descriptor
 {
     private final List<Field> fields;

diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/DescriptorArgument.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/DescriptorArgument.java
@@ -15,6 +15,7 @@
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import io.trino.spi.Experimental;
 import io.trino.spi.expression.ConnectorExpression;
 
 import java.util.Optional;
@@ -27,6 +28,7 @@
  * This representation should be considered experimental. Eventually, {@link ConnectorExpression}
  * should be extended to include this kind of argument.
  */
+@Experimental(eta = "2022-10-31")
 public class DescriptorArgument
         extends Argument
 {

diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/DescriptorArgumentSpecification.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/DescriptorArgumentSpecification.java
@@ -13,6 +13,9 @@
  */
 package io.trino.spi.ptf;
 
+import io.trino.spi.Experimental;
+
+@Experimental(eta = "2022-10-31")
 public class DescriptorArgumentSpecification
         extends ArgumentSpecification
 {

diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/DescriptorMapping.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/DescriptorMapping.java
@@ -13,6 +13,8 @@
  */
 package io.trino.spi.ptf;
 
+import io.trino.spi.Experimental;
+
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.Map;
@@ -23,6 +25,7 @@
 import static java.lang.String.format;
 import static java.util.Objects.requireNonNull;
 
+@Experimental(eta = "2022-10-31")
 public class DescriptorMapping
 {
     public static final DescriptorMapping EMPTY_MAPPING = new DescriptorMappingBuilder().build();

diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/NameAndPosition.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/NameAndPosition.java
@@ -13,6 +13,8 @@
  */
 package io.trino.spi.ptf;
 
+import io.trino.spi.Experimental;
+
 import java.util.Objects;
 
 import static io.trino.spi.ptf.Preconditions.checkArgument;
@@ -27,6 +29,7 @@
  * The Table Function is supposed to refer to input data using `NameAndPosition`,
  * and the engine should provide the requested column.
  */
+@Experimental(eta = "2022-10-31")
 public class NameAndPosition
 {
     private final String name;

diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/ReturnTypeSpecification.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/ReturnTypeSpecification.java
@@ -13,6 +13,8 @@
  */
 package io.trino.spi.ptf;
 
+import io.trino.spi.Experimental;
+
 import static io.trino.spi.ptf.Preconditions.checkArgument;
 import static java.util.Objects.requireNonNull;
 
@@ -21,6 +23,7 @@
  * These are the columns produced by the table function as opposed to the columns
  * of input relations passed through by the table function.
  */
+@Experimental(eta = "2022-10-31")
 public abstract class ReturnTypeSpecification
 {
     /**

diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/ScalarArgument.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/ScalarArgument.java
@@ -15,6 +15,7 @@
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import io.trino.spi.Experimental;
 import io.trino.spi.expression.ConnectorExpression;
 import io.trino.spi.type.Type;
 
@@ -29,6 +30,7 @@
  * Additionally, only constant values are currently supported. In the future,
  * we will add support for different kinds of expressions.
  */
+@Experimental(eta = "2022-10-31")
 public class ScalarArgument
         extends Argument
 {

diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/ScalarArgumentSpecification.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/ScalarArgumentSpecification.java
@@ -13,12 +13,14 @@
  */
 package io.trino.spi.ptf;
 
+import io.trino.spi.Experimental;
 import io.trino.spi.type.Type;
 
 import static io.trino.spi.ptf.Preconditions.checkArgument;
 import static java.lang.String.format;
 import static java.util.Objects.requireNonNull;
 
+@Experimental(eta = "2022-10-31")
 public class ScalarArgumentSpecification
         extends ArgumentSpecification
 {

diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/TableArgument.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/TableArgument.java
@@ -15,6 +15,7 @@
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import io.trino.spi.Experimental;
 import io.trino.spi.expression.ConnectorExpression;
 import io.trino.spi.type.RowType;
 
@@ -30,6 +31,7 @@
  * This representation should be considered experimental. Eventually, {@link ConnectorExpression}
  * should be extended to include this kind of argument.
  */
+@Experimental(eta = "2022-10-31")
 public class TableArgument
         extends Argument
 {

diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/TableArgumentSpecification.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/TableArgumentSpecification.java
@@ -13,6 +13,9 @@
  */
 package io.trino.spi.ptf;
 
+import io.trino.spi.Experimental;
+
+@Experimental(eta = "2022-10-31")
 public class TableArgumentSpecification
         extends ArgumentSpecification
 {

diff --git a/core/trino-spi/src/main/java/io/trino/spi/ptf/TableFunctionAnalysis.java b/core/trino-spi/src/main/java/io/trino/spi/ptf/TableFunctionAnalysis.java
@@ -13,6 +13,8 @@
  */
 package io.trino.spi.ptf;
 
+import io.trino.spi.Experimental;
+
 import java.util.Optional;
 
 import static io.trino.spi.ptf.DescriptorMapping.EMPTY_MAPPING;
@@ -37,6 +39,7 @@
  * gathered at analysis time. Typically, these are the values of the constant arguments, and results
  * of pre-processing arguments.
  */
+@Experimental(eta = "2022-10-31")
 public final class TableFunctionAnalysis
 {
     private final Optional<Descriptor> returnedType;

diff --git a/core/trino-spi/src/test/java/io/trino/spi/TestSpiBackwardCompatibility.java b/core/trino-spi/src/test/java/io/trino/spi/TestSpiBackwardCompatibility.java
@@ -59,22 +59,12 @@ public class TestSpiBackwardCompatibility
             // example
             .put("123", "Field: public java.util.List<io.trino.spi.predicate.Range> io.trino.spi.predicate.BenchmarkSortedRangeSet$Data.ranges")
             .put("377", "Constructor: public io.trino.spi.memory.MemoryPoolInfo(long,long,long,java.util.Map<io.trino.spi.QueryId, java.lang.Long>,java.util.Map<io.trino.spi.QueryId, java.util.List<io.trino.spi.memory.MemoryAllocation>>,java.util.Map<io.trino.spi.QueryId, java.lang.Long>)")
-            .put("382", "Method: public io.trino.spi.ptf.TableArgumentSpecification$Builder io.trino.spi.ptf.TableArgumentSpecification$Builder.rowSemantics(boolean)")
-            .put("382", "Method: public io.trino.spi.ptf.TableArgumentSpecification$Builder io.trino.spi.ptf.TableArgumentSpecification$Builder.pruneWhenEmpty(boolean)")
-            .put("382", "Method: public io.trino.spi.ptf.TableArgumentSpecification$Builder io.trino.spi.ptf.TableArgumentSpecification$Builder.passThroughColumns(boolean)")
-            .put("382", "Class: public abstract class io.trino.spi.ptf.ConnectorTableFunction")
-            .put("382", "Constructor: public io.trino.spi.ptf.ConnectorTableFunction(java.lang.String,java.lang.String,java.util.List<io.trino.spi.ptf.ArgumentSpecification>,io.trino.spi.ptf.ReturnTypeSpecification)")
-            .put("382", "Method: public java.util.List<io.trino.spi.ptf.ArgumentSpecification> io.trino.spi.ptf.ConnectorTableFunction.getArguments()")
-            .put("382", "Method: public io.trino.spi.ptf.ReturnTypeSpecification io.trino.spi.ptf.ConnectorTableFunction.getReturnTypeSpecification()")
-            .put("382", "Method: public java.lang.String io.trino.spi.ptf.ConnectorTableFunction.getName()")
-            .put("382", "Method: public java.lang.String io.trino.spi.ptf.ConnectorTableFunction.getSchema()")
             .put("383", "Method: public abstract java.lang.String io.trino.spi.function.AggregationState.value()")
             .put("383", "Method: public default void io.trino.spi.security.SystemAccessControl.checkCanExecuteFunction(io.trino.spi.security.SystemSecurityContext,io.trino.spi.connector.CatalogSchemaRoutineName)")
             .put("383", "Method: public default void io.trino.spi.connector.ConnectorAccessControl.checkCanExecuteFunction(io.trino.spi.connector.ConnectorSecurityContext,io.trino.spi.connector.SchemaRoutineName)")
             .put("384", "Constructor: public io.trino.spi.eventlistener.QueryInputMetadata(java.lang.String,java.lang.String,java.lang.String,java.util.List<java.lang.String>,java.util.Optional<java.lang.Object>,java.util.OptionalLong,java.util.OptionalLong)")
             .put("386", "Method: public default java.util.stream.Stream<io.trino.spi.connector.TableColumnsMetadata> io.trino.spi.connector.ConnectorMetadata.streamTableColumns(io.trino.spi.connector.ConnectorSession,io.trino.spi.connector.SchemaTablePrefix)")
             .put("386", "Method: public default boolean io.trino.spi.connector.ConnectorMetadata.isSupportedVersionType(io.trino.spi.connector.ConnectorSession,io.trino.spi.connector.SchemaTableName,io.trino.spi.connector.PointerType,io.trino.spi.type.Type)")
-            .put("386", "Method: public static io.trino.spi.ptf.TableArgumentSpecification$Builder io.trino.spi.ptf.TableArgumentSpecification.builder(java.lang.String)")
             .put("387", "Constructor: public io.trino.spi.eventlistener.QueryContext(java.lang.String,java.util.Optional<java.lang.String>,java.util.Set<java.lang.String>,java.util.Optional<java.lang.String>,java.util.Optional<java.lang.String>,java.util.Optional<java.lang.String>,java.util.Optional<java.lang.String>,java.util.Set<java.lang.String>,java.util.Set<java.lang.String>,java.util.Optional<java.lang.String>,java.util.Optional<java.lang.String>,java.util.Optional<java.lang.String>,java.util.Optional<io.trino.spi.resourcegroups.ResourceGroupId>,java.util.Map<java.lang.String, java.lang.String>,io.trino.spi.session.ResourceEstimates,java.lang.String,java.lang.String,java.lang.String,java.util.Optional<io.trino.spi.resourcegroups.QueryType>)")
             .put("388", "Method: public abstract java.util.concurrent.CompletableFuture<io.trino.spi.connector.ConnectorSplitSource$ConnectorSplitBatch> io.trino.spi.connector.ConnectorSplitSource.getNextBatch(io.trino.spi.connector.ConnectorPartitionHandle,int)")
             .put("388", "Method: public java.util.concurrent.CompletableFuture<io.trino.spi.connector.ConnectorSplitSource$ConnectorSplitBatch> io.trino.spi.connector.FixedSplitSource.getNextBatch(io.trino.spi.connector.ConnectorPartitionHandle,int)")
@@ -152,6 +142,12 @@ private static void addClassEntities(ImmutableSet.Builder<String> entities, Clas
         if (!isPublic(clazz.getModifiers())) {
             return;
         }
+
+        // TODO remove this after Experimental is released
+        if (isOriginalPtfClass(clazz, includeDeprecated)) {
+            return;
+        }
+
         for (Class<?> nestedClass : clazz.getDeclaredClasses()) {
             addClassEntities(entities, nestedClass, includeDeprecated);
         }
@@ -210,4 +206,10 @@ private static boolean isExperimental(AnnotatedElement element, String descripti
         }
         return true;
     }
+
+    // TODO remove this after Experimental is released
+    private static boolean isOriginalPtfClass(Class<?> clazz, boolean includeDeprecated)
+    {
+        return !includeDeprecated && clazz.getName().startsWith("io.trino.spi.ptf.");
+    }
 }