[KIEKER-118] Provide standard way to run AnalysisController asynchronously

[rju]

JIRA Issue: KIEKER-118 Provide standard way to run AnalysisController asynchronously Original Reporter: Andre van Hoorn

---

Currently, the way to set-up and start a Kieker analysis instance is the following:

final IMonitoringReader reader = ...
final IMonitoringRecordConsumerPlugin receiver = ...

final AnalysisController analysis = new AnalysisController();
analysis.setReader(reader);
analysis.registerPlugin(receiver);
analysis.run();

... // code after analysis

The "code after analysis" is only executed after the analysis terminated.
Particularly, this means that the reader has terminated after an asynchronous invocation. This is perfectly fine for readers like the file system readers. However, readers that "passively" receives records (e.g. from Pipes, JMX servers, or JMS queues) basically never terminate. Instead, we would like to terminate these analysis instances explicitly.

[rju]

author André van Hoorn -- Fri, 2 Sep 2011 20:10:57 +0200

Added a terminate() method to the AnalysisController:

    /**
     * Initiates a termination of the analysis. 
     */
    public void terminate() {
        /* terminate the reader. After the reader has terminated, the run method()
         * will terminate all plugins */
        AnalysisController.log.info("Explicit termination of the analysis. Terminating the reader ...");
        this.logReader.terminate();
    }

Therefore, the IMonitoringReader interface has been extended by the following method:

    /**
     * Initiates a termination of the reader. This method is only used by the 
     * framework and should not be called manually to register a receiver. Use 
     * the method {link AnalysisController#terminate()} instead.
     * 
     * After receiving this notification, 
     * the reader should terminate its {link #read()} method. 
     */
    public void terminate();

The new class AnalysisControllerThread (extending the Thread class) takes an initialized AnalysisController as input and starts it in its start() method. The asynchronously running instance can be terminated by calling the AnalysisControllerThread's terminate method().

Now, the initialization and the asynchronous start of an AnalysisController looks like this:

final IMonitoringReader reader = ...
final IMonitoringRecordConsumerPlugin receiver = ...

final AnalysisController analysis = new AnalysisController();
analysis.setReader(reader);
analysis.registerPlugin(receiver);
final AnalysisControllerThread analysisThread = new AnalysisControllerThread(analysis);
analysisThread.start();

... // do some work

analysisThread.terminate();

[rju]

author André van Hoorn -- Fri, 2 Sep 2011 22:21:12 +0200

Committed in [/changeset/1786/kieker].

Some readers need to refine their terminate() method ( KIEKER-453 Done ).