Error Handling
Any time a Java method throws an uncaught Exception it will be written to the log file as an error.
If you need to figure out what is going wrong, the log file should be your first piece of evidence. The location of the log file is set in the jinx.ini config file, and by default it is in the logs folder alongside the Jinx add-in.
In addition to the log file, Jinx provides ways of handling errors to present them to the user directly when they occur. The full exception and stack trace are always written to the log file, but in many cases providing the user with some details of the error is sufficient to let them understand the problem without having to resort to the log file.
For example, if a worksheet function fails Excel’s default behaviour is to show an error like #NA. Jinx’s error handling can catch the exception and convert it to a more human readable error message.
The configured error handler will be called for all types of functions when an uncaught exception is thrown, not simply worksheet functions.
Standard Error Handlers
Jinx provides three standard error handlers to choose from.
- default
- quiet
- none
These are configured by setting error_handler in the jinx.ini file, e.g.:
[JINX]
error_handler = default
| Error Source | Default handler | Quiet handler | None handler |
| Worksheet Function | Return error as string | Return error as string | Nothing (returns #NA! etc.) |
| Macro | Return error as string | Return error as string | Nothing (returns #NA! etc.) |
| Menu Item | Show error in a message box | Do nothing | Do nothing |
| Ribbon Action | Show error in a message box | Do nothing | Do nothing |
Custom Error Handlers
If none of the standard error handlers are suitable, you can provide your own error handler.
A custom error handler is a class that implements ErrorHandler, and is configured in the jinx.ini file using the full class name, e.g.:
[JINX]
error_handler = com.xxx.YourErrorHandler
Your custom error handler class should have a public constructor that either takes no parameters, or takes a single ExcelAddIn parameter.
If you only want to provide an implementation for part of the interface, you can use ExcelAddIn.getDefaultErrorHandler() to get the default error handler to use for the methods you don’t wish to implement.
