Skip to content

Commit e8e6450

Browse files
saurotersauroter
committed
Finished javadocs.
1 parent 2d1c574 commit e8e6450

File tree

7 files changed

+265
-24
lines changed

7 files changed

+265
-24
lines changed

‎src/main/java/com/hivemq/extensions/kafka/api/builders/KafkaRecordBuilder.java

Lines changed: 139 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
* See the License for the specific language governing permissions and
1414
* limitations under the License.
1515
*/
16+
1617
package com.hivemq.extensions.kafka.api.builders;
1718

1819
import com.hivemq.extension.sdk.api.annotations.NotNull;
@@ -22,39 +23,169 @@
2223
import java.nio.charset.Charset;
2324

2425
/**
26+
* The KafkaRecordBuilder enables the creation of {@link KafkaRecord}s via its fluent API.
27+
* <p>
28+
* All data in a {@link KafkaRecord} except the topic is optional. Ensure that you set an topic via the {@link
29+
* KafkaRecordBuilder#topic(String)} method before you call {@link KafkaRecordBuilder#build()}.
30+
* <p>
31+
* The internal state of this interface can only be changed via its methods. All arguments, that have mutable data
32+
* types, are deep copied before the setting method returns.
33+
*
2534
* @author Christoph Schäbel
35+
* @author Georg Held
36+
* @since 4.4.0
2637
*/
2738
public interface KafkaRecordBuilder {
2839

40+
/**
41+
* Set the topic of the Kafka record.
42+
* <p>
43+
* This is required to successfully build a {@link KafkaRecord}.
44+
*
45+
* @param topic the name of the topic.
46+
* @return this builder
47+
* @since 4.4.0
48+
*/
2949
@NotNull KafkaRecordBuilder topic(@NotNull String topic);
3050

31-
@NotNull KafkaRecordBuilder header(@NotNull String key, @NotNull ByteBuffer value);
32-
33-
@NotNull KafkaRecordBuilder header(@NotNull String key, @NotNull byte[] value);
34-
35-
@NotNull KafkaRecordBuilder header(@NotNull String key, @NotNull String value);
36-
37-
@NotNull KafkaRecordBuilder header(@NotNull String key, @NotNull String value, @NotNull Charset charset);
38-
51+
/**
52+
* Set the key of the Kafka record.
53+
*
54+
* @param key the value of the key.
55+
* @return this builder
56+
* @since 4.4.0
57+
*/
3958
@NotNull KafkaRecordBuilder key(@NotNull ByteBuffer key);
4059

60+
/**
61+
* Set the key of the Kafka record.
62+
*
63+
* @param key the value of the key.
64+
* @return this builder
65+
* @since 4.4.0
66+
*/
4167
@NotNull KafkaRecordBuilder key(@NotNull byte[] key);
4268

69+
/**
70+
* Set the key of the Kafka record.
71+
*
72+
* @param key the value of the key. {@link java.nio.charset.StandardCharsets#UTF_8} is used for encoding.
73+
* @return this builder
74+
* @since 4.4.0
75+
*/
4376
@NotNull KafkaRecordBuilder key(@NotNull String key);
4477

78+
/**
79+
* Set the key of the Kafka record.
80+
*
81+
* @param key the value of the key.
82+
* @param charset the {@link Charset} used for encoding.
83+
* @return this builder
84+
* @since 4.4.0
85+
*/
4586
@NotNull KafkaRecordBuilder key(@NotNull String key, @NotNull Charset charset);
4687

88+
/**
89+
* Set the value of the Kafka record.
90+
*
91+
* @param value the value of the Kafka value.
92+
* @return this builder
93+
* @since 4.4.0
94+
*/
4795
@NotNull KafkaRecordBuilder value(@NotNull ByteBuffer value);
4896

97+
/**
98+
* Set the value of the Kafka record.
99+
*
100+
* @param value the value of the Kafka value.
101+
* @return this builder
102+
* @since 4.4.0
103+
*/
49104
@NotNull KafkaRecordBuilder value(@NotNull byte[] value);
50105

106+
/**
107+
* Set the value of the Kafka record.
108+
*
109+
* @param value the value of the Kafka value. {@link java.nio.charset.StandardCharsets#UTF_8} is used for encoding.
110+
* @return this builder
111+
* @since 4.4.0
112+
*/
51113
@NotNull KafkaRecordBuilder value(@NotNull String value);
52114

115+
/**
116+
* Set the value of the Kafka record.
117+
*
118+
* @param value the value of the Kafka value.
119+
* @param charset the {@link Charset} used for encoding.
120+
* @return this builder
121+
* @since 4.4.0
122+
*/
53123
@NotNull KafkaRecordBuilder value(@NotNull String value, @NotNull Charset charset);
54124

125+
/**
126+
* Add a header to the Kafka record.
127+
*
128+
* @param key the key of the header.
129+
* @param value the value of the header.
130+
* @return this builder
131+
* @since 4.4.0
132+
*/
133+
@NotNull KafkaRecordBuilder header(@NotNull String key, @NotNull ByteBuffer value);
134+
135+
/**
136+
* Add a header to the Kafka record.
137+
*
138+
* @param key the key of the header.
139+
* @param value the value of the header.
140+
* @return this builder
141+
* @since 4.4.0
142+
*/
143+
@NotNull KafkaRecordBuilder header(@NotNull String key, @NotNull byte[] value);
144+
145+
/**
146+
* Add a header to the Kafka record.
147+
*
148+
* @param key the key of the header.
149+
* @param value the value of the header. {@link java.nio.charset.StandardCharsets#UTF_8} is used for encoding.
150+
* @return this builder
151+
* @since 4.4.0
152+
*/
153+
@NotNull KafkaRecordBuilder header(@NotNull String key, @NotNull String value);
154+
155+
/**
156+
* Add a header to the Kafka record.
157+
*
158+
* @param key the key of the header.
159+
* @param value the value of the header.
160+
* @param charset the {@link Charset} used for encoding the {@code value}.
161+
* @return this builder
162+
* @since 4.4.0
163+
*/
164+
@NotNull KafkaRecordBuilder header(@NotNull String key, @NotNull String value, @NotNull Charset charset);
165+
166+
/**
167+
* Set the timestamp of the Kafka record.
168+
*
169+
* @param timestamp the value of the Kafka timestamp.
170+
* @return this builder
171+
* @since 4.4.0
172+
*/
55173
@NotNull KafkaRecordBuilder timestamp(long timestamp);
56174

175+
/**
176+
* Set the partition number of the Kafka record.
177+
*
178+
* @param partition the value of the Kafka partition number.
179+
* @return this builder
180+
* @since 4.4.0
181+
*/
57182
@NotNull KafkaRecordBuilder partition(int partition);
58183

184+
/**
185+
* Create a new {@link KafkaRecord} from the current state of this builder. The builder can be reused afterwards.
186+
*
187+
* @return a new {@link KafkaRecord} containing a snapshot of the current state of this builder.
188+
* @throws NullPointerException if the topic was not set.
189+
*/
59190
@NotNull KafkaRecord build();
60191
}

