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.)
• Functions.showMessage - Display an HTML message onscreen. (Add "<br>" to create a line break.
  Only one message is displayed, when the code returns to the platform. Multiple calls are concatenated.)
• Functions.throwError - Raise an exception to discontinue processing and roll back the current transaction.

get a stack trace, but it generally doesn't help very much, because the trace is almost entirely devoted to the sequence of platform calls that got to your code. You're more interested in the steps your program followed. Following these steps gives you that information

Error Handling Principles

1. All calls to platform functions need to be in a try-catch block.
2. All calls to methods that invoke a platform function need to be in a try-catch block.
3. When calling a platform function, ...
4. When calling a routine, ...
5. A standard Java stack trace is of little value, since is consists almost entirely of calls inside the platform.
6. To get a useful trace, catch every exception and add the name of the current method to the log.

   a. Call Logger.info. Use the class name as "category" label.

   b. Include the method name in the message.

   c. Include the exception's class name, using e.getClass().getName().
   For things like ArrayIndexOutOfBounds, that will generally tell you what went wrong.

7. In a method that is invoked directly from the platform, the rule is to LOG, SHOW, and THROW:

   // LOG, SHOW, and RE-THROW
   String msg = "Unexpected exception in methodName()";
   log(msg + ":\n" + e.getClass().getName() );    
   show(msg + " - see debug log");     
   throw e; // Roll back the current transaction
   

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

8. In a catch block inside a method that is called by your code, the rule is to LOG and THROW:

   // LOG and RE-THROW
   String msg = "Unexpected exception in methodName()";
   log(msg + ":\n" + e.getClass().getName() ); //+ "\n" + e.getMessage() );   
   throw e;
   

9. In the catch block surrounding the call you make to that method, the rule is to SHOW:

   // SHOW
   show("Error in getActivities() - see debug log");
   return;
   

10. Outside of a catch block, the rule is to THROW, using Functions.throwError to generate an exception that interrupts processing and rolls back the current transaction:

    // THROW
    String msg = ""Error <while doing something>";
    Functions.throwError(msg);