[Delta] Upgrade to User-Facing Error with Proper Error Class in Time Travel (delta-io#4500)

<!--
Thanks for sending a pull request!  Here are some tips for you:
1. If this is your first time, please read our contributor guidelines:
https://github.com/delta-io/delta/blob/master/CONTRIBUTING.md
2. If the PR is unfinished, add '[WIP]' in your PR title, e.g., '[WIP]
Your PR title ...'.
  3. Be sure to keep the PR description updated to reflect all changes.
  4. Please write your PR title to summarize what this PR proposes.
5. If possible, provide a concise example to reproduce the issue for a
faster review.
6. If applicable, include the corresponding issue number in the PR title
and link it in the body.
-->

#### Which Delta project/connector is this regarding?
<!--
Please add the component selected below to the beginning of the pull
request title
For example: [Spark] Title of my pull request
-->

- [x] Spark
- [ ] Standalone
- [ ] Flink
- [ ] Kernel
- [ ] Other (fill in here)

## Description

<!--
- Describe what this PR changes.
- Describe why we need the change.
 
If this PR resolves an issue be sure to include "Resolves #XXX" to
correctly link and close the issue upon merge.
-->

Upgraded TemporallyUnstableInputException to user-facing error with
proper error class. Reused the existing error class
`DELTA_TIMESTAMP_GREATER_THAN_COMMIT`, which is currently being used by
streaming reads. Make `DeltaErrors.timestampGreaterThanLatestCommit`
also return `TemporallyUnstableInputException`.

## How was this patch tested?

<!--
If tests were added, say they were added here. Please make sure to test
the changes thoroughly including negative and positive cases if
possible.
If the changes were tested in any way other than unit tests, please
clarify how you tested step by step (ideally copy and paste-able, so
that other reviewers can test and check, and descendants can verify in
the future).
If the changes were not tested, please explain why.
-->

Updated existing UTs

## Does this PR introduce _any_ user-facing changes?

<!--
If yes, please clarify the previous behavior and the change this PR
proposes - provide the console output, description and/or an example to
show the behavior difference if possible.
If possible, please also clarify if this is a user-facing change
compared to the released Delta Lake versions or within the unreleased
branches such as master.
If no, write 'No'.
-->

No.

Author: yumingxuanguo-db

spark/src/main/scala/org/apache/spark/sql/delta/DeltaAnalysis.scala

@@ -430,8 +430,8 @@ class DeltaAnalysis(session: SparkSession)
               )
             case tUnstable: TemporallyUnstableInputException =>
               throw DeltaErrors.restoreTimestampGreaterThanLatestException(
-                tUnstable.userTimestamp.toString,
-                tUnstable.commitTs.toString
+                tUnstable.userTs.toString,
+                tUnstable.lastCommitTs.toString
               )
           }
           // TODO: Fetch the table version from deltaLog.update().version to guarantee freshness.

spark/src/main/scala/org/apache/spark/sql/delta/DeltaErrors.scala

