KafkaConstants.java

Overview

`KafkaConstants.java` is a utility class within the Apache Camel Kafka component (`org.apache.camel.component.kafka` package) that defines a centralized set of constant string keys used primarily as message header keys and configuration identifiers. These constants facilitate the consistent exchange of metadata and control information between Camel routes and Kafka producers/consumers.

This class provides metadata annotations for better integration with Camel tooling, enabling automatic documentation, validation, and configuration assistance. It includes constants used for specifying Kafka message attributes like partition, topic, offset, keys, timestamps, headers, and manual commit control.

As a final class with a private constructor, it is designed solely as a static constant holder and cannot be instantiated or extended.

Detailed Explanation of Contents

Class: `KafkaConstants`

Purpose:
Holds static final string constants representing Kafka-related headers and configuration keys used throughout the Camel Kafka component.
Modifiers: public final
Prevents subclassing and ensures constants cannot be modified.
Constructor:
- private KafkaConstants() — Private to prevent instantiation.

Constants

Each constant is a `public static final String` representing a key used in Camel Kafka message headers or configuration.

Constant Name	Description	Java Type	Label(s)	Deprecated
`PARTITION_KEY`	Producer: Specifies the partition explicitly to which the message will be sent.	`Integer`	producer	No
`PARTITION`	Consumer: The partition where the consumed message was stored.	`Integer`	consumer	No
`KEY`	Producer: The key of the message to ensure related messages go to the same partition. Consumer: The key if configured.	Object	producer, consumer	No
`TOPIC`	Consumer: The topic from which the message originated.	`String`	consumer	No
`OVERRIDE_TOPIC`	Producer: Overrides the topic to which the message is sent. This header is not preserved after sending.	`String`	producer	No
`OFFSET`	Consumer: The offset of the message in the Kafka topic partition.	`Long`	consumer	No
`HEADERS`	Consumer: The Kafka record headers associated with the message.	`org.apache.kafka.common.header.Headers`	consumer	No
`LAST_RECORD_BEFORE_COMMIT`	Consumer: Indicates if this is the last record before a commit when `autoCommitEnable` is `false`.	`Boolean`	consumer	No
`LAST_POLL_RECORD`	Consumer: Indicates the last record within the current poll request when manual commit control is enabled.	`Boolean`	consumer	No
`TIMESTAMP`	Consumer: The timestamp of the message.	`Long`	consumer	No
`OVERRIDE_TIMESTAMP`	Producer: Overrides the message timestamp. The header is not preserved after sending.	`Long`	producer	No
`KAFKA_DEFAULT_ENCODER`	(Deprecated) Default Kafka encoder class name used previously.	`String`	N/A	Yes
`KAFKA_STRING_ENCODER`	(Deprecated) Kafka string encoder class name used previously.	`String`	N/A	Yes
`KAFKA_DEFAULT_SERIALIZER`	Default Kafka serializer class name used for serializing messages.	`String`	N/A	No
`KAFKA_DEFAULT_DESERIALIZER`	Default Kafka deserializer class name used for deserializing messages.	`String`	N/A	No
`PARTITIONER_RANGE_ASSIGNOR`	Kafka consumer partition assignment strategy class name (`RangeAssignor`).	`String`	N/A	No
`KAFKA_RECORD_META`	Producer: Metadata about the record (available if `recordMetadata` endpoint parameter is `true`).	`List`	producer	No
`MANUAL_COMMIT`	Consumer: Used to trigger manual offset commits in Kafka consumer.	org.apache.camel.component.kafka.consumer.KafkaManualCommit	consumer	No
`KAFKA_SUBSCRIBE_ADAPTER`	Internal use key related to subscription adapter.	`String`	N/A	No

Metadata Annotations

The constants are annotated with @Metadata from Camel's SPI, which enriches each constant with:
- Label: Indicates whether the constant is related to producer or consumer functionality.
- Description: Explains the purpose and behavior of the constant.
- JavaType: Specifies the expected type of the header value.
- Required: Some constants are marked as required.

These annotations assist tooling, documentation generators, and validation mechanisms within the Apache Camel ecosystem.

Usage Examples

Setting a Kafka Message Partition

exchange.getIn().setHeader(KafkaConstants.PARTITION_KEY, 3);

This forces the producer to send the message to partition 3 explicitly.

Reading the Topic of a Consumed Message

String topic = exchange.getIn().getHeader(KafkaConstants.TOPIC, String.class);

Obtains the topic name from which the message was consumed.

Manual Commit Control

KafkaManualCommit manualCommit = exchange.getIn().getHeader(KafkaConstants.MANUAL_COMMIT, KafkaManualCommit.class);
if (manualCommit != null) {
    manualCommit.commitSync();
}

Used in consumer routes where auto commit is disabled to manually commit the offset.

Important Implementation Details

The class is designed strictly as a constants holder; it contains no logic or state.
Deprecated constants indicate migration away from older Kafka serializers to newer ones.
Constants like OVERRIDE_TOPIC and OVERRIDE_TIMESTAMP specify behavior where the header value overrides the default Kafka record property and is not preserved after the message is sent.
Manual commit constants support finer control over offset management in consumers, which is critical for exactly-once processing semantics.
The usage of @Metadata annotations integrates with Camel's model for enhanced developer experience.

Interaction with Other System Components

Apache Camel Kafka Component:
The constants are used throughout the Kafka component's producers and consumers for setting and reading Kafka message metadata via Camel message headers.
Kafka Client API:
Some constants correspond to Kafka's ProducerRecord and ConsumerRecord properties, enabling transparent handling of Kafka internals.
Camel Routes and Processors:
Developers use these constants to interact programmatically with Kafka messages inside Camel routes, filters, and processors.
Manual Offset Commit Handling:
The MANUAL_COMMIT constant ties into the custom KafkaManualCommit class, enabling manual offset commits controlled by the Camel consumer logic.

Class Diagram

classDiagram
    class KafkaConstants {
        <<final>>
        +String PARTITION_KEY
        +String PARTITION
        +String KEY
        +String TOPIC
        +String OVERRIDE_TOPIC
        +String OFFSET
        +String HEADERS
        +String LAST_RECORD_BEFORE_COMMIT
        +String LAST_POLL_RECORD
        +String TIMESTAMP
        +String OVERRIDE_TIMESTAMP
        +String KAFKA_DEFAULT_ENCODER <<deprecated>>
        +String KAFKA_STRING_ENCODER <<deprecated>>
        +String KAFKA_DEFAULT_SERIALIZER
        +String KAFKA_DEFAULT_DESERIALIZER
        +String PARTITIONER_RANGE_ASSIGNOR
        +String KAFKA_RECORD_META
        +String MANUAL_COMMIT
        +String KAFKA_SUBSCRIBE_ADAPTER
        -KafkaConstants()
    }

Summary

The `KafkaConstants` class serves as a foundational contract defining Kafka-related message header keys and configuration constants used by Apache Camel's Kafka component. It standardizes the communication of Kafka metadata within Camel routes, enabling producers and consumers to manage topics, partitions, keys, offsets, timestamps, and manual commit operations effectively. Its design as a static constants utility class with rich metadata annotations facilitates maintainability, tooling integration, and developer usability.