com.smartgwt.client.docs

Interface ErrorHandling

public interface ErrorHandling

Error Handling Overview

RPCResponse and DSResponse objects have an integer status field that the RPCManager inspects when the response is received from the server. If the value of this field is less than zero, the request is considered to have failed. Otherwise it is considered to have succeeded. This value is settable via the setStatus() method call on the server-side DSResponse and RPCResponse objects.

Errors in a Smart GWT application fall into two main categories:

• Validation errors, which arise as a result of rules in the application's business logic being broken. These are part of the normal operation of the system. A response with validation errors has a status of STATUS_VALIDATION_ERROR
• Unrecoverable errors, which are errors with the system itself. These are not part of the normal operation of the system

Validation errors occur when an add, or update operation contains values that do not conform to specified validation rules. When a user is saving or validating edits in a databound component such as a DynamicForm or canEdit:true ListGrid, validation errors are handled by redrawing the component to display those errors to the user.

How the user sees those errors is completely configurable - for example, see the DynamicForm properties showErrorIcons, showErrorText, showInlineErrors, and indeed most DynamicForm properties that contain the word "Error" - but the default in most skins is to highlight the field with some kind of error icon, and provide the actual error text message in a floating box when the user hovers over the field.

Note that the centralized HandleErrorCallback.handleError() method (see below) will not be invoked for validation errors that occurred while editing data in a component.

Validation errors can also occur when application code directly invokes dataSource APIs to save data instead of calling saveData() on an edit component. (See DataSource.addData(), DataSource.updateData()). In this case, since there is no component in which validation errors can be displayed, centralized error handling will be invoked by default.

In addition to validation errors, RPCRequests and DSRequests can fail due to errors with the system itself. For example:

• A network transport problem
• A server-side crash
• An update failed because a transaction was rolled back

Errors like this can either be handled centrally, or you can choose to handle them in your regular callback code. The RPCRequest.willHandleError attribute determines whether or not central error handling will be invoked.

Centralized Error Handling
If the status field for a request shows a failure, and willHandleError has not been set to true for, HandleErrorCallback.handleError() will be invoked, (unless the error was a validation error occurring while editing data in a DataBoundComponent, as discussed above).

By default, RPCManager.handleError() logs a warning and shows a dialog with the contents of the response's data field (which is assumed to contain a meaningful description of the error that occurred). If you specified a callback in your request, it will not be called.

This default behavior means that any Smart GWT application has a basic handling mechanism for unrecoverable errors, without any code to write.

You can customize centralized error handling at two levels:

• Use RPCManager.setHandleErrorCallback(com.smartgwt.client.rpc.HandleErrorCallback) to provide your own error handling logic (note that customization takes place at the static class level, not per-instance)
• Use RPCManager.setHandleTransportErrorCallback(com.smartgwt.client.rpc.HandleTransportErrorCallback). This logic is called earlier than handleError, and it is called even when you are using custom error handling (discussed below). It is intended to allow your code to inspect the failed response early in the handling flow, to see if it is really unrecoverable. For example, a failure might have happened because of a temporary network problem, so resubmitting the request may be a valid thing to do to try to resolve the error. Note, as with handleError, this is a static class-level customization

Custom Error Handling
As an alternative to handling errors centrally, you can handle them in your regular callback methods. To do this, specify willHandleError as a request property. When you do this, HandleErrorCallback.handleError() is bypassed, and your callback is invoked as normal. If you want to invoke the default error handling logic in your callback, you can use RPCManager.runDefaultErrorHandling()

Note: if handleTransportError() was configured it will be called for error codes indicating a transport error even if willHandleError is true.

For willHandleError:true requests, your callback code can determine that it is in error state by inspecting the status property on the response. Any value less than zero indicates an error. See the documented status codes such as STATUS_FAILURE for more information on specific error codes that may be returned by the Smart GWT server.

Note that if validation failed for a save request on an edit component, setting willHandleError to true will cause your callback to be invoked, but the normal behavior of populating the field errors onto the form and redrawing it also takes place.

Note, when you are handling errors in user callbacks, an error status other than STATUS_VALIDATION_ERROR typically indicates some sort of serious, unrecoverable error. Therefore, ensure that your error handling code does not assume that the response will be properly formed or contain particular elements.

You can specify willHandleError (or any other DSRequest/RPCRequest property) on a component request by providing the DSRequest Properties parameter. For example, on a ListGrid.fetchData():

      DSRequest properties = new DSRequest();
      properties.setWillHandleError(true);
      listGrid.fetchData(new Criteria(), new DSCallback() {
          public void execute(DSResponse response, Object rawData, DSRequest request) {
              if (response.getStatus() < 0) {
                  // Error handling here
              } else {
                  // Normal processing here
              }
          }
      }, properties);
  

Error Status Codes
The error status codes used by the framework are documented as class variables of the RPCResponse class. Status codes in the range -1 to -100 are reserved for use by the framework; if you wish to introduce new custom error statuses for your own use, avoid this range.

Errors indicating login is required
Some of the framework error statuses indicate that login is required, typically because a user's HTTP session has timed out. The best way to handle this situation is to use the built-in re-login flow to automatically prompt users to log back in as required, and then resubmit the requests that triggered the login required response.

Errors during a file download

If the server responds to a file download request with an error status code, standard error handling will be invoked.

This includes:

• export operations such as exportData(), exportClientData(), or exportContent().
• downloading of binary field values via DataSource.downloadFile()
• custom download operations where the RPCRequest.downloadResult flag is set

However if a server encounters an error while streaming a response to the browser this will not trigger HandleErrorCallback.handleError() and the centralized error handling pathway.

Therefore if you have an error condition that could arise in the middle of a file download, best practice is to:

• pre-validate the request: do an ordinary, non-download request to check all common error conditions, before the request that actually initiates a download. This can avoid problems like a user who tries to download after their session has timed out, or tries to download a file that another user has deleted
• return a valid file containing a user-friendly error message: for example, if the download is for an Excel spreadsheet but the database was unexpectedly unavailable, return a valid spreadsheet containing just the error message.

Unrecoverable server error handling
Unrecoverable server Exception will be written to HTTP response as a warning containing the exception message. Depending on framework setting servlet.sendStackTraceToClient (boolean) exception stacktrace can also be included.

See Also:

com.smartgwt.client.data.DataSource#getSimpleErrors, HandleErrorCallback.handleError(com.smartgwt.client.data.DSResponse, com.smartgwt.client.data.DSRequest), RPCManager.runDefaultErrorHandling(com.smartgwt.client.data.DSResponse, com.smartgwt.client.data.DSRequest), HandleTransportErrorCallback.handleTransportError(int, int, int, java.lang.String), ErrorEvent, FormItem.clearErrors(), FormItem.setErrors(java.lang.String), FormItem.hasErrors(), DSResponse.getStatus(), DSResponse.getQueueStatus(), DSResponse.getErrors(), com.smartgwt.client.data.DSRequest#getCallback, com.smartgwt.client.rpc.RPCRequest#getCallback, RPCRequest.getWillHandleError()