[Kernel] [CC Refactor #1] Add ConfigurationProvider, TableIdentifier, TableBuilder APIs

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

@@ -20,7 +20,7 @@
 import io.delta.kernel.exceptions.CheckpointAlreadyExistsException;
 import io.delta.kernel.exceptions.KernelException;
 import io.delta.kernel.exceptions.TableNotFoundException;
-import io.delta.kernel.internal.TableImpl;
+import io.delta.kernel.internal.TableBuilderImpl;
 import java.io.IOException;
 
 /**
@@ -33,28 +33,29 @@ public interface Table {
   /**
    * Instantiate a table object for the Delta Lake table at the given path.
    *
-   * <ul>
-   *   <li>Behavior when the table location doesn't exist:
-   *       <ul>
-   *         <li>Reads will fail with a {@link TableNotFoundException}
-   *         <li>Writes will create the location
-   *       </ul>
-   *   <li>Behavior when the table location exists (with contents or not) but not a Delta table:
-   *       <ul>
-   *         <li>Reads will fail with a {@link TableNotFoundException}
-   *         <li>Writes will create a Delta table at the given location. If there are any existing
-   *             files in the location that are not already part of the Delta table, they will
-   *             remain excluded from the Delta table.
-   *       </ul>
-   * </ul>
+   * <p>For detailed behavior when creating, reading from, or writing to the table, see {@link
+   * TableBuilder#build()}.
    *
    * @param engine {@link Engine} instance to use in Delta Kernel.
    * @param path location of the table. Path is resolved to fully qualified path using the given
    *     {@code engine}.
    * @return an instance of {@link Table} representing the Delta table at the given path
    */
   static Table forPath(Engine engine, String path) {
-    return TableImpl.forPath(engine, path);
+    return builder(engine, path).build();
+  }
+
+  /**
+   * Create a {@link TableBuilder} to build a {@link Table} instance.
+   *
+   * @param engine {@link Engine} instance to use in Delta Kernel.
+   * @param path location of the table. Path is resolved to fully qualified path using the given
+   *     {@code engine}.
+   * @return a {@link TableBuilder} instance
+   * @since 3.3.0
+   */
+  static TableBuilder builder(Engine engine, String path) {
+    return new TableBuilderImpl(engine, path);
   }
 
   /**

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

@@ -0,0 +1,76 @@
+/*
+ * Copyright (2024) 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;
+
+import io.delta.kernel.annotation.Evolving;
+import io.delta.kernel.config.ConfigurationProvider;
+import io.delta.kernel.engine.Engine;
+import io.delta.kernel.exceptions.TableNotFoundException;
+
+/**
+ * Builder for creating a {@link Table} instance.
+ *
+ * <p>Required parameters for building a {@link TableBuilder} instance include:
+ *
+ * <ul>
+ *   <li>{@code Engine}: The {@link Engine} instance required to interact with Delta Kernel.
+ *   <li>{@code Path}: The location of the table, resolved by the provided {@code Engine}.
+ * </ul>
+ *
+ * @since 3.3.0
+ */
+@Evolving
+public interface TableBuilder {
+
+  /**
+   * Set the {@link ConfigurationProvider} to use for the table.
+   *
+   * @param configProvider {@link ConfigurationProvider} to use for the table
+   * @return this updated {@link TableBuilder} instance
+   */
+  TableBuilder withConfigurationProvider(ConfigurationProvider configProvider);
+
+  /**
+   * Set the {@link TableIdentifier} for the table.
+   *
+   * @param tableId {@link TableIdentifier} for the table
+   * @return this updated {@link TableBuilder} instance
+   */
+  TableBuilder withTableId(TableIdentifier tableId);
+
+  /**
+   * Builds the table object for the Delta Lake table at the given path.
+   *
+   * <ul>
+   *   <li>Behavior when the table location doesn't exist:
+   *       <ul>
+   *         <li>Reads will fail with a {@link TableNotFoundException}
+   *         <li>Writes will create the location
+   *       </ul>
+   *   <li>Behavior when the table location exists (with contents or not) but is not a Delta table:
+   *       <ul>
+   *         <li>Reads will fail with a {@link TableNotFoundException}
+   *         <li>Writes will create a Delta table at the given location. If there are any existing
+   *             files in the location that are not already part of the Delta table, they will
+   *             remain excluded from the Delta table.
+   *       </ul>
+   * </ul>
+   *
+   * @return the new {@link Table} instance
+   */
+  Table build();
+}

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

@@ -0,0 +1,41 @@
+/*
+ * Copyright (2024) 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;
+
+/** Identifier for a table. e.g. <catalog> / <schema> / <tableName> */
+public class TableIdentifier {
+  /** The name of the table. */
+  private final String name;
+
+  /** The namespace of the table. e.g. <catalog> / <schema> */
+  private final String[] namespace;
+
+  public TableIdentifier(String[] namespace, String name) {
+    this.namespace = namespace;
+    this.name = name;
+  }
+
+  /** Returns the namespace of the table. */
+  public String[] getNamespace() {
+    return namespace;
+  }
+
+  /** Returns the name of the table. */
+  public String getName() {
+    return name;
+  }
+}

kernel/kernel-api/src/main/java/io/delta/kernel/config/ConfigurationProvider.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright (2024) 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.config;
+
+import io.delta.kernel.annotation.Evolving;
+import java.util.NoSuchElementException;
+import java.util.Optional;
+
+/**
+ * Provides per-session configuration values for Delta Kernel, specific to the current execution.
+ *
+ * <p>These values are not Delta table properties. Delta table properties are stored in the Delta
+ * log metadata and apply globally to all readers and writers interacting with the table.
+ *
+ * <p>Instead, the configuration values provided by this interface are scoped to a single instance
+ * of Delta Kernel during its execution.
+ *
+ * @since 3.3.0
+ */
+@Evolving
+public interface ConfigurationProvider {
+  /**
+   * Retrieves the configuration value for the given key.
+   *
+   * @param key the configuration key
+   * @return the configuration value associated with the key
+   * @throws NoSuchElementException if the key is not found
+   */
+  String get(String key);
+
+  /**
+   * Retrieves the configuration value for the given key. If it doesn't exist, returns {@link
+   * Optional#empty}.
+   *
+   * @param key the configuration key
+   * @return the configuration value associated with the key, if it exists
+   */
+  Optional<String> getOptional(String key);
+
+  /**
+   * Checks if the configuration provider contains the given key.
+   *
+   * @param key the configuration key
+   * @return {@code true} if the key exists, else {@code false}
+   */
+  boolean contains(String key);
+}

kernel/kernel-api/src/main/java/io/delta/kernel/internal/EmptyConfigurationProvider.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright (2024) 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.internal;
+
+import io.delta.kernel.config.ConfigurationProvider;
+import java.util.NoSuchElementException;
+import java.util.Optional;
+
+/**
+ * An implementation of {@link ConfigurationProvider} that always returns empty results or throws
+ * exceptions for configuration values. This class is intended to be used in cases where no
+ * configuration is provided or expected.
+ */
+public class EmptyConfigurationProvider implements ConfigurationProvider {
+  @Override
+  public String get(String key) {
+    throw new NoSuchElementException();
+  }
+
+  @Override
+  public Optional<String> getOptional(String key) {
+    return Optional.empty();
+  }
+
+  @Override
+  public boolean contains(String key) {
+    return false;
+  }
+}

kernel/kernel-api/src/main/java/io/delta/kernel/internal/TableBuilderImpl.java

@@ -0,0 +1,77 @@
+/*
+ * Copyright (2024) 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.internal;
+
+import static java.util.Objects.requireNonNull;
+
+import io.delta.kernel.Table;
+import io.delta.kernel.TableBuilder;
+import io.delta.kernel.TableIdentifier;
+import io.delta.kernel.config.ConfigurationProvider;
+import io.delta.kernel.engine.Engine;
+import io.delta.kernel.internal.util.Clock;
+import java.util.Optional;
+
+public class TableBuilderImpl implements TableBuilder {
+  private final Engine engine;
+  private final String path;
+
+  private Optional<ConfigurationProvider> configProviderOpt = Optional.empty();
+  private Optional<TableIdentifier> tableIdOpt = Optional.empty();
+
+  /** Note: This is not for a public API. It's for internal testing use only. */
+  private Optional<Clock> clockOpt = Optional.empty();
+
+  public TableBuilderImpl(Engine engine, String path) {
+    requireNonNull(engine, "Expected non-null value for 'engine'");
+    requireNonNull(path, "Expected non-null value for 'path'");
+
+    this.engine = engine;
+    this.path = path;
+  }
+
+  @Override
+  public TableBuilder withConfigurationProvider(ConfigurationProvider configProvider) {
+    requireNonNull(configProvider, "Expected non-null value for 'configProvider'");
+    this.configProviderOpt = Optional.of(configProvider);
+    return this;
+  }
+
+  @Override
+  public TableBuilder withTableId(TableIdentifier tableId) {
+    requireNonNull(tableId, "Expected non-null value for 'tableId'");
+    this.tableIdOpt = Optional.of(tableId);
+    return null;
+  }
+
+  /** Note: This is not a public API. It's for internal testing use only. */
+  public TableBuilder withClock(Clock clock) {
+    requireNonNull(clock, "Expected non-null value for 'clock'");
+    this.clockOpt = Optional.of(clock);
+    return this;
+  }
+
+  @Override
+  public Table build() {
+    return TableImpl.create(
+        engine,
+        path,
+        clockOpt.orElse(System::currentTimeMillis),
+        configProviderOpt.orElse(new EmptyConfigurationProvider()),
+        tableIdOpt);
+  }
+}