From 26ee9c68ebc07d57bfb8a3489bfeb80b15ca5557 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Thu, 26 Sep 2019 14:24:33 +0200 Subject: [PATCH] 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 --- .../config/BeanFactoryPostProcessor.java | 39 +++++++++++++------ .../factory/config/BeanPostProcessor.java | 37 ++++++++++++------ 2 files changed, 54 insertions(+), 22 deletions(-) diff --git a/spring-beans/src/main/java/org/springframework/beans/factory/config/BeanFactoryPostProcessor.java b/spring-beans/src/main/java/org/springframework/beans/factory/config/BeanFactoryPostProcessor.java index 8016220590d5..5db855fe79e7 100644 --- a/spring-beans/src/main/java/org/springframework/beans/factory/config/BeanFactoryPostProcessor.java +++ b/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 @@ import org.springframework.beans.BeansException; /** - * Allows for custom modification of an application context's bean definitions, - * adapting the bean property values of the context's underlying bean factory. - * - *

Application contexts can auto-detect BeanFactoryPostProcessor beans in - * their bean definitions and apply them before any other beans get created. + * Factory hook that allows for custom modification of an application context's + * bean definitions, adapting the bean property values of the context's underlying + * bean factory. * *

Useful for custom config files targeted at system administrators that - * override bean properties configured in the application context. - * - *

See PropertyResourceConfigurer and its concrete implementations - * for out-of-the-box solutions that address such configuration needs. + * 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. * - *

A BeanFactoryPostProcessor may interact with and modify bean + *

A {@code 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. * + *

Registration

+ *

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}. + * + *

Ordering

+ *

{@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 diff --git a/spring-beans/src/main/java/org/springframework/beans/factory/config/BeanPostProcessor.java b/spring-beans/src/main/java/org/springframework/beans/factory/config/BeanPostProcessor.java index 5b92d1e61a45..7288aa476cf4 100644 --- a/spring-beans/src/main/java/org/springframework/beans/factory/config/BeanPostProcessor.java +++ b/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.lang.Nullable; /** - * Factory hook that allows for custom modification of new bean instances, - * e.g. checking for marker interfaces or wrapping them with proxies. - * - *

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. + * Factory hook that allows for custom modification of new bean instances — + * for example, checking for marker interfaces or wrapping beans with proxies. * *

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}. * + *

Registration

+ *

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. + * + *

Ordering

+ *

{@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 @@ public interface BeanPostProcessor { /** - * Apply this BeanPostProcessor to the given new bean instance before any bean + * Apply this {@code BeanPostProcessor} to the given new bean instance before 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 @@ default Object postProcessBeforeInitialization(Object bean, String beanName) thr } /** - * Apply this BeanPostProcessor to the given new bean instance after any bean + * Apply this {@code BeanPostProcessor} to the given new bean instance after 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 @@ default Object postProcessBeforeInitialization(Object bean, String beanName) thr * objects or both through corresponding {@code bean instanceof FactoryBean} checks. *

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. *

The default implementation returns the given {@code bean} as-is. * @param bean the new bean instance * @param beanName the name of the bean