‎src/main/java/com/hivemq/extensions/kafka/api/model/KafkaCluster.java

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,33 @@
1313
* See the License for the specific language governing permissions and
1414
* limitations under the License.
1515
*/
16+
1617
package com.hivemq.extensions.kafka.api.model;
1718

19+
import com.hivemq.extension.sdk.api.annotations.DoNotImplement;
20+
import com.hivemq.extension.sdk.api.annotations.Immutable;
1821
import com.hivemq.extension.sdk.api.annotations.NotNull;
1922

2023
/**
24+
* This interface provides information about a {@code <kafka-cluster>} as it is configured in the {@code
25+
* kafka-extension.xml}.
26+
*
2127
* @author Christoph Schäbel
28+
* @author Georg Held
29+
* @since 4.4.0
2230
*/
23-
public
24-
interface KafkaCluster {
31+
@Immutable
32+
@DoNotImplement
33+
public interface KafkaCluster {
2534

35+
/**
36+
* @return the configured {@code <id>} of the luster.
37+
* @since 4.4.0
38+
*/
2639
@NotNull String getId();
2740

41+
/**
42+
* @return the configured {@code <bootstrap-servers>} of the cluster.
43+
*/
2844
@NotNull String getBootstrapServers();
29-
3045
}

‎src/main/java/com/hivemq/extensions/kafka/api/model/KafkaHeader.java

Lines changed: 36 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,26 +13,59 @@
1313
* See the License for the specific language governing permissions and
1414
* limitations under the License.
1515
*/
16+
1617
package com.hivemq.extensions.kafka.api.model;
1718

19+
import com.hivemq.extension.sdk.api.annotations.DoNotImplement;
20+
import com.hivemq.extension.sdk.api.annotations.Immutable;
1821
import com.hivemq.extension.sdk.api.annotations.NotNull;
1922

2023
import java.nio.ByteBuffer;
2124
import java.nio.charset.Charset;
2225

2326
/**
27+
* * Represents the header of a Kafka record, that was either read from or should be written to a Kafka cluster.
28+
* <p>
29+
* The internal state of this interface is completely immutable. All returned {@link ByteBuffer}s are read only and a
30+
* deep copy of any {@code byte[]} is made for every method call returning one.
31+
*
2432
* @author Christoph Schäbel
33+
* @author Georg Held
34+
* @since 4.4.0
2535
*/
36+
@Immutable
37+
@DoNotImplement
2638
public interface KafkaHeader {
2739

40+
/**
41+
* @return the key of this header.
42+
* @since 4.4.0
43+
*/
2844
@NotNull String getKey();
2945

46+
/**
47+
* @return the value of this header.
48+
* @since 4.4.0
49+
*/
3050
@NotNull ByteBuffer getValue();
3151

52+
/**
53+
* @return the value of this header.
54+
* @since 4.4.0
55+
*/
56+
@NotNull byte[] getValueAsByteArray();
57+
58+
/**
59+
* @return the value of this header as a string. {@link java.nio.charset.StandardCharsets#UTF_8} is used for the
60+
* decoding.
61+
* @since 4.4.0
62+
*/
3263
@NotNull String getValueAsString();
3364

65+
/**
66+
* @param charset the {@link Charset} that is used for the decoding.
67+
* @return the value of this header as a string.
68+
* @since 4.4.0
69+
*/
3470
@NotNull String getValueAsString(@NotNull Charset charset);
35-
36-
@NotNull byte[] getValueAsByteArray();
37-
3871
}

‎src/main/java/com/hivemq/extensions/kafka/api/model/KafkaHeaders.java

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -13,34 +13,44 @@
1313
* See the License for the specific language governing permissions and
1414
* limitations under the License.
1515
*/
16+
1617
package com.hivemq.extensions.kafka.api.model;
1718

19+
import com.hivemq.extension.sdk.api.annotations.DoNotImplement;
1820
import com.hivemq.extension.sdk.api.annotations.Immutable;
1921
import com.hivemq.extension.sdk.api.annotations.NotNull;
2022

2123
import java.util.List;
2224
import java.util.Optional;
2325

2426
/**
27+
* This interface contains all {@link KafkaHeader}s belonging to a single {@link KafkaRecord}.
28+
*
2529
* @author Christoph Schäbel
30+
* @author Georg Held
31+
* @since 4.4.0
2632
*/
33+
@Immutable
34+
@DoNotImplement
2735
public interface KafkaHeaders {
2836

29-
@NotNull List<KafkaHeader> asList();
37+
/**
38+
* @return all Kafka headers as a {@link List}.
39+
*/
40+
@Immutable @NotNull List<@NotNull KafkaHeader> asList();
3041

3142
/**
32-
* @param name The name of the user property to get.
33-
* @return An {@link Optional} that contains the last user property with the specified name.
34-
* @since 4.0.0
43+
* @param name the name of the Kafka header to get.
44+
* @return an {@link Optional} that contains the last Kafka header with the specified name.
45+
* @since 4.3.0
3546
*/
3647
@NotNull Optional<KafkaHeader> getLast(@NotNull String name);
3748

3849
/**
39-
* @param name The name of the user properties to get.
40-
* @return The values user property with the specified name.
41-
* @since 4.0.0
50+
* @param name the name of the Kafka headers to get.
51+
* @return the values of the Kafka headers with the specified name.
52+
* @since 4.4.0
4253
*/
43-
@Immutable
44-
@NotNull List<@NotNull KafkaHeader> getAllForName(@NotNull String name);
54+
@Immutable @NotNull List<@NotNull KafkaHeader> getAllForName(@NotNull String name);
4555

4656
}

0 commit comments

Comments
 (0)