Stop Strategy

Purpose

The Stop Strategy provides a fail-safe mechanism for Kafka consumers by immediately stopping consumption when a polling exception occurs. This approach prevents the consumer from continuously encountering errors that could lead to resource exhaustion or inconsistent state. It is particularly useful in scenarios where continued consumption after certain exceptions would be harmful or when manual intervention is preferred before resuming.

Functionality

Upon a polling exception detected during the Kafka consumer's fetch cycle, the Stop Strategy intervenes to halt further polling and processing. Its core behaviors include:

• Immediate Halt: The strategy sets a flag to prevent continuation of the polling loop.

• Consumer Termination: It signals the fetch task to mark the consumer as disconnected, effectively stopping message retrieval.

• Retry Control: It disallows retries by toggling an internal retry flag to false.

• Reset Capability: Upon reset (e.g., consumer restart), it re-enables the possibility to continue if needed.

This ensures that once an error triggers the Stop Strategy, the consumer ceases operation until explicitly reset or restarted, avoiding further error propagation.

Key Methods and Workflow

• handle(long partitionLastOffset, Exception exception): Invoked when a polling exception occurs. Logs a warning, disables retries, and instructs the fetcher to stop consuming.

• canContinue(): Returns whether the consumer should keep running. After an error triggers stopping, it returns false.

• reset(): Resets the strategy to allow continuation again, used when restarting the consumer.

Critical Interaction Snippet

@Override
public void handle(long partitionLastOffset, Exception exception) {
    LOG.warn("Requesting the consumer to stop based on polling exception strategy");
    retry = false;
    recordFetcher.setConnected(false); // Stops the consumer fetch loop
}

@Override
public boolean canContinue() {
    return retry; // False after an error triggers stop
}

Integration

The Stop Strategy integrates tightly with the Kafka consumer's fetch mechanism (`KafkaFetchRecords`) through the `PollExceptionStrategy` interface. It complements other error handling strategies by providing a conservative, defensive approach:

• Unlike Retry or Reconnect strategies which attempt to recover and continue, the Stop Strategy opts for immediate shutdown.

• It interacts with the fetch task by setting its connected state to false, halting the polling loop.

• It fits within the consumer's error handling framework, allowing users to configure when to stop vs. retry or bridge errors.

• Works alongside commit managers and manual commit support by ensuring no further offsets are committed after stopping.

• When combined with health checks and monitoring, stopping the consumer triggers alerts or recovery workflows externally.

By halting on error, this strategy prevents repeated error cycles that could interfere with offset management, message processing guarantees, or resource stability. It is ideal for critical systems where failing fast and requiring operator intervention is preferable to risking inconsistent consumption.

Diagram

flowchart TD
    A[Start Kafka Consumer Fetch Loop] --> B[Poll Kafka for Records]
    B --> C{Polling Exception Occurs?}
    C -- No --> D[Process Records]
    D --> B
    C -- Yes --> E[Invoke StopErrorStrategy.handle()]
    E --> F[Log Warning and Set retry = false]
    F --> G[Set recordFetcher.connected = false]
    G --> H[Stop Polling Loop]

This flowchart illustrates the consumer's fetch cycle interruption triggered by the Stop Strategy upon encountering a polling exception.

By stopping the consumer decisively on errors, the Stop Strategy ensures controlled shutdown and prevents compounding failures, supporting robust Kafka consumption workflows within Apache Camel.