Handling errors and exceptions

With programmatic usage of the JBCL classes, most error handling is surfaced through JBCL extensions of the java.lang.Exception class. All dataset exception classes are of type DataSetException or its subclass.

The DataSetException class can have other types of exceptions chained to them, for example, java.io.IOException and java.sql.SQLException exceptions. In these cases the DataSetException has an appropriate message that describes the error from the perspective of a higher level API. The DataSetException method getExceptionChain() can be used to obtain any chained exceptions. The chained exceptions (a singly linked list) are non-DataSetException exceptions that were encountered at a lower level API.

The dataset package has some built-in DataSetException handling support for JBCL data-aware controls. The controls themselves don't know what a DataSetException is. They simply expect all of their data update and access operations to work, leaving the handling of errors to the built-in DataSetException.

For JBCL data aware controls, the default DataSetException error handling works as follows:

Overriding default DataSetException handling on controls

You can override part of the default error handling by registering a StatusEvent listener with the DataSet. This prevents ValidationException messages from displaying in the Exceptions dialog.

The default DataSetException handling for controls can be further disabled at the DataSet level by setting its displayErrors property to false. Because this is a property at the DataSet level, you need to set it for each DataSet in your application to effectively disable the default error handling for all DataSet objects in your application.

To completely control DataSetException handling for all JBCL controls and DataSet objects, create your own handler class and connect it to the ExceptionEvent listener of the DataSetException class.

Most of the events in the dataset package throw a DataSetException. This is very useful when your event handlers use dataSet APIs (which usually throw DataSetException). This releases you from coding try/catch logic for each event handler you write. Currently the JBuilder design tools do not insert the "throws DataSetException" clause in the source java code it generates, however you can add the clause yourself.