GH-4388: Cross-reference alwaysStartAfterRefresh from autoStartup and autoStartDltHandler Javadoc

spring-kafka/src/main/java/org/springframework/kafka/annotation/KafkaListener.java

@@ -228,8 +228,15 @@
 	 * a {@link String}, in which case the {@link Boolean#parseBoolean(String)} is used to
 	 * obtain the value.
 	 * <p>SpEL {@code #{...}} and property place holders {@code ${...}} are supported.
+	 * <p><b>Note:</b> After the application context is refreshed,
+	 * {@link org.springframework.kafka.config.KafkaListenerEndpointRegistry#setAlwaysStartAfterRefresh(boolean)}
+	 * (which defaults to {@code true}) may cause containers to start regardless of this setting.
+	 * To honor this property in post-refresh scenarios (e.g. tests), set
+	 * {@code KafkaListenerEndpointRegistry.alwaysStartAfterRefresh} to {@code false}, or configure
+	 * {@code spring.kafka.listener.always-start-after-refresh=false} in your application properties.
 	 * @return true to auto start, false to not auto start.
 	 * @since 2.2
+	 * @see org.springframework.kafka.config.KafkaListenerEndpointRegistry#setAlwaysStartAfterRefresh(boolean)
 	 */
 	String autoStartup() default "";
 

spring-kafka/src/main/java/org/springframework/kafka/annotation/RetryableTopic.java

@@ -208,8 +208,15 @@
 	/**
 	 * Override the container factory's {@code autoStartup} property for just the DLT container.
 	 * Usually used to not start the DLT container when {@code autoStartup} is true.
+	 * <p><b>Note:</b> After the application context is refreshed,
+	 * {@link org.springframework.kafka.config.KafkaListenerEndpointRegistry#setAlwaysStartAfterRefresh(boolean)}
+	 * (which defaults to {@code true}) may cause containers to start regardless of this setting.
+	 * To honor this property in post-refresh scenarios (e.g. tests), set
+	 * {@code KafkaListenerEndpointRegistry.alwaysStartAfterRefresh} to {@code false}, or configure
+	 * {@code spring.kafka.listener.always-start-after-refresh=false} in your application properties.
 	 * @return whether or not to override the factory.
 	 * @since 2.8
+	 * @see org.springframework.kafka.config.KafkaListenerEndpointRegistry#setAlwaysStartAfterRefresh(boolean)
 	 */
 	String autoStartDltHandler() default "";
 

spring-kafka/src/main/java/org/springframework/kafka/config/KafkaListenerEndpointRegistry.java

@@ -178,8 +178,17 @@ public MessageListenerContainer getUnregisteredListenerContainer(String id) {
 	 * context initialization. Set to false to apply the autoStartup property, even for
 	 * late endpoint binding. If this is called after the context is refreshed, it will
 	 * apply to any endpoints registered after that call.
+	 * <p>This setting also affects
+	 * {@link org.springframework.kafka.annotation.KafkaListener#autoStartup()} and
+	 * {@link org.springframework.kafka.annotation.RetryableTopic#autoStartDltHandler()}:
+	 * when {@code true} (the default), those properties are overridden after a context
+	 * refresh. To honor them in post-refresh scenarios (e.g. integration tests), set
+	 * this to {@code false} or configure
+	 * {@code spring.kafka.listener.always-start-after-refresh=false}.
 	 * @param alwaysStartAfterRefresh false to apply the property.
 	 * @since 2.8.7
+	 * @see org.springframework.kafka.annotation.KafkaListener#autoStartup()
+	 * @see org.springframework.kafka.annotation.RetryableTopic#autoStartDltHandler()
 	 */
 	public void setAlwaysStartAfterRefresh(boolean alwaysStartAfterRefresh) {
 		this.alwaysStartAfterRefresh = alwaysStartAfterRefresh;