Interface ResponseHandler

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface ResponseHandler
A reactive handler invoked by a RequestExecutionEngine once per request as it completes, passed to RequestExecutionEngine.sendAll(ResponseHandler). Each call returns a Retention verdict deciding whether that result is kept in the terminal RequestExecutionResult or discarded.

Invocation is serial - at most one call is in progress at a time, in completion order - so handler-captured state needs no synchronization. The handler receives the live RequestExecution it is part of, which it can use to queue further requests into the same run or control the run via its lifetime.

RequestStatus.DROPPED requests (abandoned before sending when the run is cancelled) are not delivered to the handler, though they still appear in RequestExecutionResult.results().

Exceptions thrown by the handler are caught and logged; the run continues.

To flag "interesting" responses by how they differ from a baseline, build a Http.createResponseVariationsAnalyzer() or Http.createResponseKeywordsAnalyzer(java.util.List), feed it baseline responses, then Retention.DROP the responses that do not vary - the engine has no built-in "interesting" flag by design. 

 engine.sendAll((result, execution) -> {
     if (result.status() == RequestStatus.RESPONDED && isInteresting(result.requestResponse())) {
         execution.queue(followUpFor(result));   // keeps the run alive
         return Retention.KEEP;
     }
     return Retention.DROP;
 });