Example Service that Throws an Exception for Retry

This example shows one possible way to build a service that catches errors, checks errors to determine whether they are transient, and re-throws an error as an ISRuntimeException if it is transient. It includes the following basic sections of logic:

The catch sequence examines any exception that occurs in the try sequence, determines whether the exception is a transient error, and indicates whether Integration Server should retry the service.

The outer sequence is used so that the catch sequence is skipped when the try sequence is successful.

A throw exception step that executes only when the catch sequence indicates that a transient error occurred. It throws the ISRuntimeException to signal Integration Server that the service should be re-executed.

The outer sequence wraps the try sequence and the catch sequence. This sequence is set to exit on success so that it exits when either of its child steps (the try sequence or the catch sequence) execute successfully. If the try sequence executes successfully, Integration Server skips the catch sequence.

The try sequence contains the logic you want the service to execute. This sequence is set to exit on failure. As a result, if a step in this try sequence fails, Integration Server executes the next step, which is the catch sequence that checks for transient errors.

This step contains the logic that you want the service to perform. The service logic might consist of multiple services or flow steps.

When the service logic executes successfully, that means the try sequence is successful. Because the outer sequence exits on success, Integration Server exits the outer sequence, skipping the catch sequence. Integration Server executes the next step, which is the BRANCH on ‘/isTransientError’ step.

If an error occurs in the service logic, Integration Server exits the try sequence because it is set to exit on failure. As a result, Integration Server executes the catch sequence.

Integration Server only executes the catch sequence if the try sequence failed. The catch sequence contains logic that evaluates the error to determine whether the error is transient.

Because the catch sequence exits on DONE, the sequence is successful after Integration Server executes all the steps in the sequence. After the catch sequence is successful, the outer sequence, which is set to exit on success, also exits. Integration Server executes the next step, which is the BRANCH on ‘/isTransientError’ step.

To determine whether a transient error occurred, the catch sequence first invokes the pub.flow:getLastError service to catch the error that caused the try sequence to fail.

Important:

The pub.flow:getLastError service must be the first service invoked within the catch sequence. If it is not first and a preceding service in the catch sequence fails, the error thrown in the try sequence is overwritten with the new error.

This step evaluates the contents of the lastError document that the pub.flow:getLastError service returns to determine whether the try sequence failed because of a transient error. You might use multiple services or flow steps to determine whether a transient error occurred.

Note:

If the service logic in the try sequence includes an adapter service and a transient error occurs during adapter service execution, the adapter service throws an exception that extends the ISRuntimeException. Ensure that your catch sequence interprets the adapter service exception that signals retry. For more information, see Requirements for Retrying a Service.

This step sets the transient error flag based on whether the try sequence failed because of a transient error. In this example if a transient error occurred, the variable isTransientError) is set to “true”.

After this step executes, Integration Server exits the catch sequence, exits the outer sequence, and then executes the BRANCH on ‘/isTransientError’ step.

This step uses the value of isTransientError to determine whether the service should throw an ISRuntimeException.

If the try sequence executed successfully, isTransientError is null. As a result, Integration Server falls through to the end of the service because the value of the switch variable does not match any of the target steps. Integration Server will not attempt to retry the service.

If the try sequence failed, but the catch sequence determined that the error was not transient, the catch sequence does not set isTransientError to “true”. It might be null or the catch sequence might set isTransientError to another value, for example, “false”. Either way, Integration Server falls through to the end of the service because the value of the switch variable does not match any of the target steps. Integration Server will not attempt to retry the service.

If the try sequence failed and the catch sequence determined that the error was transient, isTransientError is “true”, and as a result, Integration Server executes the next step.

Integration Server executes this step to invoke pub.flow:throwExceptionForRetry service when the value of isTransientError is “true”. This service wraps the exception generated by the transient error in the try sequence and re-throws it as an ISRuntimeException.

If the service is configured for retry, Integration Server retries the service if the maximum number of retries has not been reached. For more information, see Configuring Service Retry.