Recommendation for consistent @Profile declarations on overloaded @Bean methods

Issue: SPR-15266
(cherry picked from commit 5d3249f)

spring-context/src/main/java/org/springframework/context/annotation/Conditional.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -16,6 +16,7 @@
 
 package org.springframework.context.annotation;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
@@ -55,8 +56,9 @@ import java.lang.annotation.Target;
  * @since 4.0
  * @see Condition
  */
-@Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.TYPE, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
 public @interface Conditional {
 
 	/**

spring-context/src/main/java/org/springframework/context/annotation/Configuration.java

@@ -231,7 +231,7 @@ import org.springframework.stereotype.Component;
  * indicate they should be processed only if a given profile or profiles are <em>active</em>:
  *
  * <pre class="code">
- * &#064;Profile("embedded")
+ * &#064;Profile("development")
  * &#064;Configuration
  * public class EmbeddedDatabaseConfig {
  *
@@ -251,6 +251,22 @@ import org.springframework.stereotype.Component;
  *     }
  * }</pre>
  *
+ * Alternatively, you may also declare profile conditions at the {@code @Bean} method level,
+ * e.g. for alternative bean variants within the same configuration class:
+ *
+ * <pre class="code">
+ * &#064;Configuration
+ * public class ProfileDatabaseConfig {
+ *
+ *     &#064;Bean("dataSource")
+ *     &#064;Profile("development")
+ *     public DataSource embeddedDatabase() { ... }
+ *
+ *     &#064;Bean("dataSource")
+ *     &#064;Profile("production")
+ *     public DataSource productionDatabase() { ... }
+ * }</pre>
+ *
  * See the {@link Profile @Profile} and {@link org.springframework.core.env.Environment}
  * javadocs for further details.
  *

spring-context/src/main/java/org/springframework/context/annotation/Profile.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -57,12 +57,24 @@ import org.springframework.core.env.ConfigurableEnvironment;
  *
  * <p>If a given profile is prefixed with the NOT operator ({@code !}), the annotated
  * component will be registered if the profile is <em>not</em> active &mdash; for example,
- * given {@code @Profile({"p1", "!p2"})}, registration will occur if profile 'p1' is active or
- * if profile 'p2' is <em>not</em> active.
+ * given {@code @Profile({"p1", "!p2"})}, registration will occur if profile 'p1' is active
+ * or if profile 'p2' is <em>not</em> active.
  *
  * <p>If the {@code @Profile} annotation is omitted, registration will occur regardless
  * of which (if any) profiles are active.
  *
+ * <p><b>NOTE:</b> With {@code @Profile} on {@code @Bean} methods, a special scenario may
+ * apply: In the case of overloaded {@code @Bean} methods of the same Java method name
+ * (analogous to constructor overloading), an {@code @Profile} condition needs to be
+ * consistently declared on all overloaded methods. If the conditions are inconsistent,
+ * only the condition on the first declaration among the overloaded methods will matter.
+ * {@code @Profile} can therefore not be used to select an overloaded method with a
+ * particular argument signature over another; resolution between all factory methods
+ * for the same bean follows Spring's constructor resolution algorithm at creation time.
+ * <b>Use distinct Java method names pointing to the same {@link @Bean#name bean name}
+ * if you'd like to define alternative beans with different profile conditions</b>;
+ * see {@code ProfileDatabaseConfig} in {@link Configuration @Configuration}'s javadoc.
+ *
  * <p>When defining Spring beans via XML, the {@code "profile"} attribute of the
  * {@code <beans>} element may be used. See the documentation in the
  * {@code spring-beans} XSD (version 3.1 or greater) for details.
@@ -78,8 +90,8 @@ import org.springframework.core.env.ConfigurableEnvironment;
  * @see Conditional
  * @see org.springframework.test.context.ActiveProfiles
  */
-@Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.TYPE, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
 @Documented
 @Conditional(ProfileCondition.class)
 public @interface Profile {