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 SQLState.java
2. Write new English language text for the error, placing that into the XML message file for English language messages, messages.xml
3. 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.
4. 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 an example
   

An example of this process

For a very good example of this process, please see 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 AlterTableConstantAction.java