Added more descriptions.

Author: sauroter

.idea/codeStyles/Project.xml

@@ -1,19 +1,38 @@
+/*
+ * Copyright 2018-present HiveMQ GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.hivemq.extensions.kafka.api.services;
 
+import com.hivemq.extension.sdk.api.annotations.DoNotImplement;
 import com.hivemq.extension.sdk.api.annotations.Immutable;
 import com.hivemq.extension.sdk.api.annotations.NotNull;
 
 import java.util.Map;
 import java.util.Set;
 
 /**
- * The KafkaTopicService enables the programmatic interaction with Kafka topics.
- * All methods act on the Kafka cluster, that the calling transformer is associated with.
+ * The KafkaTopicService enables the programmatic interaction with Kafka topics. All methods act on the Kafka cluster,
+ * that the calling transformer is associated with.
  *
  * @author Georg Held
- * @see <a href=https://www.hivemq.com/docs/kafka/latest/enterprise-extension-for-kafka/kafka.html#kafka-clusters>Kafka Cluster configuration</a></a>.
+ * @see <a href=https://www.hivemq.com/docs/kafka/latest/enterprise-extension-for-kafka/kafka.html#kafka-clusters>Kafka
+ *         Cluster configuration</a></a>.
  * @since 4.4.0
  */
