From 065c901e69b9767af87f9a18f7fd81499463fb4c Mon Sep 17 00:00:00 2001
From: Gary Russell <grussell@pivotal.io>
Date: Thu, 31 Jan 2019 16:03:22 -0500
Subject: [PATCH] Improve Javadocs for Topic Patterns

https://stackoverflow.com/questions/54466662/kafka-consumer-picking-up-topics-dynamically/54467119#comment95745500_54467119
---
 .../kafka/annotation/KafkaListener.java       | 15 ++++++++++----
 .../kafka/listener/ContainerProperties.java   | 20 ++++++++++++++++++-
 2 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/spring-kafka/src/main/java/org/springframework/kafka/annotation/KafkaListener.java b/spring-kafka/src/main/java/org/springframework/kafka/annotation/KafkaListener.java
index a03ae873..0c7e5807 100644
--- a/spring-kafka/src/main/java/org/springframework/kafka/annotation/KafkaListener.java
+++ b/spring-kafka/src/main/java/org/springframework/kafka/annotation/KafkaListener.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2017 the original author or authors.
+ * Copyright 2016-2019 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -113,22 +113,29 @@ public @interface KafkaListener {
 	 * The topics for this listener.
 	 * The entries can be 'topic name', 'property-placeholder keys' or 'expressions'.
 	 * An expression must be resolved to the topic name.
+	 * <p>
 	 * Mutually exclusive with {@link #topicPattern()} and {@link #topicPartitions()}.
 	 * @return the topic names or expressions (SpEL) to listen to.
 	 */
 	String[] topics() default {};
 
 	/**
-	 * The topic pattern for this listener.
-	 * The entries can be 'topic name', 'property-placeholder keys' or 'expressions'.
-	 * An expression must be resolved to the topic pattern.
+	 * The topic pattern for this listener. The entries can be 'topic pattern', a
+	 * 'property-placeholder key' or an 'expression'. The framework will create a
+	 * container that subscribes to all topics matching the specified pattern to get
+	 * dynamically assigned partitions. The pattern matching will be performed
+	 * periodically against topics existing at the time of check. An expression must
+	 * be resolved to the topic pattern (String or Pattern result types are supported).
+	 * <p>
 	 * Mutually exclusive with {@link #topics()} and {@link #topicPartitions()}.
 	 * @return the topic pattern or expression (SpEL).
+	 * @see org.apache.kafka.clients.CommonClientConfigs#METADATA_MAX_AGE_CONFIG
 	 */
 	String topicPattern() default "";
 
 	/**
 	 * The topicPartitions for this listener.
+	 * <p>
 	 * Mutually exclusive with {@link #topicPattern()} and {@link #topics()}.
 	 * @return the topic names or expressions (SpEL) to listen to.
 	 */
diff --git a/spring-kafka/src/main/java/org/springframework/kafka/listener/ContainerProperties.java b/spring-kafka/src/main/java/org/springframework/kafka/listener/ContainerProperties.java
index 94bb1d7f..96ca65d1 100644
--- a/spring-kafka/src/main/java/org/springframework/kafka/listener/ContainerProperties.java
+++ b/spring-kafka/src/main/java/org/springframework/kafka/listener/ContainerProperties.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 the original author or authors.
+ * Copyright 2016-2019 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -220,6 +220,10 @@ public class ContainerProperties {
 
 	private boolean missingTopicsFatal = true;
 
+	/**
+	 * Create properties for a container that will subscribe to the specified topics.
+	 * @param topics the topics.
+	 */
 	public ContainerProperties(String... topics) {
 		Assert.notEmpty(topics, "An array of topics must be provided");
 		this.topics = Arrays.asList(topics).toArray(new String[topics.length]);
@@ -227,12 +231,26 @@ public class ContainerProperties {
 		this.topicPartitions = null;
 	}
 
+	/**
+	 * Create properties for a container that will subscribe to topics matching the
+	 * specified pattern. The framework will create a container that subscribes to all
+	 * topics matching the specified pattern to get dynamically assigned partitions. The
+	 * pattern matching will be performed periodically against topics existing at the time
+	 * of check.
+	 * @param topicPattern the pattern.
+	 * @see org.apache.kafka.clients.CommonClientConfigs#METADATA_MAX_AGE_CONFIG
+	 */
 	public ContainerProperties(Pattern topicPattern) {
 		this.topics = null;
 		this.topicPattern = topicPattern;
 		this.topicPartitions = null;
 	}
 
+	/**
+	 * Create properties for a container that will assign itself the provided topic
+	 * partitions.
+	 * @param topicPartitions the topic partitions.
+	 */
 	public ContainerProperties(TopicPartitionInitialOffset... topicPartitions) {
 		this.topics = null;
 		this.topicPattern = null;