From 6bd438a7376ea28047cb068fa26bc95631bf49e7 Mon Sep 17 00:00:00 2001
From: Madhura Bhave <mbhave@pivotal.io>
Date: Thu, 26 Jul 2018 12:15:45 -0700
Subject: [PATCH] Document `@ConditionalOnProperty` limitation with collections

Closes gh-7483
---
 .../condition/ConditionalOnProperty.java          | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnProperty.java b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnProperty.java
index 3189ef15ff8..45e4cd48ff9 100644
--- a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnProperty.java
+++ b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnProperty.java
@@ -22,6 +22,7 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.springframework.boot.autoconfigure.couchbase.OnBootstrapHostsCondition;
 import org.springframework.context.annotation.Conditional;
 import org.springframework.core.env.Environment;
 
@@ -72,6 +73,20 @@ import org.springframework.core.env.Environment;
  * {@link #matchIfMissing()} attribute is consulted. By default missing attributes do not
  * match.
  *
+ * <p>
+ * This condition cannot be reliably used for matching collection properties. For example,
+ * in the following configuration, the condition matches if {@code spring.example.values}
+ * is present in the {@link Environment} but does not match if {@code spring.example.values[0]} is present.
+ *
+ * <pre class="code">
+ * &#064;ConditionalOnProperty(prefix = "spring", name = "example.values")
+ * class ExampleAutoConfiguration {
+ * }
+ * </pre>
+ *
+ * It is better to use a custom condition for such cases.
+ * See {@link OnBootstrapHostsCondition} for an example of a custom condition.
+ *
  * @author Maciej Walkowiak
  * @author Stephane Nicoll
  * @author Phillip Webb