[Db-derby Wiki] Update of "AddAnErrorMessage" by BryanPendleton

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Db-derby Wiki" for change notification.

The "AddAnErrorMessage" page has been changed by BryanPendleton:
https://wiki.apache.org/db-derby/AddAnErrorMessage

Comment:
New page describing the error message process

New page:
= Overview =

Derby's error messages are implemented in a way that allows the text of the messages to be translated to other languages.

In the past, Derby contributors have translated Derby's error messages into a variety of languages. Although new error messages are not always translated, the error-handling infrastructure is powerful enough to be able to look for a translated message, then fall back to an English message if a translated version is not found.

Therefore, when adding a new error message to the Derby system, you need only provide an English language version. Of course, if you are capable of contributing versions in other languages, that is welcomed as well. But typically new error messages are added only in their English form.

To add a new error message, the process is fairly simple:
 1. Invent a new `SQLState` value, following the existing pattern and choosing an appropriate value, and a meaningful symbolic name for the `SQLState`, and place that into [[https://svn.apache.org/viewvc/db/derby/code/trunk/java/shared/org/apache/derby/shared/common/reference/SQLState.java?view=markup&pathrev=1609099|SQLState.java]]
 1. Write new English language text for the error, placing that into the XML message file for English language messages, [[https://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/loc/messages.xml?view=markup|messages.xml]]
 1. In the code which recognizes the error condition, throw the new exception, using the symbolic name from `SQLState.java` as the argument to `StandardException.newException`, and passing any appropriate arguments for the message as arguments to the `newException()` call.
 1. Don't forget to add new tests that verify that your message is thrown at the appropriate situation, and that the SQLstate is as you expect. This is commonly done using the testing-helper-function `assertStatementError`: here's [[https://svn.apache.org/viewvc/db/derby/code/trunk/java/shared/org/apache/derby/shared/common/reference/SQLState.java?view=markup&pathrev=1609099|an example]]

== An example of this process ==

For a very good example of this process, please see [[https://svn.apache.org/viewvc?view=revision&revision=1609099|SVN Revision 1609099]]. This modification to Derby is quite clean and demonstrates the above steps with very few distractions.

One detail about this particular change is that the 'badCustomTool' private method was not strictly speaking necessary: the more common pattern in  Derby code is simply to do `throw StandardException.newException(message-code [, args...]);`

For a fairly small source code example which shows a number of examples of how to raise error messages, see [[https://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/impl/sql/execute/AlterTableConstantAction.java?view=markup|AlterTableConstantAction.java]]