Java Error Handling

The Java Class Template embodies the error handling principles explained here. 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.

The goal of error handling is identify which error occurred, where it happened, and (ideally) what data was present at the time. The principles elucidated below help to achieve those goals. (You can call Functions.throwError to 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. Use the class name as "category" label when calling Logger.info (to ).
2. In a logged error message, include the method name (to find the message rapidly).
3. When catching an unexpected exception, display the exception's class name.
   That's generally more indicative than the message embedded in the exception
4. All calls to platform functions need to be in a try-catch block.
5. All calls to methods that invoke a platform function need to be in a try-catch block.
6. 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
   

7. 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;
   

   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 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;
   

9. 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);