Skip to content

Commit 308b48f

Browse files
MicWalterMicWalter
authored
Merge pull request #71 from hivemq/improve-javadoc
Improve javadoc
2 parents c3660a7 + 2cc711d commit 308b48f

16 files changed

+114
-111
lines changed

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

Lines changed: 39 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -44,9 +44,9 @@ public interface KafkaRecordBuilder {
4444
* <p>
4545
* This is required to successfully build a {@link KafkaRecord}.
4646
*
47-
* @param topic the name of the topic.
48-
* @return this builder
49-
* @throws IllegalArgumentException if topic is not a valid name for a Kafka topic
47+
* @param topic The name of the topic.
48+
* @return This builder.
49+
* @throws IllegalArgumentException If the topic is not a valid name for a Kafka topic.
5050
* @since 4.4.0
5151
*/
5252
@NotNull KafkaRecordBuilder topic(@NotNull String topic);
@@ -55,140 +55,140 @@ public interface KafkaRecordBuilder {
5555
* Set the key of the Kafka record.
5656
*
5757
* @param key the value of the key.
58-
* @return this builder
58+
* @return This builder.
5959
* @since 4.4.0
6060
*/
6161
@NotNull KafkaRecordBuilder key(@NotNull ByteBuffer key);
6262

6363
/**
6464
* Set the key of the Kafka record.
6565
*
66-
* @param key the value of the key.
67-
* @return this builder
66+
* @param key The value of the key.
67+
* @return This builder.
6868
* @since 4.4.0
6969
*/
7070
@NotNull KafkaRecordBuilder key(byte @NotNull [] key);
7171

7272
/**
7373
* Set the key of the Kafka record.
7474
*
75-
* @param key the value of the key. {@link java.nio.charset.StandardCharsets#UTF_8} is used for encoding.
76-
* @return this builder
75+
* @param key The value of the key. {@link java.nio.charset.StandardCharsets#UTF_8} is used for encoding.
76+
* @return This builder.
7777
* @since 4.4.0
7878
*/
7979
@NotNull KafkaRecordBuilder key(@NotNull String key);
8080

8181
/**
8282
* Set the key of the Kafka record.
8383
*
84-
* @param key the value of the key.
85-
* @param charset the {@link Charset} used for encoding.
86-
* @return this builder
84+
* @param key The value of the key.
85+
* @param charset The {@link Charset} used for encoding.
86+
* @return This builder.
8787
* @since 4.4.0
8888
*/
8989
@NotNull KafkaRecordBuilder key(@NotNull String key, @NotNull Charset charset);
9090

9191
/**
9292
* Set the value of the Kafka record.
9393
*
94-
* @param value the value of the Kafka value.
95-
* @return this builder
94+
* @param value The value of the Kafka value.
95+
* @return This builder.
9696
* @since 4.4.0
9797
*/
9898
@NotNull KafkaRecordBuilder value(@NotNull ByteBuffer value);
9999

100100
/**
101101
* Set the value of the Kafka record.
102102
*
103-
* @param value the value of the Kafka value.
104-
* @return this builder
103+
* @param value The value of the Kafka value.
104+
* @return This builder.
105105
* @since 4.4.0
106106
*/
107107
@NotNull KafkaRecordBuilder value(byte @NotNull [] value);
108108

109109
/**
110110
* Set the value of the Kafka record.
111111
*
112-
* @param value the value of the Kafka value. {@link java.nio.charset.StandardCharsets#UTF_8} is used for encoding.
113-
* @return this builder
112+
* @param value The value of the Kafka value. {@link java.nio.charset.StandardCharsets#UTF_8} is used for encoding.
113+
* @return This builder.
114114
* @since 4.4.0
115115
*/
116116
@NotNull KafkaRecordBuilder value(@NotNull String value);
117117

118118
/**
119119
* Set the value of the Kafka record.
120120
*
121-
* @param value the value of the Kafka value.
122-
* @param charset the {@link Charset} used for encoding.
123-
* @return this builder
121+
* @param value The value of the Kafka value.
122+
* @param charset The {@link Charset} used for encoding.
123+
* @return This builder.
124124
* @since 4.4.0
125125
*/
126126
@NotNull KafkaRecordBuilder value(@NotNull String value, @NotNull Charset charset);
127127

128128
/**
129129
* Add a header to the Kafka record.
130130
*
131-
* @param key the key of the header.
132-
* @param value the value of the header.
133-
* @return this builder
131+
* @param key The key of the header.
132+
* @param value The value of the header.
133+
* @return This builder.
134134
* @since 4.4.0
135135
*/
136136
@NotNull KafkaRecordBuilder header(@NotNull String key, @NotNull ByteBuffer value);
137137

138138
/**
139139
* Add a header to the Kafka record.
140140
*
141-
* @param key the key of the header.
142-
* @param value the value of the header.
143-
* @return this builder
141+
* @param key The key of the header.
142+
* @param value The value of the header.
143+
* @return This builder.
144144
* @since 4.4.0
145145
*/
146146
@NotNull KafkaRecordBuilder header(@NotNull String key, byte @NotNull [] value);
147147

148148
/**
149149
* Add a header to the Kafka record.
150150
*
151-
* @param key the key of the header.
152-
* @param value the value of the header. {@link java.nio.charset.StandardCharsets#UTF_8} is used for encoding.
153-
* @return this builder
151+
* @param key The key of the header.
152+
* @param value The value of the header. {@link java.nio.charset.StandardCharsets#UTF_8} is used for encoding.
153+
* @return This builder.
154154
* @since 4.4.0
155155
*/
156156
@NotNull KafkaRecordBuilder header(@NotNull String key, @NotNull String value);
157157

158158
/**
159159
* Add a header to the Kafka record.
160160
*
161-
* @param key the key of the header.
162-
* @param value the value of the header.
163-
* @param charset the {@link Charset} used for encoding the {@code value}.
164-
* @return this builder
161+
* @param key The key of the header.
162+
* @param value The value of the header.
163+
* @param charset The {@link Charset} used for encoding the {@code value}.
164+
* @return This builder.
165165
* @since 4.4.0
166166
*/
167167
@NotNull KafkaRecordBuilder header(@NotNull String key, @NotNull String value, @NotNull Charset charset);
168168

169169
/**
170170
* Set the timestamp of the Kafka record.
171171
*
172-
* @param timestamp the value of the Kafka timestamp, in milliseconds since UNIX epoch.
173-
* @return this builder
172+
* @param timestamp The value of the Kafka timestamp, in milliseconds since UNIX epoch.
173+
* @return This builder.
174174
* @since 4.4.0
175175
*/
176176
@NotNull KafkaRecordBuilder timestamp(long timestamp);
177177

178178
/**
179179
* Set the partition number of the Kafka record.
180180
*
181-
* @param partition the value of the Kafka partition number.
182-
* @return this builder
181+
* @param partition The value of the Kafka partition number.
182+
* @return This builder.
183183
* @since 4.4.0
184184
*/
185185
@NotNull KafkaRecordBuilder partition(int partition);
186186

187187
/**
188188
* Create a new {@link KafkaRecord} from the current state of this builder. The builder can be reused afterwards.
189189
*
190-
* @return a new {@link KafkaRecord} containing a snapshot of the current state of this builder.
191-
* @throws NullPointerException if the topic was not set.
190+
* @return A new {@link KafkaRecord} containing a snapshot of the current state of this builder.
191+
* @throws NullPointerException If the topic was not set.
192192
* @since 4.4.0
193193
*/
194194
@NotNull KafkaRecord build();

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,13 +33,13 @@
3333
public interface KafkaCluster {
3434

3535
/**
36-
* @return the configured {@code <id>} of the cluster.
36+
* @return The configured {@code <id>} of the cluster.
3737
* @since 4.4.0
3838
*/
3939
@NotNull String getId();
4040

4141
/**
42-
* @return the configured {@code <bootstrap-servers>} of the cluster.
42+
* @return The configured {@code <bootstrap-servers>} of the cluster.
4343
* @since 4.4.0
4444
*/
4545
@NotNull String getBootstrapServers();

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,33 +38,33 @@
3838
public interface KafkaHeader {
3939

4040
/**
41-
* @return the key of this header.
41+
* @return The key of this header.
4242
* @since 4.4.0
4343
*/
4444
@NotNull String getKey();
4545

4646
/**
47-
* @return the value of this header.
47+
* @return The value of this header.
4848
* @since 4.4.0
4949
*/
5050
@NotNull ByteBuffer getValue();
5151

5252
/**
53-
* @return the value of this header.
53+
* @return The value of this header.
5454
* @since 4.4.0
5555
*/
5656
byte @NotNull [] getValueAsByteArray();
5757

5858
/**
59-
* @return the value of this header as a string. {@link java.nio.charset.StandardCharsets#UTF_8 UTF_8} is used for
59+
* @return The value of this header as a string. {@link java.nio.charset.StandardCharsets#UTF_8 UTF_8} is used for
6060
* the decoding.
6161
* @since 4.4.0
6262
*/
6363
@NotNull String getValueAsString();
6464

6565
/**
66-
* @param charset the {@link Charset} that is used for the decoding.
67-
* @return the value of this header as a string.
66+
* @param charset The {@link Charset} that is used for the decoding.
67+
* @return The value of this header as a string.
6868
* @since 4.4.0
6969
*/
7070
@NotNull String getValueAsString(@NotNull Charset charset);

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -35,21 +35,21 @@
3535
public interface KafkaHeaders {
3636

3737
/**
38-
* @return all Kafka headers as a {@link List}.
38+
* @return All Kafka headers as a {@link List}.
3939
* @since 4.4.0
4040
*/
4141
@Immutable @NotNull List<@NotNull KafkaHeader> asList();
4242

4343
/**
44-
* @param name the name of the Kafka header to get.
45-
* @return an {@link Optional} that contains the last Kafka header with the specified name.
44+
* @param name The name of the Kafka header to get.
45+
* @return An {@link Optional} that contains the last Kafka header with the specified name.
4646
* @since 4.4.0
4747
*/
4848
@NotNull Optional<KafkaHeader> getLast(@NotNull String name);
4949

5050
/**
51-
* @param name the name of the Kafka headers to get.
52-
* @return the values of the Kafka headers with the specified name.
51+
* @param name The name of the Kafka headers to get.
52+
* @return The values of the Kafka headers with the specified name.
5353
* @since 4.4.0
5454
*/
5555
@Immutable @NotNull List<@NotNull KafkaHeader> getAllForName(@NotNull String name);

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

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -38,55 +38,55 @@
3838
public interface KafkaRecord {
3939

4040
/**
41-
* @return the topic of this record.
41+
* @return The topic of this record.
4242
* @since 4.4.0
4343
*/
4444
@NotNull String getTopic();
4545

4646
/**
47-
* @return the {@link KafkaHeaders} of this record. These might be empty.
47+
* @return The {@link KafkaHeaders} of this record. These might be empty.
4848
* @since 4.4.0
4949
*/
5050
@NotNull KafkaHeaders getHeaders();
5151

5252
/**
53-
* @return an {@link Optional} of the key of this record.
53+
* @return An {@link Optional} of the key of this record.
5454
* @since 4.4.0
5555
*/
5656
@NotNull Optional<ByteBuffer> getKey();
5757

5858
/**
59-
* @return an {@link Optional} of the key of this record.
59+
* @return An {@link Optional} of the key of this record.
6060
* @since 4.4.0
6161
*/
6262
@NotNull Optional<byte[]> getKeyAsByteArray();
6363

6464
/**
65-
* @return an {@link Optional} of the value of this record.
65+
* @return An {@link Optional} of the value of this record.
6666
* @since 4.4.0
6767
*/
6868
@NotNull Optional<ByteBuffer> getValue();
6969

7070
/**
71-
* @return an {@link Optional} of the value of this record.@return
71+
* @return An {@link Optional} of the value of this record.
7272
* @since 4.4.0
7373
*/
7474
@NotNull Optional<byte[]> getValueAsByteArray();
7575

7676
/**
77-
* @return an {@link Optional} of the timestamp of this record, in milliseconds since UNIX epoch.
77+
* @return An {@link Optional} of the timestamp of this record, in milliseconds since UNIX epoch.
7878
* @since 4.4.0
7979
*/
8080
@NotNull Optional<Long> getTimestamp();
8181

8282
/**
83-
* @return an {@link Optional} of the partition number of this record.
83+
* @return An {@link Optional} of the partition number of this record.
8484
* @since 4.4.0
8585
*/
8686
@NotNull Optional<Integer> getPartition();
8787

8888
/**
89-
* @return an {@link Optional} of the offset value of this record.
89+
* @return An {@link Optional} of the offset value of this record.
9090
* @since 4.4.0
9191
*/
9292
@NotNull Optional<Long> getOffset();

‎src/main/java/com/hivemq/extensions/kafka/api/services/KafkaTopicService.java

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ public interface KafkaTopicService {
4141
* <p>
4242
* This method can block the calling transformer.
4343
*
44-
* @param topic the name of a Kafka topic.
45-
* @return the {@link KafkaTopicState} of the topic. Possible values here are {@link KafkaTopicState#FAILURE},
44+
* @param topic The name of a Kafka topic.
45+
* @return The {@link KafkaTopicState} of the topic. Possible values here are {@link KafkaTopicState#FAILURE},
4646
* {@link KafkaTopicState#EXISTS} and {@link KafkaTopicState#MISSING}.
4747
* @since 4.4.0
4848
*/
@@ -55,8 +55,8 @@ public interface KafkaTopicService {
5555
* <p>
5656
* This method can block the calling transformer.
5757
*
58-
* @param topics a set containing the names of Kafka topics.
59-
* @return a mapping of the queried Kafka topics to their {@link KafkaTopicState}. Possible values here are {@link
58+
* @param topics A set containing the names of Kafka topics.
59+
* @return A mapping of the queried Kafka topics to their {@link KafkaTopicState}. Possible values here are {@link
6060
* KafkaTopicState#FAILURE}, {@link KafkaTopicState#EXISTS} and {@link KafkaTopicState#MISSING}.
6161
* @throws NullPointerException if {@code topics} is or contains null.
6262
* @since 4.4.0
@@ -70,8 +70,8 @@ public interface KafkaTopicService {
7070
* This method can block the calling transformer.
7171
* <p>
7272
*
73-
* @param topic the name of a new Kafka topic.
74-
* @return the {@link KafkaTopicState} of the topic after this methods completes. Possible values here are {@link
73+
* @param topic The name of a new Kafka topic.
74+
* @return The {@link KafkaTopicState} of the topic after this methods completes. Possible values here are {@link
7575
* KafkaTopicState#FAILURE}, {@link KafkaTopicState#EXISTS} and {@link KafkaTopicState#CREATED}.
7676
* @since 4.4.0
7777
*/
@@ -85,11 +85,11 @@ public interface KafkaTopicService {
8585
* <p>
8686
* This method can block the calling transformer.
8787
*
88-
* @param topics a set containing the names of new Kafka topics.
89-
* @return a mapping of the Kafka topics to their {@link KafkaTopicState} after this method completes. Possible
88+
* @param topics A set containing the names of new Kafka topics.
89+
* @return A mapping of the Kafka topics to their {@link KafkaTopicState} after this method completes. Possible
9090
* values here are {@link KafkaTopicState#FAILURE}, {@link KafkaTopicState#EXISTS} and {@link
9191
* KafkaTopicState#CREATED}.
92-
* @throws NullPointerException if {@code topics} is or contains null.
92+
* @throws NullPointerException If {@code topics} is or contains null.
9393
* @since 4.4.0
9494
*/
9595
@Immutable @NotNull Map<String, @NotNull KafkaTopicState> createKafkaTopics(@NotNull Set<@NotNull String> topics);
@@ -108,7 +108,7 @@ enum KafkaTopicState {
108108
* <ul>
109109
* <li> Network degradation between HiveMQ and the Kafka cluster
110110
* <li> Insufficient permissions to perform the operation
111-
* <li> An unsuitable configuration in either the HiveMQ Enterprise Extension for Kafka or the Kafka cluster
111+
* <li> An unsuitable configuration in either the "HiveMQ Enterprise Extension for Kafka" or the Kafka cluster
112112
* <li> The internal state of the Kafka cluster
113113
* </ul>
114114
*

0 commit comments

Comments
 (0)