@@ -1497,13 +1497,10 @@ trait DeltaErrorsBase
          """.stripMargin)
 
   def timestampGreaterThanLatestCommit(
-      userTimestamp: java.sql.Timestamp,
-      commitTs: java.sql.Timestamp,
-      timestampString: String): Throwable = {
-    new DeltaAnalysisException(
-      errorClass = "DELTA_TIMESTAMP_GREATER_THAN_COMMIT",
-      messageParameters = Array(s"$userTimestamp", s"$commitTs", timestampString)
-    )
+      userTs: java.sql.Timestamp,
+      lastCommitTs: java.sql.Timestamp,
+      maximumTsStr: String): Throwable = {
+    TemporallyUnstableInputException(userTs, lastCommitTs, maximumTsStr)
   }
 
   def timestampInvalid(expr: Expression): Throwable = {
@@ -1521,15 +1518,12 @@ trait DeltaErrorsBase
   }
 
   case class TemporallyUnstableInputException(
-      userTimestamp: java.sql.Timestamp,
-      commitTs: java.sql.Timestamp,
-      timestampString: String,
-      commitVersion: Long) extends AnalysisException(
-    s"""The provided timestamp: $userTimestamp is after the latest commit timestamp of
-         |$commitTs. If you wish to query this version of the table, please either provide
-         |the version with "VERSION AS OF $commitVersion" or use the exact timestamp
-         |of the last commit: "TIMESTAMP AS OF '$timestampString'".
-       """.stripMargin)
+      userTs: java.sql.Timestamp,
+      lastCommitTs: java.sql.Timestamp,
+      maximumTsStr: String)
+    extends DeltaAnalysisException(
+      errorClass = "DELTA_TIMESTAMP_GREATER_THAN_COMMIT",
+      messageParameters = Array(s"$userTs", s"$lastCommitTs", maximumTsStr))
 
   def restoreVersionNotExistException(
       userVersion: Long,

spark/src/main/scala/org/apache/spark/sql/delta/DeltaHistoryManager.scala

@@ -327,8 +327,7 @@ class DeltaHistoryManager(
       throw DeltaErrors.TimestampEarlierThanCommitRetentionException(timestamp, commitTs, tsString)
     } else if (commit.version == latestVersion && !canReturnLastCommit) {
       if (commit.timestamp < time) {
-        throw DeltaErrors.TemporallyUnstableInputException(
-          timestamp, commitTs, tsString, commit.version)
+        throw DeltaErrors.timestampGreaterThanLatestCommit(timestamp, commitTs, tsString)
       }
     }
     commit

spark/src/test/scala/org/apache/spark/sql/delta/DeltaHistoryManagerSuite.scala

@@ -368,17 +368,31 @@ trait DeltaTimeTravelTests extends QueryTest
         .select($"ts".cast("string")).as[String].collect()
         .map(i => s"'$i'")
 
-      val e1 = intercept[AnalysisException] {
+      val e1 = intercept[DeltaErrors.TemporallyUnstableInputException] {
         sql(s"select count(*) from ${timestampAsOf(tblName, ts(0))}").collect()
       }
-      assert(e1.getMessage.contains("VERSION AS OF 0"))
-      assert(e1.getMessage.contains("TIMESTAMP AS OF '2018-10-24 14:14:18'"))
+      checkError(
+        e1,
+        "DELTA_TIMESTAMP_GREATER_THAN_COMMIT",
+        sqlState = "42816",
+        parameters = Map(
+          "providedTimestamp" -> "2018-10-24 14:24:18.0",
+          "tableName" -> "2018-10-24 14:14:18.0",
+          "maximumTimestamp" -> "2018-10-24 14:14:18")
+      )
 
-      val e2 = intercept[AnalysisException] {
+      val e2 = intercept[DeltaErrors.TemporallyUnstableInputException] {
         sql(s"select count(*) from ${timestampAsOf(tblName, start + 10.minutes)}").collect()
       }
-      assert(e2.getMessage.contains("VERSION AS OF 0"))
-      assert(e2.getMessage.contains("TIMESTAMP AS OF '2018-10-24 14:14:18'"))
+      checkError(
+        e2,
+        "DELTA_TIMESTAMP_GREATER_THAN_COMMIT",
+        sqlState = "42816",
+        parameters = Map(
+          "providedTimestamp" -> "2018-10-24 14:24:18.0",
+          "tableName" -> "2018-10-24 14:14:18.0",
+          "maximumTimestamp" -> "2018-10-24 14:14:18")
+      )
 
       checkAnswer(
         sql(s"select count(*) from ${timestampAsOf(tblName, "'2018-10-24 14:14:18'")}"),

spark/src/test/scala/org/apache/spark/sql/delta/DeltaTimeTravelSuite.scala

@@ -209,11 +209,19 @@ class DeltaTimeTravelSuite extends QueryTest
         assert(history.getActiveCommitAtTime(start + (i * 20 + 10).minutes, true).version === i)
       }
 
-      val e = intercept[AnalysisException] {
+      val e = intercept[DeltaErrors.TemporallyUnstableInputException] {
         // This is 20 minutes after the last commit
         history.getActiveCommitAtTime(start + 200.minutes, false)
       }
-      assert(e.getMessage.contains("after the latest commit timestamp"))
+      checkError(
+        e,
+        "DELTA_TIMESTAMP_GREATER_THAN_COMMIT",
+        sqlState = "42816",
+        parameters = Map(
+          "providedTimestamp" -> "2018-10-24 17:34:18.0",
+          "tableName" -> "2018-10-24 17:14:18.0",
+          "maximumTimestamp" -> "2018-10-24 17:14:18")
+      )
       assert(history.getActiveCommitAtTime(start + 180.minutes, true).version === 9)
 
       val e2 = intercept[AnalysisException] {
@@ -522,18 +530,32 @@ class DeltaTimeTravelSuite extends QueryTest
       // Simulate getting the timestamp directly from Spark SQL
       val ts = getSparkFormattedTimestamps(start + 10.minutes)
 
-      val e1 = intercept[AnalysisException] {
+      val e1 = intercept[DeltaErrors.TemporallyUnstableInputException] {
         spark.read.format("delta").option("timestampAsOf", ts.head).load(tblLoc).collect()
       }
-      assert(e1.getMessage.contains("VERSION AS OF 0"))
-      assert(e1.getMessage.contains("TIMESTAMP AS OF '2018-10-24 14:14:18'"))
+      checkError(
+        e1,
+        "DELTA_TIMESTAMP_GREATER_THAN_COMMIT",
+        sqlState = "42816",
+        parameters = Map(
+          "providedTimestamp" -> "2018-10-24 14:24:18.0",
+          "tableName" -> "2018-10-24 14:14:18.0",
+          "maximumTimestamp" -> "2018-10-24 14:14:18")
+      )
 
-      val e2 = intercept[AnalysisException] {
+      val e2 = intercept[DeltaErrors.TemporallyUnstableInputException] {
         spark.read.format("delta").load(identifierWithTimestamp(tblLoc, start + 10.minutes))
           .collect()
       }
-      assert(e2.getMessage.contains("VERSION AS OF 0"))
-      assert(e2.getMessage.contains("TIMESTAMP AS OF '2018-10-24 14:14:18'"))
+      checkError(
+        e2,
+        "DELTA_TIMESTAMP_GREATER_THAN_COMMIT",
+        sqlState = "42816",
+        parameters = Map(
+          "providedTimestamp" -> "2018-10-24 14:24:18.0",
+          "tableName" -> "2018-10-24 14:14:18.0",
+          "maximumTimestamp" -> "2018-10-24 14:14:18")
+      )
 
       checkAnswer(
         spark.read.format("delta").option("timestampAsOf", "2018-10-24 14:14:18")
@@ -771,9 +793,16 @@ class DeltaTimeTravelSuite extends QueryTest
         val ex2 = intercept[DeltaErrors.TemporallyUnstableInputException] {
           spark.sql(s"SELECT * from $tableName FOR TIMESTAMP AS OF '2018-10-24 20:14:18'")
         }
-        assert(ex2.getMessage contains
-          "The provided timestamp: 2018-10-24 20:14:18.0 is after the " +
-            "latest commit timestamp of\n2018-10-24 14:34:18.0")
+
+        checkError(
+          ex2,
+          "DELTA_TIMESTAMP_GREATER_THAN_COMMIT",
+          sqlState = "42816",
+          parameters = Map(
+            "providedTimestamp" -> "2018-10-24 20:14:18.0",
+            "tableName" -> "2018-10-24 14:34:18.0",
+            "maximumTimestamp" -> "2018-10-24 14:34:18")
+        )
       }
     }
   }

spark/src/test/scala/org/apache/spark/sql/delta/InCommitTimestampSuite.scala

@@ -654,7 +654,7 @@ class InCommitTimestampSuite
           catalogTableOpt = None,
           canReturnLastCommit = false)
       }
-      assert(e.getMessage.contains("The provided timestamp:") && e.getMessage.contains("is after"))
+      assert(e.getMessage.contains("The provided timestamp") && e.getMessage.contains("is after"))
     }
   }