Interface StreamsGroupTopologyDescriptionPlugin
- All Superinterfaces:
AutoCloseable, Configurable
@Public
@Evolving
public interface StreamsGroupTopologyDescriptionPlugin
extends Configurable, AutoCloseable
A broker-side plugin that stores, forwards, or exposes topology descriptions pushed
by Kafka Streams clients.
Implementations must be thread-safe. setTopology(String, int, StreamsGroupTopologyDescription) may be called
concurrently by multiple members of the same group; calls with the same
(groupId, topologyEpoch) carry identical data and must be idempotent.
deleteTopology(String) must also be idempotent — it may be called more than once
for the same groupId, including when nothing is stored.
-
Method Summary
Modifier and TypeMethodDescriptiondeleteTopology(String groupId) Remove any topology description stored for this group.getTopology(String groupId, int topologyEpoch) Return the stored topology description for(groupId, topologyEpoch), ornullif the plugin no longer has the data (e.g.setTopology(String groupId, int topologyEpoch, StreamsGroupTopologyDescription description) Store the topology description for a streams group.Methods inherited from interface AutoCloseable
closeMethods inherited from interface Configurable
configure
-
Method Details
-
setTopology
CompletableFuture<Void> setTopology(String groupId, int topologyEpoch, StreamsGroupTopologyDescription description) Store the topology description for a streams group.The returned future completes when the topology has been persisted or forwarded. Failures must be signalled by completing the future exceptionally — implementations must not throw synchronously; a synchronous throw is treated as a permanent failure with a generic client-visible error message. The completion exception drives broker-side behaviour:
StreamsTopologyDescriptionPermanentFailureException— the description will never be accepted at this topology epoch (e.g. too large, semantically rejected). The broker ratchetsLastFailedTopologyEpochand stops re-soliciting until the epoch advances.StreamsTopologyDescriptionTransientFailureExceptionor any other exception — treated as transient. The broker arms or extends the per-group back-off (30 s → 1 h, exponential) and re-solicits on a later heartbeat.
STREAMS_TOPOLOGY_DESCRIPTION_UPDATE_FAILEDwith the exception's message inErrorMessage; the permanent-vs-transient split is broker-internal state. -
deleteTopology
Remove any topology description stored for this group. Called when the group is deleted or expires. A failure (future completed exceptionally) is reported to the caller ofDeleteGroupsasGROUP_DELETION_FAILEDwith the exception message in the per-groupErrorMessage, and the broker does not tombstone the group; a retry ofDeleteGroupsre-invokes this method idempotently. The periodic-cleanup path treats a failure identically — the group's tombstone is deferred to a future cycle. -
getTopology
Return the stored topology description for(groupId, topologyEpoch), ornullif the plugin no longer has the data (e.g. backend wipe). If the future completes exceptionally, the broker reports a read error for the group.
-