Experimental SPI annotation

core/trino-spi/src/main/java/io/trino/spi/Experimental.java

@@ -0,0 +1,40 @@
+/*
+ * Licensed 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 io.trino.spi;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.CONSTRUCTOR;
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Signifies that a public API (public class, method or field) is subject to incompatible changes,
+ * or even removal, in a future release. An API bearing this annotation is exempt from any
+ * compatibility guarantees made by its containing library. Note that the presence of this
+ * annotation implies nothing about the quality or performance of the API in question, only the fact
+ * that it has not been finalized.
+ */
+@Retention(RUNTIME)
+@Target({TYPE, FIELD, METHOD, CONSTRUCTOR})
+public @interface Experimental
+{
+    /**
+     * When the community expects the SPI will be finalized, but this date may be extended.
+     */
+    String eta();
+}

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
 {

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
 {
 }

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;

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();

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
 {
 }

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;

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
 {

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
 {

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();

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;

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
 {
     /**

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
 {

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
 {

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
 {

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
 {

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;