Add Experimental annotation to SPI

The Experimental annotation designates part of the SPI that is still
under development and is considered experimental. Experimental SPIs may
be changed at any time and maybe removed. The date in the annotation
signifies when the community believes the SPI will be finalized, but
this date may be extended.

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/test/java/io/trino/spi/TestSpiBackwardCompatibility.java

@@ -22,6 +22,7 @@
 import org.testng.annotations.Test;
 
 import java.io.IOException;
+import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Constructor;
 import java.lang.reflect.Field;
 import java.lang.reflect.Method;
@@ -30,13 +31,16 @@
 import java.net.URLClassLoader;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.time.LocalDate;
+import java.time.format.DateTimeParseException;
 import java.util.Set;
 import java.util.stream.Stream;
 
 import static com.google.common.collect.ImmutableSet.toImmutableSet;
 import static com.google.common.collect.Sets.difference;
 import static java.lang.ClassLoader.getPlatformClassLoader;
 import static java.lang.ClassLoader.getSystemClassLoader;
+import static java.lang.String.format;
 import static java.lang.reflect.Modifier.isPublic;
 import static org.assertj.core.api.Assertions.assertThat;
 
@@ -141,6 +145,10 @@ private static Set<String> getSpiEntities(ClassLoader classLoader, boolean inclu
 
     private static void addClassEntities(ImmutableSet.Builder<String> entities, Class<?> clazz, boolean includeDeprecated)
     {
+        if (isExperimental(clazz, "class " + clazz.getName())) {
+            return;
+        }
+
         if (!isPublic(clazz.getModifiers())) {
             return;
         }
@@ -152,12 +160,18 @@ private static void addClassEntities(ImmutableSet.Builder<String> entities, Clas
         }
         entities.add("Class: " + clazz.toGenericString());
         for (Constructor<?> constructor : clazz.getConstructors()) {
+            if (isExperimental(constructor, "constructor " + constructor)) {
+                continue;
+            }
             if (!includeDeprecated && constructor.isAnnotationPresent(Deprecated.class)) {
                 continue;
             }
             entities.add("Constructor: " + constructor.toGenericString());
         }
         for (Method method : clazz.getDeclaredMethods()) {
+            if (isExperimental(method, "method " + method)) {
+                continue;
+            }
             if (!isPublic(method.getModifiers())) {
                 continue;
             }
@@ -167,6 +181,9 @@ private static void addClassEntities(ImmutableSet.Builder<String> entities, Clas
             entities.add("Method: " + method.toGenericString());
         }
         for (Field field : clazz.getDeclaredFields()) {
+            if (isExperimental(field, "field " + field)) {
+                continue;
+            }
             if (!isPublic(field.getModifiers())) {
                 continue;
             }
@@ -176,4 +193,21 @@ private static void addClassEntities(ImmutableSet.Builder<String> entities, Clas
             entities.add("Field: " + field.toGenericString());
         }
     }
+
+    private static boolean isExperimental(AnnotatedElement element, String description)
+    {
+        if (!element.isAnnotationPresent(Experimental.class)) {
+            return false;
+        }
+
+        // validate the annotation while we have access to the annotation
+        String date = element.getAnnotation(Experimental.class).eta();
+        try {
+            LocalDate.parse(date);
+        }
+        catch (DateTimeParseException e) {
+            throw new AssertionError(format("Invalid date '%s' in Experimental annotation on %s", date, description));
+        }
+        return true;
+    }
 }