Difference between revisions of "Java Error Handling"

From AgileApps Support Wiki
imported>Aeric
imported>Aeric
Line 3: Line 3:
===Error Handling Tools===
===Error Handling Tools===
The [[Java Class Template]] embodies the error handling principles explained below. To do so, it uses the following 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 <tt>"/n"</tt> (newline) to create a line break.)
:* [[Logger.info]] - Put a text message into the [[Debug Log]]. Add <tt>"/n"</tt> (newline) to create a line break.
:* [[Functions.showMessage]] - Display an HTML message onscreen. (Add <tt><nowiki>"<br>"</nowiki></tt> to create a line break.<br>Only one message is displayed, when the code returns to the platform. Multiple calls are concatenated.)
:*: - 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 <tt><nowiki>"<br>"</nowiki></tt> to create a line break.
:*: - Only one message is displayed, when the code returns to the platform.  
:*: - Multiple calls to showMessage() are concatenated--but only if no Exceptions occurred
:* [[Functions.throwError]] - Raise an exception to discontinue processing and roll back the current transaction.
:* [[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
:*: - only last one is seen


===Error Handling Principles===
===Error Handling Principles===

Revision as of 02:33, 14 November 2014

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.
    - Only one message is displayed, when the code returns to the platform.
    - Multiple calls to showMessage() are concatenated--but only if no Exceptions occurred
  • Functions.throwError - Raise an exception to discontinue processing and roll back the current transaction.
    - only last one is seen

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. A standard Java stack trace is of little value, since is consists almost entirely of calls inside the platform.
  4. To get a useful trace, 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 "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.
    Use code like this to generate log message like myMethod(): Exception or myMethod(): ArrayIndexOutOfBounds
    try {
       ...
    }
    catch (Exception e) {
       log( "methodName(): "+e.getClass().getName() );   /  
       throw e; // Roll back the current transaction
    }
    
  5. If there are multiple calls to platform functions, and you want different messages, you need a separate try-catch block for each call.
  6. 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:
    // THROW THE ERROR
    String msg = ""Error <while doing something> in methodName()";
    Functions.throwError(msg);