+@DoNotImplement
 public interface KafkaTopicService {
 
     /**
@@ -23,7 +42,8 @@ public interface KafkaTopicService {
      *
      * @param topic the name of a Kafka topic.
      * @return the {@link KafkaTopicState} of the topic. Possible values here are {@link KafkaTopicState#FAILURE},
-     * {@link KafkaTopicState#EXISTS} and {@link KafkaTopicState#MISSING}.
+     *         {@link KafkaTopicState#EXISTS} and {@link KafkaTopicState#MISSING}.
+     * @since 4.4.0
      */
     @NotNull KafkaTopicState getKafkaTopicState(@NotNull String topic);
 
@@ -35,59 +55,74 @@ public interface KafkaTopicService {
      * This method can block the calling transformer.
      *
      * @param topics a set containing the names of Kafka topics.
-     * @return a mapping of the queried Kafka topics to their {@link KafkaTopicState}. Possible values here are
-     * {@link KafkaTopicState#FAILURE}, {@link KafkaTopicState#EXISTS} and {@link KafkaTopicState#MISSING}.
+     * @return a mapping of the queried Kafka topics to their {@link KafkaTopicState}. Possible values here are {@link
+     *         KafkaTopicState#FAILURE}, {@link KafkaTopicState#EXISTS} and {@link KafkaTopicState#MISSING}.
+     * @throws NullPointerException if {@code topics} is or contains null.
+     * @since 4.4.0
      */
     @Immutable @NotNull Map<String, @NotNull KafkaTopicState> getKafkaTopicStates(@NotNull Set<@NotNull String> topics);
 
     /**
-     * Create a single Kafka topic on the associated cluster.
-     * Use {@link KafkaTopicService#getKafkaTopicState(String)} if you would like to check, whether the topic already exists.
+     * Create a single Kafka topic on the associated cluster. Use {@link KafkaTopicService#getKafkaTopicState(String)}
+     * if you would like to check, whether the topic already exists.
      * <p>
      * This method can block the calling transformer.
      * <p>
      *
      * @param topic the name of a new Kafka topic.
-     * @return the {@link KafkaTopicState} of the topic after this methods completes. Possible values here are {@link KafkaTopicState#FAILURE},
-     * {@link KafkaTopicState#EXISTS} and {@link KafkaTopicState#CREATED}.
+     * @return the {@link KafkaTopicState} of the topic after this methods completes. Possible values here are {@link
+     *         KafkaTopicState#FAILURE}, {@link KafkaTopicState#EXISTS} and {@link KafkaTopicState#CREATED}.
+     * @since 4.4.0
      */
     @NotNull KafkaTopicState createKafkaTopic(@NotNull String topic);
 
     /**
-     * Create multiple Kafka topics on the associated cluster.
-     * Use {@link KafkaTopicService#getKafkaTopicStates(Set)} if you would like to check, whether the topics already
-     * exists.
+     * Create multiple Kafka topics on the associated cluster. Use {@link KafkaTopicService#getKafkaTopicStates(Set)} if
+     * you would like to check, whether the topics already exists.
      * <p>
      * * The returned map contains exactly one entry per queried topic in the argument set.
      * <p>
      * This method can block the calling transformer.
      *
      * @param topics a set containing the names of new Kafka topics.
-     * @return a mapping of the Kafka topics to their {@link KafkaTopicState} after this method completes. Possible values
-     * here are {@link KafkaTopicState#FAILURE}, {@link KafkaTopicState#EXISTS} and {@link KafkaTopicState#CREATED}.
+     * @return a mapping of the Kafka topics to their {@link KafkaTopicState} after this method completes. Possible
+     *         values here are {@link KafkaTopicState#FAILURE}, {@link KafkaTopicState#EXISTS} and {@link
+     *         KafkaTopicState#CREATED}.
+     * @throws NullPointerException if {@code topics} is or contains null.
+     * @since 4.4.0
      */
     @NotNull Map<String, @NotNull KafkaTopicState> createKafkaTopics(@NotNull Set<@NotNull String> topics);
 
     /**
      * KafkaTopicState encodes the current known state of a Kafka topic on the associated cluster.
+     *
+     * @since 4.4.0
      */
     enum KafkaTopicState {
         /**
          * FAILURE signals that the operation for the topic was not successful. No possible information about the true
          * state of this topic on the Kafka cluster can be assumed.
+         *
+         * @since 4.4.0
          */
         FAILURE,
         /**
-         * This topic is missing from the associated Kafka cluster and may need to be created before a record can be published
-         * to it.
+         * This topic is missing from the associated Kafka cluster and may need to be created before a record can be
+         * published to it.
+         *
+         * @since 4.4.0
          */
         MISSING,
         /**
          * This topic already exists on the associated Kafka cluster.
+         *
+         * @since 4.4.0
          */
         EXISTS,
         /**
          * This topic was created on the associated Kafka cluster.
+         *
+         * @since 4.4.0
          */
         CREATED,
     }

.idea/codeStyles/codeStyleConfig.xml

@@ -13,14 +13,26 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package com.hivemq.extensions.kafka.api.transformers;
 
+import com.hivemq.extension.sdk.api.annotations.DoNotImplement;
 import com.hivemq.extension.sdk.api.annotations.NotNull;
 
 /**
+ * This is the base interface for all HiveMQ Enterprise Extension for Kafka transformer.
+ *
  * @author Christoph Schäbel
+ * @author Georg Held
  */
+@DoNotImplement
 public interface Transformer<I extends TransformerInitInput> {
+
+    /**
+     * Use the init method to set up static runtime context for the execution of your transformer.
+     *
+     * @param input see the specific input e.g. {@link com.hivemq.extensions.kafka.api.transformers.mqtttokafka.MqttToKafkaInitInput}.
+     */
     default void init(@NotNull I input) {
     }
 }

.idea/inspectionProfiles/Project_Default.xml

@@ -1,13 +1,43 @@
+/*
+ * Copyright 2018-present HiveMQ GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.hivemq.extensions.kafka.api.transformers.mqtttokafka;
 
 import com.hivemq.extension.sdk.api.annotations.NotNull;
+import com.hivemq.extensions.kafka.api.model.KafkaCluster;
 import com.hivemq.extensions.kafka.api.services.KafkaTopicService;
 import com.hivemq.extensions.kafka.api.transformers.TransformerInitInput;
 
 /**
+ * Provides context for the set up of a {@link MqttToKafkaTransformer}.
+ *
  * @author Georg Held
+ * @since 4.4.0
  */
 public interface MqttToKafkaInitInput extends TransformerInitInput {
 
+    /**
+     * @return the {@link KafkaCluster} this transformer is associated with.
+     * @since 4.4.0
+     */
+    @NotNull KafkaCluster getKafkaCluster();
+
+    /**
+     * @return the {@link KafkaTopicService} to interact with topics on the Kafka cluster.
+     * @since 4.4.0
+     */
     @NotNull KafkaTopicService getKafkaTopicService();
 }

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

@@ -13,21 +13,45 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package com.hivemq.extensions.kafka.api.transformers.mqtttokafka;
 
+import com.hivemq.extension.sdk.api.annotations.DoNotImplement;
+import com.hivemq.extension.sdk.api.annotations.Immutable;
 import com.hivemq.extension.sdk.api.annotations.NotNull;
 import com.hivemq.extension.sdk.api.packets.publish.PublishPacket;
 import com.hivemq.extensions.kafka.api.model.KafkaCluster;
 import com.hivemq.extensions.kafka.api.services.KafkaTopicService;
 
 /**
+ * The input parameter of the {@link MqttToKafkaTransformer}. It contains the information of the to be transformed
+ * {@link PublishPacket}.
+ * <p>
+ * The MqttToKafkaInput allows access to the {@link KafkaCluster} and the {@link KafkaTopicService} for this cluster.
+ *
  * @author Christoph Schäbel
+ * @author Georg Held
+ * @since 4.4.0
  */
+@Immutable
+@DoNotImplement
 public interface MqttToKafkaInput {
 
+    /**
+     * @return the {@link KafkaTopicService} to interact with topics on the Kafka cluster.
+     * @since 4.4.0
+     */
     @NotNull KafkaTopicService getKafkaTopicService();
 
+    /**
+     * @return the {@link PublishPacket} that triggered this transformer call.
+     * @since 4.4.0
+     */
     @NotNull PublishPacket getPublishPacket();
 
+    /**
+     * @return the {@link KafkaCluster} this transformer is associated with.
+     * @since 4.4.0
+     */
     @NotNull KafkaCluster getKafkaCluster();
 }

src/main/java/com/hivemq/extensions/kafka/api/transformers/Transformer.java

@@ -13,20 +13,58 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package com.hivemq.extensions.kafka.api.transformers.mqtttokafka;
 
+import com.hivemq.extension.sdk.api.annotations.DoNotImplement;
 import com.hivemq.extension.sdk.api.annotations.NotNull;
 import com.hivemq.extensions.kafka.api.builders.KafkaRecordBuilder;
 import com.hivemq.extensions.kafka.api.model.KafkaRecord;
 
 import java.util.List;
 
 /**
+ * The output parameter of the {@link MqttToKafkaTransformer}. It allows access to the {@link KafkaRecordBuilder}.
+ * <p>
+ * After the {@link MqttToKafkaTransformer#transformMqttToKafka(MqttToKafkaInput, MqttToKafkaOutput)} method returns the
+ * {@link KafkaRecord}s given to this output will be published to the associated Kafka cluster by the HiveMQ Enterprise
+ * Extension for Kafka.
+ *
  * @author Christoph Schäbel
+ * @author Georg Held
+ * @since 4.4.0
  */
+@DoNotImplement
 public interface MqttToKafkaOutput {
 
+    /**
+     * Create a new {@link KafkaRecordBuilder}. One {@link KafkaRecordBuilder} can be used to build multiple Kafka
+     * records.
+     *
+     * @return an empty instance of the {@link KafkaRecordBuilder}.
+     * @since 4.4.0
+     */
     @NotNull KafkaRecordBuilder newKafkaRecordBuilder();
 
-    void setKafkaRecords(@NotNull List<@NotNull KafkaRecord> kafkaRecord);
+    /**
+     * Sets the {@link KafkaRecord}s, that will be pushed to the associated Kafka cluster after the {@link
+     * MqttToKafkaTransformer#transformMqttToKafka(MqttToKafkaInput, MqttToKafkaOutput)} call returns. The HiveMQ
+     * Enterprise Extension for Kafka will publish these records in the order provided by the {@code kafkaRecords}
+     * argument.
+     * <p>
+     * If desired, the same record can occupy multiple places in the {@code kafkaRecords} list. When no record shall be
+     * pushed to the associated Kafka cluster for a {@link com.hivemq.extension.sdk.api.packets.publish.PublishPacket},
+     * call this method with an empty list.
+     * <p>
+     * Use the {@link KafkaRecordBuilder} to create new records as desired.
+     * <p>
+     * Each additional call of this method will overwrite the previous one.
+     *
+     * @param kafkaRecords a list of to be published {@link KafkaRecord}s.
+     * @throws NullPointerException     if {@code kafkaRecords} or any element of it is null.
+     * @throws IllegalArgumentException if any element in {@code kafkaRecords} was not created via a {@link
+     *                                  KafkaRecordBuilder}.
+     * @since 4.4.0
+     */
+    void setKafkaRecords(@NotNull List<@NotNull KafkaRecord> kafkaRecords);
 }