KAFKA-18801 Remove ClusterGenerator and revise ClusterTemplate javadoc (#18907)

Reviewers: Chia-Ping Tsai <chia7712@gmail.com>, David Arthur <mumrah@gmail.com>

test-common/test-common-internal-api/src/main/java/org/apache/kafka/common/test/api/ClusterGenerator.java

@@ -1,25 +0,0 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * The ASF licenses this file to You 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 org.apache.kafka.common.test.api;
-
-import java.util.function.Consumer;
-
-@FunctionalInterface
-public interface ClusterGenerator extends Consumer<ClusterConfig> {
-
-}

test-common/test-common-internal-api/src/main/java/org/apache/kafka/common/test/api/ClusterTemplate.java

@@ -30,9 +30,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
  * Used to indicate that a test should call the method given by {@link #value()} to generate a number of
- * cluster configurations. The method specified by the value should accept a single argument of the type
+ * cluster configurations. The test-containing class must define a static method which takes no arguments and
- * {@link ClusterGenerator}. Any return value from the method is ignored. A test invocation
+ * returns a list of {@link ClusterConfig}, used to generate multiple cluster configurations.
- * will be generated for each {@link ClusterConfig} provided to the ClusterGenerator instance.
  *
  * The method given here must be static since it is invoked before any tests are actually run. Each test generated
  * by this annotation will run as if it was defined as a separate test method with its own
@@ -42,6 +41,17 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * ClusterConfig instances.
  *
  * For Scala tests, the method should be defined in a companion object with the same name as the test class.
+ * Usage looks something like this:
+ * <pre>{@code
+ * private static List<ClusterConfig> generator() {
+ *     return Collections.singletonList(ClusterConfig.defaultBuilder().build());
+ * }
+ *
+ * @ClusterTemplate("generator")
+ * public void testGenerateClusterTemplate(ClusterInstance clusterInstance) {
+ *     assertNotNull(clusterInstance.bootstrapServers());
+ * }
+ * }</pre>
  */
 @Documented
 @Target({METHOD})

test-common/test-common-runtime/src/main/java/org/apache/kafka/common/test/junit/ClusterTestExtensions.java

@@ -213,7 +213,7 @@ public class ClusterTestExtensions implements TestTemplateInvocationContextProvi
         String baseDisplayName = context.getRequiredTestMethod().getName();
         int repeatCount = getTestRepeatCount();
         List<TestTemplateInvocationContext> contexts = IntStream.range(0, repeatCount)
-            .mapToObj(__ -> generateClusterConfigurations(context, annot.value()).stream())
+            .mapToObj(__ -> generateClusterConfiguration(context, annot.value()).stream())
             .flatMap(Function.identity())
             .flatMap(config -> config.clusterTypes().stream().map(type -> invocationContextForClusterType(type, baseDisplayName, config)))
             .collect(Collectors.toList());
@@ -226,7 +226,7 @@ public class ClusterTestExtensions implements TestTemplateInvocationContextProvi
     }
 
     @SuppressWarnings("unchecked")
-    private List<ClusterConfig> generateClusterConfigurations(
+    private List<ClusterConfig> generateClusterConfiguration(
         ExtensionContext context,
         String generateClustersMethods
     ) {