Error Handling

The AWS Flow Framework's cooperative cancellation mechanism allows in-flight activity tasks to be canceled gracefully. When cancellation is triggered, tasks that blocked or are waiting to be assigned to a worker are automatically canceled. If, however, a task is already assigned to a worker, the framework will request the activity to cancel. Your activity implementation must explicitly handle such cancellation requests. This is done by reporting heartbeat of your activity.

Reporting heartbeat allows the activity implementation to report the progress of an ongoing activity task, which is useful for monitoring, and it lets the activity check for cancellation requests. The recordActivityHeartbeat method will throw a CancellationException if a cancellation has been requested. The activity implementation can catch this exception and act on the cancellation request, or it can ignore the request by swallowing the exception. In order to honor the cancellation request, the activity should perform the desired clean up, if any, and then rethrow CancellationException. When this exception is thrown from an activity implementation, the framework records that the activity task has been completed in canceled state.

The following example shows an activity that downloads and processes images. It heartbeats after processing each image, and if cancellation is requested, it cleans up and rethrows the exception to acknowledge cancellation.

@Override
public void processImages(List<String> urls) {
    int imageCounter = 0;
    for (String url: urls) {
        imageCounter++;
        Image image = download(url);
        process(image);
        try {
            ActivityExecutionContext context 
                 = contextProvider.getActivityExecutionContext();
            context.recordActivityHeartbeat(Integer.toString(imageCounter));
        } catch(CancellationException ex) {
            cleanDownloadFolder();
            throw ex;
        }
    }
}
        
      

Reporting activity heartbeat is not required, but it is recommended if your activity is long running or may be performing expensive operations that you wish to be canceled under error conditions. You should call heartbeatActivityTask periodically from the activity implementation.

If the activity times out, the ActivityTaskTimedOutException will be thrown and getDetails on the exception object will return the data passed to the last successful call to heartbeatActivityTask for the corresponding activity task. The workflow implementation may use this information to determine how much progress was made before the activity task was timed out.

Note: It is not a good practice to heartbeat too frequently because Amazon SWF may throttle heartbeat requests. See the Amazon SWF Developer guide for limits placed by Amazon SWF.

Besides error conditions, there are other cases where you may explicitly cancel a task. For example, an activity to process payments using a credit card may need to be canceled if the user cancels the order. The framework allows you to explicitly cancel tasks created in the scope of a TryCatchFinally. In the following example, the payment task is canceled if a signal is received while the payment was being processed.

public class OrderProcessorImpl implements OrderProcessor {
    private PaymentProcessorClientFactory factory 
        = new PaymentProcessorClientFactoryImpl();
    boolean processingPayment = false;
    private TryCatchFinally paymentTask = null;

    @Override
    public void processOrder(int orderId, final float amount) {
        paymentTask = new TryCatchFinally() {
            
            @Override
            protected void doTry() throws Throwable {
                processingPayment = true;
                
                PaymentProcessorClient paymentClient = factory.getClient();
                paymentClient.processPayment(amount);
            }
            
            @Override
            protected void doCatch(Throwable e) throws Throwable {
                if (e instanceof CancellationException) {
                    paymentClient.log("Payment canceled.");
                } else {
                    throw e;
                }
            }
            
            @Override
            protected void doFinally() throws Throwable {
                processingPayment = false;
            }
        };

    }

    @Override
    public void cancelPayment() {
        if (processingPayment) {
            paymentTask.cancel(null);
        }
    }
}

    

When a task is completed in canceled state, the framework informs the workflow logic by throwing a CancellationException. When an activity completes in canceled state, a record is made in the history and the framework calls the appropriate doCatch() with a CancellationException. As shown in the previous example, when the payment processing task is canceled, the workflow receives a CancellationException.

An unhandled CancellationException is propagated up the execution branch just like any other exception. However, the doCatch() method will receive the CancellationException only if there is no other exception in the scope; other exceptions are prioritized higher than cancellation.