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.

Note: 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. However, the operations in the catch-block are different, in those three cases:

   a. In the catch block for a method that is called from the platform:

   // LOG, THROW, and SHOW
   String msg = "Unexpected exception in methodName()";
   log(msg + ":\n" + e.getClass().getName() ); //Sometimes helpful: + "\n" + e.getMessage() );   
   show(msg + " - see debug log");
   

   b. In the catch block inside a method that is called by your code:

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

   c. In the catch block surrounding the call you make to that method:

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

   d. Outside of a catch block, use Functions.throwError:

   // THROW
   Functions.throwError("msg");