db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Db-derby Wiki] Update of "AddAnErrorMessage" by BryanPendleton
Date Sat, 09 Jul 2016 15:46:12 GMT
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]]

Mime
View raw message