karenfeng commented on a change in pull request #32850:
URL: https://github.com/apache/spark/pull/32850#discussion_r655602907
##########
File path: core/src/main/resources/error/README.md
##########
@@ -0,0 +1,79 @@
+# Guidelines
+
+To throw a standardized exception, developers should use an error class and
message parameters
+rather than an arbitrary error message.
+
+## Usage
+
+To throw an exception, do the following.
+
+1. Check if an appropriate error class already exists in `error-class.json`.
+ If true, skip to step 3. Otherwise, continue to step 2.
+2. Add a new class to `error-class.json`; keep in mind the invariants below.
+3. Check if the exception type already extends `SparkError`.
+ If true, skip to step 5. Otherwise, continue to step 4.
+4. Mix `SparkError` into the exception.
+5. Throw the exception with the error class and message parameters.
+
+### Before
+
+Throw exception:
+
+ throw new TestException("Problem A because B")
+
+
+### After
+
+`error-class.json`
+
+ "PROBLEM_BECAUSE": {
+ "sqlState": "XXXXX",
+ "messageFormatLines": ["Problem %s because %s"]
+ }
+
+`SparkException.scala`
+
+ class SparkTestException(
+ val errorClass: String,
+ val messageParameters: Seq[String])
+ extends TestException(SparkError.getMessage(errorClass,
messageParameters))
+ with SparkError
+
+Throw exception:
+
+ throw new SparkTestException("PROBLEM_BECAUSE", Seq("A", "B"))
+
+## Access fields
+
+To access error fields, catch exceptions that extend
`org.apache.spark.SparkError` and access
+ - Error class with `errorClass`
+ - SQLSTATE with `sqlState`
+
+
+ try {
+ ...
+ } catch {
+ case e: SparkError if e.sqlState.forall(_.startsWith("42")) =>
+ warn("Syntax error")
+ }
+
+## Fields
+
+All fields, excluding error messages, should be consistent across releases.
Review comment:
Error messages can (and probably will) change between releases; that's
why I included the caveat of "excluding error messages." This is actually a
major driver for this - so we can improve the quality of error messages over
time.
To clarify, I think it would be beneficial for our user base if we were
consistent across error class and SQLSTATE across releases. With consistent
error classes, users can build in known work-arounds or catch and re-throw
known error types. With consistent SQLSTATEs, clients will also have
predictable behavior.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
