Logging

Once you have determined that there is a real problem with the Comparator, the first step is to examine the log file. The Comparator produces log files with a name like compare.log.1 in the main JigCell directory. These log files record interesting events, exceptions, and other informative messages that may give you a clue about the problem. Log files are rotated when they get full, so look for the file with the most recent update time. It might not be the log file with the largest number.

Comparator additions can also make use of the log file. The Compare class contains static methods allowing you to add information to the logs. To write directly to the log file, use the warning or message methods. If you additionally want to trigger an assertion, use the assertion method. This will stop the program and give a stack trace if exception tracing is enabled. The front end shell will automatically generate log entries when you use the shellHandleException or shellHandleMessage methods to report problems to the user.

Tracing Exceptions

If you would like to more actively track abnormal events, you can enable the Comparator's exception debugging facility. This facility should not be used in a production environment. When enabled, the Comparator becomes so eager to break and warn on errors that normal error recovery activities may be skipped. After an exception is detected, the unhandled error dialog appears giving you information about the exception that occured and its location. Exception tracing should only be used when you are looking for a specific problem.

To use the exception debugging facility, you must enable assertions for the Comparator classes. Normally, it is sufficient to pass the -ea option to the Java runtime. Your runtime may require a different command line option or use some other means for enabling assertions, consult its documentation. Note that enabling assertions does not automatically turn on exception debugging and is generally safe to use.

The best way to use the exception debugging facility is to get the Comparator as close as possible to the exception point before enabling it. When you are ready to enable exception debugging, use the Toggle Exception Debugging option in the Comparator menu. Selecting this option again will disable debugging if you need to perform other operations. You can also programmatically toggle exception debugging by calling the setDebugExceptions method of Compare.

Sometimes it is necessary to enable exception debugging during startup to trace a problem. The Comparator will look for a command line option named debug_exceptions to be set. Pass your Java runtime the -Ddebug_exceptions=true option to do this. Alternatively, exception debugging can be toggled in the Comparator configuration file. Setting the Compare.debugExceptions variable in the configuration block of your main Comparator class will allow you to debug exceptions after the configuration is loaded. The command line option is checked early in startup, prior to checking the configuration file.

Debugging Console

The most powerful tool available is the console debugger. This should be used as a last resort when there is a problem. To start the console debugger, use the Open Debug Console option in the Comparator menu. A new Comparator tab will open named Console. There is no way to close a debugging console once opened. Normally you will want to restart the Comparator after you have determined what the problem is.

The console debugger is a full programmatic window into the Comparator internals. At the bottom of the tab, you can type Java commands which will be interpreted and executed in immediate mode. A variable named compare is defined initially that represents the current Comparator instance. Consult the Comparator API documentation for all of the methods you can call. Any access restrictions and protections of the Java language are disabled in the console debugger so you can directly manipulate fields and methods even if they are normally private or hidden.

What Happens by Default

If you take no special precaution against exceptions, they will probably eventually be dealt with by the Comparator unhandled error dialog. An error in a transform or objective function will never affect unrelated evaluations. However, if your computation is the dependency of another generator, that generator controls what happens to your thrown exceptions. Don't rely on the default of bubbling up to the unhandled error dialog if it is important to you.

Reporting Errors

To report an error, use one of the fireEvaluationError methods. These error messages can be turned into an easier to use, asynchronous, report of evaluation progress by the view that requested evaluation. This is often preferable to an uncaught error which may block evaluation progress or not be reported at all. Calling one of these method will only report the error, they do not terminate the evaluation of your generator. A special ERROR return value is defined for you in objectives which is preferable to alternatives such as returning null or propagating the exception. You may have some other error handling code that you wish to invoke instead to continue the evaluation. The directions here assume that you have based your transform or objective on one of the default transform implementation, or at least used ProgrammableDataGenerator. Otherwise, you are on your own.

It is also possible to listen for errors occuring in other generators. Use the addEvaluationListener method on a generator to register a handler for evaluation events. In addition to receiving error reports, you will also be sent information about when a generator begins or ends the evaluation process. For transforms, there are equivalent methods on the transform context that will give you information about every transform in the context without registering with each one individually. Normally you won't need to listen for errors unless you are creating a view that uses data generators which can be evaluated.

Debugging Tools in the Comparator

There are other debugging tools for tranfsorms and objective functions already included with the Comparator. The error messages reported by fireEvaluationError are collected by an evaluation error viewer built into several of the default views. All of the error information is archived by this viewer allowing for easy review of what happened during evaluation at a later time. Users of transforms may find the Transform Debugger useful for transforms that have incorrect output. The debugger allows you to inspect many of the aspects of a transform not normally displayed including the output and annotations of all of the primitive transforms needed to compute the result. A future Comparator user's manual will describe how to use these tools further.