[Kernel]Provide a finer grain error classes for some kernel error classes

kernel/kernel-api/src/main/java/io/delta/kernel/exceptions/CommitRangeNotFoundException.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright (2025) 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.exceptions;
+
+import io.delta.kernel.annotation.Evolving;
+import java.util.Optional;
+
+/**
+ * Exception thrown when Kernel cannot find any commit files in the requested version range. This
+ * can happen when the requested versions don't exist in the table.
+ *
+ * @since 4.1.0
+ */
+@Evolving
+public class CommitRangeNotFoundException extends KernelException {
+
+  private final String tablePath;
+  private final long startVersion;
+  private final Optional<Long> endVersion;
+
+  public CommitRangeNotFoundException(
+      String tablePath, long startVersion, Optional<Long> endVersion) {
+    super(
+        String.format(
+            "%s: Requested table changes between [%s, %s] but no log files found in the requested"
+                + " version range.",
+            tablePath, startVersion, endVersion));
+    this.tablePath = tablePath;
+    this.startVersion = startVersion;
+    this.endVersion = endVersion;
+  }
+
+  /** @return the table path where the commit range was not found */
+  public String getTablePath() {
+    return tablePath;
+  }
+
+  /** @return the start version of the requested commit range */
+  public long getStartVersion() {
+    return startVersion;
+  }
+
+  /**
+   * @return the end version of the requested commit range, or empty if no end version was specified
+   */
+  public Optional<Long> getEndVersion() {
+    return endVersion;
+  }
+}

kernel/kernel-api/src/main/java/io/delta/kernel/exceptions/UnsupportedProtocolVersionException.java

@@ -0,0 +1,69 @@
+/*
+ * Copyright (2025) 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.exceptions;
+
+import io.delta.kernel.annotation.Evolving;
+
+/**
+ * Exception thrown when Kernel encounters unsupported protocol versions.
+ *
+ * @since 4.1.0
+ */
+@Evolving
+public class UnsupportedProtocolVersionException extends KernelException {
+
+  /** Enum representing the type of Delta protocol version. */
+  public enum ProtocolVersionType {
+    /** Reader protocol version */
+    READER,
+    /** Writer protocol version */
+    WRITER
+  }
+
+  private final String tablePath;
+  private final int version;
+  private final ProtocolVersionType versionType;
+
+  public UnsupportedProtocolVersionException(
+      String tablePath, int version, ProtocolVersionType versionType) {
+    super(
+        String.format(
+            "Unsupported Delta protocol %s version: table `%s` requires %s version %s "
+                + "which is unsupported by this version of Delta Kernel.",
+            versionType.name().toLowerCase(),
+            tablePath,
+            versionType.name().toLowerCase(),
+            version));
+    this.tablePath = tablePath;
+    this.version = version;
+    this.versionType = versionType;
+  }
+
+  /** @return the table path where the unsupported protocol was encountered */
+  public String getTablePath() {
+    return tablePath;
+  }
+
+  /** @return the unsupported protocol version */
+  public int getVersion() {
+    return version;
+  }
+
+  /** @return the type of protocol version (READER or WRITER) */
+  public ProtocolVersionType getVersionType() {
+    return versionType;
+  }
+}

kernel/kernel-api/src/main/java/io/delta/kernel/exceptions/UnsupportedReaderFeatureException.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright (2025) 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.exceptions;
+
+import io.delta.kernel.annotation.Evolving;
+import java.util.Set;
+
+/**
+ * Exception thrown when Kernel encounters unsupported reader table features.
+ *
+ * @since 4.1.0
+ */
+@Evolving
+public class UnsupportedReaderFeatureException extends UnsupportedTableFeatureException {
+
+  public UnsupportedReaderFeatureException(String tablePath, Set<String> readerFeatures) {
+    super(
+        tablePath,
+        readerFeatures,
+        String.format(
+            "Unsupported Delta reader features: table `%s` requires reader table features [%s] "
+                + "which is unsupported by this version of Delta Kernel.",
+            tablePath, String.join(", ", readerFeatures)));
+  }
+}

kernel/kernel-api/src/main/java/io/delta/kernel/exceptions/UnsupportedTableFeatureException.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright (2025) 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.exceptions;
+
+import io.delta.kernel.annotation.Evolving;
+import java.util.Collections;
+import java.util.Set;
+
+/**
+ * Base exception thrown when Kernel encounters unsupported table features.
+ *
+ * @since 4.1.0
+ */
+@Evolving
+public class UnsupportedTableFeatureException extends KernelException {
+
+  private final String tablePath;
+  private final Set<String> unsupportedFeatures;
+
+  public UnsupportedTableFeatureException(
+      String tablePath, Set<String> unsupportedFeatures, String message) {
+    super(message);
+    this.tablePath = tablePath;
+    this.unsupportedFeatures =
+        unsupportedFeatures != null
+            ? Collections.unmodifiableSet(unsupportedFeatures)
+            : Collections.emptySet();
+  }
+
+  public UnsupportedTableFeatureException(
+      String tablePath, String unsupportedFeature, String message) {
+    this(tablePath, Collections.singleton(unsupportedFeature), message);
+  }
+
+  /**
+   * @return the table path where the unsupported features were encountered, or null if not
+   *     applicable
+   */
+  public String getTablePath() {
+    return tablePath;
+  }
+
+  /** @return an unmodifiable set of unsupported feature names */
+  public Set<String> getUnsupportedFeatures() {
+    return unsupportedFeatures;
+  }
+}

