Java Error Handling

The goal of error handling is identify the error that occurred, where it happened, and (ideally) what data was present at the time. The ideas presented in this section can help to achieve those goals.

Error Handling Tools

The Java Class Template embodies the error handling principles explained below. To do so, it uses the following tools:

• Logger.info - Put a text message into the Debug Log. Add "/n" (newline) to create a line break.

  None of the other tools put entries into the log. This is the only one that does.

• Functions.showMessage - Display an HTML message onscreen. Add "<br>" to create a line break.

  Multiple calls to showMessage() are concatenated in the message buffer--but only if no Exceptions occurred.

  The contents of the message buffer are displayed when the code returns to the platform.

• Functions.throwError - Raise an exception to discontinue processing and roll back the current transaction.

  Be sure to include a message(Functions.throwError("some message"). Otherwise, nothing is displayed to the user.

  That call is 100% equivalent to throw new Exception(msg)

  Those calls overwrite the message buffer, replacing any previous calls and any stored text from calls to showMessage. so only the last call is seen by the user.

  Whenever the user sees such a message occurs, the Debug Log should contain detailed information on the cause. Follow the steps in the next section to be sure it does.

Error Handling Principles

1. All calls to platform functions and standard Java functions need to be in a try-catch block. (Otherwise, a standard Java exception would be ignored.)
2. Calls to Functions.showMessage are useful in the normal flow of code, but not in a catch-block.
   (You have to re-throw an exception to be sure it is seen. But when you re-throw it, the message it contains is the only thing the user sees.)
3. Use showMessage() calls to put breadcrumbs in a block of code works, therefore, as long as no exceptions occur. Putting those messages in the Debug Log is more reliable. (To get the best of both worlds, do both!)
4. A standard Java stack trace is of little value, since it is almost entirely the sequence of platform calls that got to your code. You're more interested in the steps your program followed. To get that information, catch every exception and add the name of the current method to the log, along with the exception's class name:

   a. Call Logger.info. Use the class name as the "category" label (2nd parameter).

   b. Include the method name in the message.

   c. Include the exception's class name, using e.getClass().getName().

   (For a standard Java exception, that will generally tell you what went wrong.)

   <syntaxhighlight lang="java" enclose="div">

try {

  ...

} catch (Exception e) {

  Logger.info( "methodName(): "+e.getClass().getName(), "CurrentClass" );  
  Functions.throwError(e.getMessage());

} </syntaxhighlight>

1. That code generates log entries like these:

   someMethod(): Exception

   someMethod(): ArrayIndexOutOfBounds

2. If there are multiple calls to platform functions, and you want different messages, you need a separate try-catch block for each call.

3. In code that is outside of a catch block (for example, when a call worked but you got back an unexpected value), generate an exception to interrupt processing and roll back the current transaction:

   <syntaxhighlight lang="java" enclose="div">

// THROW THE ERROR String msg = ""Error <doing something> in methodName()"; Functions.throwError(msg); </syntaxhighlight>

2. Use a method like this one to trace the execution of some tricky bit of code. If the code runs properly, you'll see the trace messages onscreen. If not, they'll still be in the Debug Log.

   <syntaxhighlight lang="java" enclose="div">

public void debug(String msg) throws Exception { show(msg); log(msg); } </syntaxhighlight>