[Kernel] Add @Evolving and @since tags to all the Kernel API interfaces

kernel/kernel-api/src/main/java/io/delta/kernel/Scan.java

@@ -22,6 +22,7 @@
 import java.util.Optional;
 import java.util.Set;
 
+import io.delta.kernel.annotation.Evolving;
 import io.delta.kernel.client.FileReadContext;
 import io.delta.kernel.client.ParquetHandler;
 import io.delta.kernel.client.TableClient;
@@ -48,7 +49,10 @@
 
 /**
  * Represents a scan of a Delta table.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface Scan {
     /**
      * Get an iterator of data files to scan.

kernel/kernel-api/src/main/java/io/delta/kernel/ScanBuilder.java

@@ -16,13 +16,17 @@
 
 package io.delta.kernel;
 
+import io.delta.kernel.annotation.Evolving;
 import io.delta.kernel.client.TableClient;
 import io.delta.kernel.expressions.Expression;
 import io.delta.kernel.types.StructType;
 
 /**
  * Builder to construct {@link Scan} object.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface ScanBuilder {
 
     /**

kernel/kernel-api/src/main/java/io/delta/kernel/Snapshot.java

@@ -16,12 +16,16 @@
 
 package io.delta.kernel;
 
+import io.delta.kernel.annotation.Evolving;
 import io.delta.kernel.client.TableClient;
 import io.delta.kernel.types.StructType;
 
 /**
  * Represents the snapshot of a Delta table.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface Snapshot {
 
     /**

kernel/kernel-api/src/main/java/io/delta/kernel/Table.java

@@ -15,13 +15,17 @@
  */
 package io.delta.kernel;
 