kernel/kernel-api/src/main/java/io/delta/kernel/exceptions/UnsupportedWriterFeatureException.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright (2025) 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.exceptions;
+
+import io.delta.kernel.annotation.Evolving;
+import java.util.Set;
+
+/**
+ * Exception thrown when Kernel encounters unsupported writer table features.
+ *
+ * @since 4.1.0
+ */
+@Evolving
+public class UnsupportedWriterFeatureException extends UnsupportedTableFeatureException {
+
+  public UnsupportedWriterFeatureException(String tablePath, Set<String> writerFeatures) {
+    super(
+        tablePath,
+        writerFeatures,
+        String.format(
+            "Unsupported Delta writer features: table `%s` requires writer table features [%s] "
+                + "which is unsupported by this version of Delta Kernel.",
+            tablePath, String.join(", ", writerFeatures)));
+  }
+}

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

@@ -101,14 +101,9 @@ public static KernelException timestampAfterLatestCommit(
     return new KernelException(message);
   }
 
-  public static KernelException noCommitFilesFoundForVersionRange(
+  public static CommitRangeNotFoundException noCommitFilesFoundForVersionRange(
       String tablePath, long startVersion, Optional<Long> endVersionOpt) {
-    String message =
-        String.format(
-            "%s: Requested table changes between [%s, %s] but no log files found in the requested"
-                + " version range.",
-            tablePath, startVersion, endVersionOpt);
-    return new KernelException(message);
+    return new CommitRangeNotFoundException(tablePath, startVersion, endVersionOpt);
   }
 
   public static KernelException startVersionNotFound(
@@ -146,53 +141,39 @@ public static KernelException invalidVersionRange(long startVersion, long endVer
   }
 
   /* ------------------------ PROTOCOL EXCEPTIONS ----------------------------- */
-  public static KernelException unsupportedReaderProtocol(
+  public static UnsupportedProtocolVersionException unsupportedReaderProtocol(
       String tablePath, int tableReaderVersion) {
-    String message =
-        String.format(
-            "Unsupported Delta protocol reader version: table `%s` requires reader version %s "
-                + "which is unsupported by this version of Delta Kernel.",
-            tablePath, tableReaderVersion);
-    return new KernelException(message);
+    return new UnsupportedProtocolVersionException(
+        tablePath,
+        tableReaderVersion,
+        UnsupportedProtocolVersionException.ProtocolVersionType.READER);
   }
 
-  public static KernelException unsupportedWriterProtocol(
+  public static UnsupportedProtocolVersionException unsupportedWriterProtocol(
       String tablePath, int tableWriterVersion) {
-    String message =
-        String.format(
-            "Unsupported Delta protocol writer version: table `%s` requires writer version %s "
-                + "which is unsupported by this version of Delta Kernel.",
-            tablePath, tableWriterVersion);
-    return new KernelException(message);
+    return new UnsupportedProtocolVersionException(
+        tablePath,
+        tableWriterVersion,
+        UnsupportedProtocolVersionException.ProtocolVersionType.WRITER);
   }
 
-  public static KernelException unsupportedTableFeature(String feature) {
+  public static UnsupportedTableFeatureException unsupportedTableFeature(String feature) {
     String message =
         String.format(
             "Unsupported Delta table feature: table requires feature \"%s\" "
                 + "which is unsupported by this version of Delta Kernel.",
             feature);
-    return new KernelException(message);
+    return new UnsupportedTableFeatureException(null, feature, message);
   }
 
-  public static KernelException unsupportedReaderFeatures(
+  public static UnsupportedReaderFeatureException unsupportedReaderFeatures(
       String tablePath, Set<String> readerFeatures) {
-    String message =
-        String.format(
-            "Unsupported Delta reader features: table `%s` requires reader table features [%s] "
-                + "which is unsupported by this version of Delta Kernel.",
-            tablePath, String.join(", ", readerFeatures));
-    return new KernelException(message);
+    return new UnsupportedReaderFeatureException(tablePath, readerFeatures);
   }
 
-  public static KernelException unsupportedWriterFeatures(
+  public static UnsupportedWriterFeatureException unsupportedWriterFeatures(
       String tablePath, Set<String> writerFeatures) {
-    String message =
-        String.format(
-            "Unsupported Delta writer feature: table `%s` requires writer table feature \"%s\" "
-                + "which is unsupported by this version of Delta Kernel.",
-            tablePath, writerFeatures);
-    return new KernelException(message);
+    return new UnsupportedWriterFeatureException(tablePath, writerFeatures);
   }
 
   public static KernelException columnInvariantsNotSupported() {