cloud-fan commented on a change in pull request #32850:
URL: https://github.com/apache/spark/pull/32850#discussion_r660337990
##########
File path: core/src/main/resources/error/README.md
##########
@@ -0,0 +1,89 @@
+# Guidelines
+
+To throw a standardized user-facing exception, developers should specify the
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",
+ "message": ["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
+
+### Error class
+
+Error classes are a succinct, human-readable representation of the error
category.
+
+Invariants:
+
+- Unique
+- Consistent across releases
+- Sorted alphabetically
+
+### SQLSTATE
Review comment:
let's put it after `Message`, as it's optional
--
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.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
