PreEmptive Protection - DashO v8.2 User Guide

Exception Reporting

PreEmptive Protection - DashO can instrument applications to report unhandled exceptions thrown by an application and optionally send a message to a PreEmptive Analytics server. Additionally the application can be instrumented to report exceptions that are caught, uncaught, or thrown at the method level. The exception reporting is confiugured on the Injected Instrumentation screen or by adding code annotations.

Application and Thread-level Reporting

Unhandled exceptions can be intercepted and reported at either the application level or on a per-thread basis. The unhandled exceptions can be sent directly to a PreEmptive Analytics server for non-GUI applications without user interaction. For GUI applications you can select to have a dialog box presented to your application's user so they may choose to send the report or not. They will also be able to enter information about the activities they were performing prior to the exception as well as some contact information. This information is optional, but if entered is available on the PreEmptive Analytics Workbench or PreEmptive Analytics for TFS along with the exception information.

Application and thread-level reporting is added with the AddUncaughtExceptionHandler annotation. Properties of the Annotation determine if the handler is installed as the default handler or only for the current thread and whether a dialog is displayed to the user.

@AddUncaughtExceptionHandler(showDialog=true)
public static void main(final String[] args){
    // ...
}

new Thread() {
    @AddUncaughtExceptionHandler(thread=true)
    public void run() {
        // ...
    }
}.start();

Allowing the user to interact with a dialog gives them an opportunity to override the global opt-in setting. If the user chooses to send the report it will override an opt-out from other Analytics messages. Your application will still require the configuration information that will allow it to be identified to a PreEmptive Analytics Server. If the dialog is requested in a non-GUI application the report will only be sent if the user has opted-in to sending messages.

If you choose to send the report without user interaction the report will only be sent if the user has opted-in to sending analytics messages.

Note:

These features are available as an API in the ExceptionHandler class.

Method-level Reporting

If you require a more fine grained approach to the reporting of exceptions you can use Annotations to track exceptions at the method level. DashO provides three Annotations that are used to add method level exception reporting: ReportCaughtExceptions, ReportThrownExceptions, and ReportUncaughtExceptions. All three annotations support the following behaviors:

  • Send an analytics fault message. A fault message will be sent to a PreEmptive Analytics server. This is the sendMessage property. The default is to send a message. To send the message your application must contains an ApplicationStart and the user must opt-in to the sending of messages.

  • Call a method or set a field. You can have the exception passed back to your application by invoking a method that takes a Throwable or by setting a Throwable field. This is the action property.

If you use both behaviors the sending of the message is performed before the action. The following example show how the reporting of exceptions can be added at the class level so that it applied to all methods in the class. In the example the messages are sent to a PreEmptive Analytics server as well as logged locally using Log4J.

import org.apache.log4j.Logger

@ReportCaughtExceptions(action="@onCatch()")
@ReportThrownExceptions(action="@onThrow()")
class MyClass {
    private final static Logger log = Logger.getLogger(MyClass.class)

    public void execute(){
        // ...
    }

    private static void onCatch(Throwable t){
        log.info("MyClass caught " + t.getClass().getName(), t);
    }

    private static void onThrow(Throwable t){
        log.warn("MyClass threw " + t.getClass().getName(), t);
    }
}

In addition to these previously described properties the ReportUncaughtExceptions annotation allows you to ignore the unhandled exception. Methods that have a numeric return will return zero when an unhandled exception is ignored. Methods that return objects or arrays will return null.

In the following example calling the div(x, 0) could cause an ArithmeticException to be thrown and printed to System.err but the method would return zero.

@ReportUncaughtExceptions(sendMessage=false, action="onErr()", ignore=true)
int div(int num, int denom){
    return num / denom;
}

void onErr(Throwable t){
    t.printStackTrace();
}

PreEmptive Protection - DashO Version 8.2.0. Copyright © 2017 PreEmptive Solutions, LLC