Skip to main content

confluent_kafka/common/
topic_collection.rs

1// Copyright 2025 Confluent Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! A collection of topics defined by name or ID.
16//!
17//! Corresponds to `org.apache.kafka.common.TopicCollection`. Its nested
18//! subclasses, [`TopicIdCollection`] and [`TopicNameCollection`], are reached
19//! through this module, as CLAUDE.md ยง2 provides for nested classes.
20
21use crate::common::Uuid;
22
23/// A class used to represent a collection of topics. This collection may
24/// define topics by name or ID.
25///
26/// # Translation notes
27///
28/// An enum whose variants wrap Java's two subclasses.
29#[derive(Clone, Debug)]
30#[non_exhaustive]
31#[doc(alias = "org.apache.kafka.common.TopicCollection")]
32pub enum TopicCollection {
33    /// A collection of topics defined by their topic ID
34    /// (`TopicCollection.TopicIdCollection`).
35    TopicIds(TopicIdCollection),
36    /// A collection of topics defined by their topic name
37    /// (`TopicCollection.TopicNameCollection`).
38    TopicNames(TopicNameCollection),
39}
40
41impl TopicCollection {
42    /// Returns a collection of topics defined by topic ID.
43    ///
44    /// # Arguments
45    ///
46    /// - `topics` - the topic IDs
47    #[doc(alias = "org.apache.kafka.common.TopicCollection#ofTopicIds")]
48    pub fn of_topic_ids(topics: Vec<Uuid>) -> TopicCollection {
49        TopicCollection::TopicIds(TopicIdCollection::new(topics))
50    }
51
52    /// Returns a collection of topics defined by topic name.
53    ///
54    /// # Arguments
55    ///
56    /// - `topics` - the topic names
57    #[doc(alias = "org.apache.kafka.common.TopicCollection#ofTopicNames")]
58    pub fn of_topic_names(topics: Vec<String>) -> TopicCollection {
59        TopicCollection::TopicNames(TopicNameCollection::new(topics))
60    }
61}
62
63/// A class used to represent a collection of topics defined by their topic ID.
64/// Subclassing this class beyond the classes within this file is not supported.
65///
66/// # Translation notes
67///
68/// Built only by [`TopicCollection::of_topic_ids`].
69#[derive(Clone, Debug)]
70#[doc(alias = "org.apache.kafka.common.TopicCollection$TopicIdCollection")]
71pub struct TopicIdCollection {
72    topic_ids: Vec<Uuid>,
73}
74
75impl TopicIdCollection {
76    /// Translated from the private constructor `TopicIdCollection(Collection<Uuid>)`.
77    #[doc(alias = "org.apache.kafka.common.TopicCollection$TopicIdCollection#TopicIdCollection")]
78    fn new(topic_ids: Vec<Uuid>) -> Self {
79        Self { topic_ids }
80    }
81
82    /// Returns a collection of topic IDs.
83    #[doc(alias = "org.apache.kafka.common.TopicCollection$TopicIdCollection#topicIds")]
84    pub fn topic_ids(&self) -> &[Uuid] {
85        &self.topic_ids
86    }
87}
88
89/// A class used to represent a collection of topics defined by their topic name.
90/// Subclassing this class beyond the classes within this file is not supported.
91///
92/// # Translation notes
93///
94/// Built only by [`TopicCollection::of_topic_names`].
95#[derive(Clone, Debug)]
96#[doc(alias = "org.apache.kafka.common.TopicCollection$TopicNameCollection")]
97pub struct TopicNameCollection {
98    topic_names: Vec<String>,
99}
100
101impl TopicNameCollection {
102    /// Translated from the private constructor `TopicNameCollection(Collection<String>)`.
103    #[doc(alias = "org.apache.kafka.common.TopicCollection$TopicNameCollection#TopicNameCollection")]
104    fn new(topic_names: Vec<String>) -> Self {
105        Self { topic_names }
106    }
107
108    /// Returns a collection of topic names.
109    #[doc(alias = "org.apache.kafka.common.TopicCollection$TopicNameCollection#topicNames")]
110    pub fn topic_names(&self) -> &[String] {
111        &self.topic_names
112    }
113}
114
115#[cfg(test)]
116mod tests {
117    use super::*;
118
119    #[test]
120    fn of_topic_ids() {
121        let ids = vec![Uuid::new(1, 2), Uuid::new(3, 4)];
122        let collection = TopicCollection::of_topic_ids(ids.clone());
123        let TopicCollection::TopicIds(by_id) = &collection else {
124            panic!("ofTopicIds builds a TopicIdCollection, got {collection:?}");
125        };
126        assert_eq!(by_id.topic_ids(), ids.as_slice());
127    }
128
129    #[test]
130    fn of_topic_names() {
131        let names = vec!["a".to_string(), "b".to_string()];
132        let collection = TopicCollection::of_topic_names(names.clone());
133        let TopicCollection::TopicNames(by_name) = &collection else {
134            panic!("ofTopicNames builds a TopicNameCollection, got {collection:?}");
135        };
136        assert_eq!(by_name.topic_names(), names.as_slice());
137    }
138
139    /// Translated from `TopicCollectionTest.testTopicCollection`: the collections hand back
140    /// the topics they were built from.
141    #[test]
142    fn test_topic_collection() {
143        let topic_ids = vec![Uuid::random_uuid(), Uuid::random_uuid(), Uuid::random_uuid()];
144        let topic_names = vec!["foo".to_string(), "bar".to_string()];
145
146        let TopicCollection::TopicIds(id_collection) = TopicCollection::of_topic_ids(topic_ids.clone()) else {
147            panic!("ofTopicIds builds a TopicIdCollection");
148        };
149        let TopicCollection::TopicNames(name_collection) = TopicCollection::of_topic_names(topic_names.clone()) else {
150            panic!("ofTopicNames builds a TopicNameCollection");
151        };
152
153        assert!(topic_ids.iter().all(|id| id_collection.topic_ids().contains(id)));
154        assert!(topic_names.iter().all(|name| name_collection.topic_names().contains(name)));
155    }
156}