Document [Priority]Ordered support for Bean[Factory]PostProcessor

Prior to this commit, it was not clear from the Javadoc for
BeanPostProcess and BeanFactoryPostProcessor that such components can
be ordered by implementing Ordered or PriorityOrdered.

This commit improves the documentation for BPP and BFPP to make this
support explicit.

Closes gh-23636

spring-beans/src/main/java/org/springframework/beans/factory/config/BeanFactoryPostProcessor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-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.
@@ -19,25 +19,42 @@ package org.springframework.beans.factory.config;
 import org.springframework.beans.BeansException;
 
 /**
- * Allows for custom modification of an application context's bean definitions,
+ * Factory hook that allows for custom modification of an application context's
- * adapting the bean property values of the context's underlying bean factory.
+ * bean definitions, adapting the bean property values of the context's underlying
- *
+ * bean factory.
- * <p>Application contexts can auto-detect BeanFactoryPostProcessor beans in
- * their bean definitions and apply them before any other beans get created.
  *
  * <p>Useful for custom config files targeted at system administrators that
- * override bean properties configured in the application context.
+ * override bean properties configured in the application context. See
+ * {@link PropertyResourceConfigurer} and its concrete implementations for
+ * out-of-the-box solutions that address such configuration needs.
  *
- * <p>See PropertyResourceConfigurer and its concrete implementations
+ * <p>A {@code BeanFactoryPostProcessor} may interact with and modify bean
- * for out-of-the-box solutions that address such configuration needs.
- *
- * <p>A BeanFactoryPostProcessor may interact with and modify bean
  * definitions, but never bean instances. Doing so may cause premature bean
  * instantiation, violating the container and causing unintended side-effects.
  * If bean instance interaction is required, consider implementing
  * {@link BeanPostProcessor} instead.
  *
+ * <h3>Registration</h3>
+ * <p>An {@code ApplicationContext} auto-detects {@code BeanFactoryPostProcessor}
+ * beans in its bean definitions and applies them before any other beans get created.
+ * A {@code BeanFactoryPostProcessor} may also be registered programmatically
+ * with a {@code ConfigurableApplicationContext}.
+ *
+ * <h3>Ordering</h3>
+ * <p>{@code BeanFactoryPostProcessor} beans that are autodetected in an
+ * {@code ApplicationContext} will be ordered according to
+ * {@link org.springframework.core.PriorityOrdered} and
+ * {@link org.springframework.core.Ordered} semantics. In contrast,
+ * {@code BeanFactoryPostProcessor} beans that are registered programmatically
+ * with a {@code ConfigurableApplicationContext} will be applied in the order of
+ * registration; any ordering semantics expressed through implementing the
+ * {@code PriorityOrdered} or {@code Ordered} interface will be ignored for
+ * programmatically registered post-processors. Furthermore, the
+ * {@link org.springframework.core.annotation.Order @Order} annotation is not
+ * taken into account for {@code BeanFactoryPostProcessor} beans.
+ *
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 06.07.2003
  * @see BeanPostProcessor
  * @see PropertyResourceConfigurer

spring-beans/src/main/java/org/springframework/beans/factory/config/BeanPostProcessor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-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.
@@ -20,20 +20,35 @@ import org.springframework.beans.BeansException;
 import org.springframework.lang.Nullable;
 
 /**
- * Factory hook that allows for custom modification of new bean instances,
+ * Factory hook that allows for custom modification of new bean instances —
- * e.g. checking for marker interfaces or wrapping them with proxies.
+ * for example, checking for marker interfaces or wrapping beans with proxies.
- *
- * <p>ApplicationContexts can autodetect BeanPostProcessor beans in their
- * bean definitions and apply them to any beans subsequently created.
- * Plain bean factories allow for programmatic registration of post-processors,
- * applying to all beans created through this factory.
  *
  * <p>Typically, post-processors that populate beans via marker interfaces
  * or the like will implement {@link #postProcessBeforeInitialization},
  * while post-processors that wrap beans with proxies will normally
  * implement {@link #postProcessAfterInitialization}.
  *
+ * <h3>Registration</h3>
+ * <p>An {@code ApplicationContext} can autodetect {@code BeanPostProcessor} beans
+ * in its bean definitions and apply those post-processors to any beans subsequently
+ * created. A plain {@code BeanFactory} allows for programmatic registration of
+ * post-processors, applying them to all beans created through the bean factory.
+ *
+ * <h3>Ordering</h3>
+ * <p>{@code BeanPostProcessor} beans that are autodetected in an
+ * {@code ApplicationContext} will be ordered according to
+ * {@link org.springframework.core.PriorityOrdered} and
+ * {@link org.springframework.core.Ordered} semantics. In contrast,
+ * {@code BeanPostProcessor} beans that are registered programmatically with a
+ * {@code BeanFactory} will be applied in the order of registration; any ordering
+ * semantics expressed through implementing the
+ * {@code PriorityOrdered} or {@code Ordered} interface will be ignored for
+ * programmatically registered post-processors. Furthermore, the
+ * {@link org.springframework.core.annotation.Order @Order} annotation is not
+ * taken into account for {@code BeanPostProcessor} beans.
+ *
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 10.10.2003
  * @see InstantiationAwareBeanPostProcessor
  * @see DestructionAwareBeanPostProcessor
@@ -43,7 +58,7 @@ import org.springframework.lang.Nullable;
 public interface BeanPostProcessor {
 
 	/**
-	 * Apply this BeanPostProcessor to the given new bean instance <i>before</i> any bean
+	 * Apply this {@code BeanPostProcessor} to the given new bean instance <i>before</i> any bean
 	 * initialization callbacks (like InitializingBean's {@code afterPropertiesSet}
 	 * or a custom init-method). The bean will already be populated with property values.
 	 * The returned bean instance may be a wrapper around the original.
@@ -61,7 +76,7 @@ public interface BeanPostProcessor {
 	}
 
 	/**
-	 * Apply this BeanPostProcessor to the given new bean instance <i>after</i> any bean
+	 * Apply this {@code BeanPostProcessor} to the given new bean instance <i>after</i> any bean
 	 * initialization callbacks (like InitializingBean's {@code afterPropertiesSet}
 	 * or a custom init-method). The bean will already be populated with property values.
 	 * The returned bean instance may be a wrapper around the original.
@@ -71,7 +86,7 @@ public interface BeanPostProcessor {
 	 * objects or both through corresponding {@code bean instanceof FactoryBean} checks.
 	 * <p>This callback will also be invoked after a short-circuiting triggered by a
 	 * {@link InstantiationAwareBeanPostProcessor#postProcessBeforeInstantiation} method,
-	 * in contrast to all other BeanPostProcessor callbacks.
+	 * in contrast to all other {@code BeanPostProcessor} callbacks.
 	 * <p>The default implementation returns the given {@code bean} as-is.
 	 * @param bean the new bean instance
 	 * @param beanName the name of the bean