Error handling

Error catalogue

There is interface org.openhubframework.openhub.api.exception.ErrorExtEnum for defining own error catalogue that is displayed in admin GUI.

It allows consuments of your services to see possible error codes and be able to handle them.

Exceptions hierarchy

All OpenHub framework exceptions are in package org.openhubframework.openhub.api.exception:

  • IntegrationException: parent Exception for all OpenHub framework exceptions
    • LockFailureException: unsuccessful getting lock for the record from DB (most often it means that another process was faster and acquired lock before)
    • MultipleDataFoundException: one record was expected but more records were found
    • NoDataFoundException: at least one records was expected but no record was found
    • ThrottlingExceededException: this exception is thrown when throttling limits were exceeded
    • StoppingException: when OpenHub is in stopping mode then this exception will be thrown when new requests arrive
    • ValidationIntegrationException: input data are not valid
      • IllegalDataException: wrong data

How it works?

Basic algorithm of error handling is implemented in parent class of routes - org.openhubframework.openhub.api.route.AbstractBasicRoute.

Is message asynchronous?

If yes then next processing steps are determined according to exception/error type:

  • there is error that can't be resolved/repaired during next tries (e.g. wrong input data, wrong data in database etc.). Message state is changed to FAILED state because next processing doesn't have sense. Message processing is redirected to URI: AsynchConstants.URI_ERROR_FATAL
  • there is temporary error/exception where is chance to resolve/repair it in next tries (e.g. external system is unavailable, error because of concurrent message procesing etc.). Message state is changed to PARTLY_FAILED state. Message processing is redirected to URI: AsynchConstants.URI_ERROR_HANDLING - message will wait in this state for specified interval and then starts processing again.

Example of error handling in communication via Web Services with external system:

If not (=message is synchronous) then error handling is redirected to URL: AsynchConstants.URI_EX_TRANSLATION and then to ExceptionTranslator. Exception is propagated back to source system.

Custom error processing

Error handling concept in described in Apache Camel where you can find more details.

In common there are two types of error handling - routes specific and global, there are two ways how to catch exceptions - with Exception Clause or with DoTry Clause.

Mapping exceptions in WSDL

WSDL contract allows to define exceptions (aka faults) directly in operation definition.


Example of fault response with exception detail:

There is helper parent class AbstractSoapExceptionFilter for mapping SOAP fault exceptions (SoapFaultClientException) to internal Java exceptions from WSDL contract.

Example of CrmSoapExceptionFilter: