Stopping an extension when an acquisition stops

When an acquisition stops, it may take time for an extension within an acquisition to stop. Therefore, Oracle recommends that you provide a mechanism to stop an extension's runtime object in a more timely way (recall that a runtime object is either a DataSourceRuntime or a ManipulatorRuntime).

There are several requests or conditions that may cause CAS Server to stop an acquisition:

A CAS application developer requests a stop by running the stopCrawl task of the CAS Server Command-line Utility (cas-cmd).
A CAS application developer requests a stop by calling the stopCrawl() method of the CAS Server API.
A CAS Console user requests a stop by clicking Abort for the data source.
An acquisition may abort because it encounted a fatal error during the acquisition processing or record manipulation processing.

When an acquisition stops, it has the following effects in the CAS Extension API:

Calls to PipelineComponentRuntimeContext.isStopped() return true.
Calls to OutputChannel.output() throw a PipelineStoppedException exception.
Calls to ErrorChannel.discard() throw a PipelineStoppedException exception.
CAS Server calls PipelineComponentRuntime.stop() on all data source and manipulator extensions in the acquisition.

There are several mechanisms to stop an extension's runtime in a more timely way:

You can poll the PipelineComponentRuntimeContext.isStopped() method, and if it returns true, you throw a PipelineStoppedException and let the exception propagate through the system. There is example code that implements isStopped() in the CSV data source extension provided with the Content Acquisition System.
In addition to polling, you can override PipelineComponentRuntime.stop() on an extension. Your implementation of stop() should peform any tasks that help the extension stop more quickly, for example, terminating any pending network requests or closing or cancelling any output requests. This approach is particularly useful in situations where the extension is doing time-consuming work between calls to OutputChannel.output().