+import io.delta.kernel.annotation.Evolving;
 import io.delta.kernel.client.TableClient;
 
 import io.delta.kernel.internal.TableImpl;
 
 /**
  * Represents the Delta Lake table for a given path.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface Table {
     /**
      * Instantiate a table object for the Delta Lake table at the given path.

kernel/kernel-api/src/main/java/io/delta/kernel/TableNotFoundException.java

@@ -16,9 +16,14 @@
 
 package io.delta.kernel;
 
+import io.delta.kernel.annotation.Evolving;
+
 /**
  * Thrown when there is no Delta table at the given location.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public class TableNotFoundException
     extends Exception {
 }

kernel/kernel-api/src/main/java/io/delta/kernel/annotation/Evolving.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright (2023) The Delta Lake Project Authors.
+ *
+ * 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.delta.kernel.annotation;
+
+import java.lang.annotation.*;
+
+/**
+ * APIs that are meant to evolve towards becoming stable APIs, but are not stable APIs yet.
+ * Evolving interfaces can change from one feature release to another release (i.e. 3.0 to 3.1).
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER,
+    ElementType.CONSTRUCTOR, ElementType.LOCAL_VARIABLE, ElementType.PACKAGE})
+public @interface Evolving {}

kernel/kernel-api/src/main/java/io/delta/kernel/client/ExpressionHandler.java

@@ -16,6 +16,7 @@
 
 package io.delta.kernel.client;
 
+import io.delta.kernel.annotation.Evolving;
 import io.delta.kernel.expressions.Expression;
 import io.delta.kernel.expressions.ExpressionEvaluator;
 import io.delta.kernel.types.StructType;
@@ -24,7 +25,10 @@
  * Provides expression evaluation capability to Delta Kernel. Delta Kernel can use this client
  * to evaluate predicate on partition filters, fill up partition column values and any computation
  * on data using {@link Expression}s.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface ExpressionHandler {
     /**
      * Create an {@link ExpressionEvaluator} that can evaluate the given <i>expression</i> on

kernel/kernel-api/src/main/java/io/delta/kernel/client/FileHandler.java

@@ -16,6 +16,7 @@
 
 package io.delta.kernel.client;
 
+import io.delta.kernel.annotation.Evolving;
 import io.delta.kernel.data.Row;
 import io.delta.kernel.expressions.Expression;
 import io.delta.kernel.fs.FileStatus;
@@ -25,7 +26,10 @@
  * Provides file handling functionality to Delta Kernel. Connectors can implement this client to
  * provide Delta Kernel their own custom implementation of file splitting, additional predicate
  * pushdown or any other connector-specific capabilities.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface FileHandler {
     /**
      * Associates a connector specific {@link FileReadContext} for each scan file represented by a

kernel/kernel-api/src/main/java/io/delta/kernel/client/FileReadContext.java

@@ -16,13 +16,17 @@
 
 package io.delta.kernel.client;
 
+import io.delta.kernel.annotation.Evolving;
 import io.delta.kernel.data.Row;
 
 /**
  * Placeholder interface allowing connectors to attach their own custom implementation. Connectors
  * can use this to pass additional context about a scan file through Delta Kernel and back to the
  * connector for interpretation.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface FileReadContext {
     /**
      * Get the scan file info associated with the read context.

kernel/kernel-api/src/main/java/io/delta/kernel/client/FileSystemClient.java

@@ -20,6 +20,7 @@
 import java.io.FileNotFoundException;
 import java.io.IOException;
 
+import io.delta.kernel.annotation.Evolving;
 import io.delta.kernel.fs.FileStatus;
 import io.delta.kernel.utils.CloseableIterator;
 import io.delta.kernel.utils.Tuple2;
@@ -29,7 +30,10 @@
  * whenever it needs to access the underlying file system where the Delta table is present.
  * Connector implementation of this interface can hide filesystem specific details from Delta
  * Kernel.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface FileSystemClient {
     /**
      * List the paths in the same directory that are lexicographically greater or equal to

kernel/kernel-api/src/main/java/io/delta/kernel/client/JsonHandler.java

@@ -18,6 +18,7 @@
 
 import java.io.IOException;
 
+import io.delta.kernel.annotation.Evolving;
 import io.delta.kernel.data.ColumnVector;
 import io.delta.kernel.data.ColumnarBatch;
 import io.delta.kernel.data.FileDataReadResult;
@@ -29,9 +30,11 @@
  * Provides JSON handling functionality to Delta Kernel. Delta Kernel can use this client to
  * parse JSON strings into {@link io.delta.kernel.data.Row} or read content from JSON files.
  * Connectors can leverage this interface to provide their best implementation of the JSON parsing
- * capability to
- * Delta Kernel.
+ * capability to Delta Kernel.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface JsonHandler
     extends FileHandler {
     /**

kernel/kernel-api/src/main/java/io/delta/kernel/client/ParquetHandler.java

@@ -18,6 +18,7 @@
 
 import java.io.IOException;
 
+import io.delta.kernel.annotation.Evolving;
 import io.delta.kernel.data.ColumnarBatch;
 import io.delta.kernel.data.FileDataReadResult;
 import io.delta.kernel.types.StructField;
@@ -28,7 +29,10 @@
  * Provides Parquet file related functionalities to Delta Kernel. Connectors can leverage this
  * interface to provide their own custom implementation of Parquet data file functionalities to
  * Delta Kernel.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface ParquetHandler
     extends FileHandler {
     /**

kernel/kernel-api/src/main/java/io/delta/kernel/client/TableClient.java

@@ -16,11 +16,16 @@
 
 package io.delta.kernel.client;
 
+import io.delta.kernel.annotation.Evolving;
+
 /**
  * Interface encapsulating all clients needed by the Delta Kernel in order to read the
  * Delta table. Connectors are expected to pass an implementation of this interface when reading
  * a Delta table.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface TableClient {
 
     /**

kernel/kernel-api/src/main/java/io/delta/kernel/data/ColumnVector.java

@@ -20,11 +20,15 @@
 import java.util.List;
 import java.util.Map;
 
+import io.delta.kernel.annotation.Evolving;
 import io.delta.kernel.types.DataType;
 
 /**
  * Represents zero or more values of a single column.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface ColumnVector extends AutoCloseable {
     /**
      * @return the data type of this column vector.

kernel/kernel-api/src/main/java/io/delta/kernel/data/ColumnarBatch.java

@@ -16,6 +16,7 @@
 
 package io.delta.kernel.data;
 
+import io.delta.kernel.annotation.Evolving;
 import io.delta.kernel.types.StructField;
 import io.delta.kernel.types.StructType;
 import io.delta.kernel.utils.CloseableIterator;
@@ -24,7 +25,10 @@
 
 /**
  * Represents zero or more rows of records with same schema type.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface ColumnarBatch {
     /**
      * @return the schema of the data in this batch.

kernel/kernel-api/src/main/java/io/delta/kernel/data/DataReadResult.java

@@ -18,6 +18,8 @@
 
 import java.util.Optional;
 
+import io.delta.kernel.annotation.Evolving;
+
 /**
  * Data read from Delta table file. Data is in {@link ColumnarBatch} format with an optional
  * selection vector to select only a subset of rows for this columnar batch.
@@ -26,7 +28,10 @@
  * {@link ColumnarBatch}. For each row index, a value of true in the selection vector indicates
  * the row at the same index in the data {@link ColumnarBatch} is valid; a value of false
  * indicates the row should be ignored. If there is no selection vector then all the rows are valid.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public class DataReadResult {
     private final ColumnarBatch data;
     private final Optional<ColumnVector> selectionVector;

kernel/kernel-api/src/main/java/io/delta/kernel/data/FileDataReadResult.java

@@ -16,10 +16,14 @@
 
 package io.delta.kernel.data;
 
+import io.delta.kernel.annotation.Evolving;
 
 /**
  * Data read from a Delta table file and the corresponding scan file information.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface FileDataReadResult {
     /**
      * Get the data read from the file.

kernel/kernel-api/src/main/java/io/delta/kernel/data/Row.java

@@ -20,11 +20,15 @@
 import java.util.List;
 import java.util.Map;
 
+import io.delta.kernel.annotation.Evolving;
 import io.delta.kernel.types.StructType;
 
 /**
  * Represent a single record
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface Row {
 
     /**

kernel/kernel-api/src/main/java/io/delta/kernel/expressions/ExpressionEvaluator.java

@@ -16,6 +16,7 @@
 
 package io.delta.kernel.expressions;
 
+import io.delta.kernel.annotation.Evolving;
 import io.delta.kernel.data.ColumnVector;
 import io.delta.kernel.data.ColumnarBatch;
 
@@ -24,7 +25,10 @@
  * It contains one {@link Expression} which can be evaluated on multiple {@link ColumnarBatch}es
  * Connectors can implement this interface to optimize the evaluation using the
  * connector specific capabilities.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public interface ExpressionEvaluator extends AutoCloseable {
     /**
      * Evaluate the expression on given {@link ColumnarBatch} data.

kernel/kernel-api/src/main/java/io/delta/kernel/fs/FileStatus.java

@@ -18,11 +18,15 @@
 
 import java.util.Objects;
 
+import io.delta.kernel.annotation.Evolving;
+
 /**
  * Class for encapsulating metadata about a file in Delta Lake table.
+ *
+ * @since 3.0.0
  */
+@Evolving
 public class FileStatus {
-
     private final String path;
     private final long size;
     private final long modificationTime;
@@ -66,8 +70,8 @@ public long getModificationTime() {
     /**
      * Create a {@link FileStatus} with the given path, size and modification time.
      *
-     * @param path             Fully qualified file path.
-     * @param size             File size in bytes
+     * @param path Fully qualified file path.
+     * @param size File size in bytes
      * @param modificationTime Modification time of the file in epoch millis
      */
     public static FileStatus of(String path, long size, long modificationTime) {

kernel/kernel-api/src/main/java/io/delta/kernel/types/ArrayType.java

@@ -18,6 +18,14 @@
 
 import java.util.Objects;
 
+import io.delta.kernel.annotation.Evolving;
+
+/**
+ * Represent {@code array} data type
+ *
+ * @since 3.0.0
+ */
+@Evolving
 public class ArrayType extends DataType {
     private final DataType elementType;
     private final boolean containsNull;