Database application development is a feature of JBuilder Professional and Enterprise. Distributed application development is a feature of JBuilder Enterprise.
With programmatic usage of the DataExpress classes, most error handling is surfaced through DataExpress 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
.
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 dbSwing data-aware components. 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 dbSwing data-aware components, the default DataSetException
error handling works as follows:
DataSetException
to occur, an Exception dialog is presented with the message of the error. This Exception dialog has a Details button that displays the stack trace.
DataSetException
has chained exceptions, they can be viewed in the Exception dialog using the Previous and Next buttons.
ValidationException
(a subclass of DataSetException
), the Exception dialog displays only if there are no StatusEvent
listeners on the DataSet
, for example, the JdbStatusLabel
control. A ValidationException
is generated by a constraint violation, for example, a minimum or maximum value outside specified ranges, a data entry that doesn't meet an edit mask specification, an attempt at updating a read-only column, and so on. If a JdbStatusLabel
control is bound to a DataSet
, it automatically becomes a StatusEvent
listener. This allows users to see the messages resulting from constraint violations on the status label.
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 dbSwing 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.