001/*
002 * Copyright 2002-2019 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.beans.factory.config;
018
019import java.beans.PropertyDescriptor;
020
021import org.springframework.beans.BeansException;
022import org.springframework.beans.PropertyValues;
023import org.springframework.lang.Nullable;
024
025/**
026 * Subinterface of {@link BeanPostProcessor} that adds a before-instantiation callback,
027 * and a callback after instantiation but before explicit properties are set or
028 * autowiring occurs.
029 *
030 * <p>Typically used to suppress default instantiation for specific target beans,
031 * for example to create proxies with special TargetSources (pooling targets,
032 * lazily initializing targets, etc), or to implement additional injection strategies
033 * such as field injection.
034 *
035 * <p><b>NOTE:</b> This interface is a special purpose interface, mainly for
036 * internal use within the framework. It is recommended to implement the plain
037 * {@link BeanPostProcessor} interface as far as possible, or to derive from
038 * {@link InstantiationAwareBeanPostProcessorAdapter} in order to be shielded
039 * from extensions to this interface.
040 *
041 * @author Juergen Hoeller
042 * @author Rod Johnson
043 * @since 1.2
044 * @see org.springframework.aop.framework.autoproxy.AbstractAutoProxyCreator#setCustomTargetSourceCreators
045 * @see org.springframework.aop.framework.autoproxy.target.LazyInitTargetSourceCreator
046 */
047public interface InstantiationAwareBeanPostProcessor extends BeanPostProcessor {
048
049        /**
050         * Apply this BeanPostProcessor <i>before the target bean gets instantiated</i>.
051         * The returned bean object may be a proxy to use instead of the target bean,
052         * effectively suppressing default instantiation of the target bean.
053         * <p>If a non-null object is returned by this method, the bean creation process
054         * will be short-circuited. The only further processing applied is the
055         * {@link #postProcessAfterInitialization} callback from the configured
056         * {@link BeanPostProcessor BeanPostProcessors}.
057         * <p>This callback will be applied to bean definitions with their bean class,
058         * as well as to factory-method definitions in which case the returned bean type
059         * will be passed in here.
060         * <p>Post-processors may implement the extended
061         * {@link SmartInstantiationAwareBeanPostProcessor} interface in order
062         * to predict the type of the bean object that they are going to return here.
063         * <p>The default implementation returns {@code null}.
064         * @param beanClass the class of the bean to be instantiated
065         * @param beanName the name of the bean
066         * @return the bean object to expose instead of a default instance of the target bean,
067         * or {@code null} to proceed with default instantiation
068         * @throws org.springframework.beans.BeansException in case of errors
069         * @see #postProcessAfterInstantiation
070         * @see org.springframework.beans.factory.support.AbstractBeanDefinition#getBeanClass()
071         * @see org.springframework.beans.factory.support.AbstractBeanDefinition#getFactoryMethodName()
072         */
073        @Nullable
074        default Object postProcessBeforeInstantiation(Class<?> beanClass, String beanName) throws BeansException {
075                return null;
076        }
077
078        /**
079         * Perform operations after the bean has been instantiated, via a constructor or factory method,
080         * but before Spring property population (from explicit properties or autowiring) occurs.
081         * <p>This is the ideal callback for performing custom field injection on the given bean
082         * instance, right before Spring's autowiring kicks in.
083         * <p>The default implementation returns {@code true}.
084         * @param bean the bean instance created, with properties not having been set yet
085         * @param beanName the name of the bean
086         * @return {@code true} if properties should be set on the bean; {@code false}
087         * if property population should be skipped. Normal implementations should return {@code true}.
088         * Returning {@code false} will also prevent any subsequent InstantiationAwareBeanPostProcessor
089         * instances being invoked on this bean instance.
090         * @throws org.springframework.beans.BeansException in case of errors
091         * @see #postProcessBeforeInstantiation
092         */
093        default boolean postProcessAfterInstantiation(Object bean, String beanName) throws BeansException {
094                return true;
095        }
096
097        /**
098         * Post-process the given property values before the factory applies them
099         * to the given bean, without any need for property descriptors.
100         * <p>Implementations should return {@code null} (the default) if they provide a custom
101         * {@link #postProcessPropertyValues} implementation, and {@code pvs} otherwise.
102         * In a future version of this interface (with {@link #postProcessPropertyValues} removed),
103         * the default implementation will return the given {@code pvs} as-is directly.
104         * @param pvs the property values that the factory is about to apply (never {@code null})
105         * @param bean the bean instance created, but whose properties have not yet been set
106         * @param beanName the name of the bean
107         * @return the actual property values to apply to the given bean (can be the passed-in
108         * PropertyValues instance), or {@code null} which proceeds with the existing properties
109         * but specifically continues with a call to {@link #postProcessPropertyValues}
110         * (requiring initialized {@code PropertyDescriptor}s for the current bean class)
111         * @throws org.springframework.beans.BeansException in case of errors
112         * @since 5.1
113         * @see #postProcessPropertyValues
114         */
115        @Nullable
116        default PropertyValues postProcessProperties(PropertyValues pvs, Object bean, String beanName)
117                        throws BeansException {
118
119                return null;
120        }
121
122        /**
123         * Post-process the given property values before the factory applies them
124         * to the given bean. Allows for checking whether all dependencies have been
125         * satisfied, for example based on a "Required" annotation on bean property setters.
126         * <p>Also allows for replacing the property values to apply, typically through
127         * creating a new MutablePropertyValues instance based on the original PropertyValues,
128         * adding or removing specific values.
129         * <p>The default implementation returns the given {@code pvs} as-is.
130         * @param pvs the property values that the factory is about to apply (never {@code null})
131         * @param pds the relevant property descriptors for the target bean (with ignored
132         * dependency types - which the factory handles specifically - already filtered out)
133         * @param bean the bean instance created, but whose properties have not yet been set
134         * @param beanName the name of the bean
135         * @return the actual property values to apply to the given bean (can be the passed-in
136         * PropertyValues instance), or {@code null} to skip property population
137         * @throws org.springframework.beans.BeansException in case of errors
138         * @see #postProcessProperties
139         * @see org.springframework.beans.MutablePropertyValues
140         * @deprecated as of 5.1, in favor of {@link #postProcessProperties(PropertyValues, Object, String)}
141         */
142        @Deprecated
143        @Nullable
144        default PropertyValues postProcessPropertyValues(
145                        PropertyValues pvs, PropertyDescriptor[] pds, Object bean, String beanName) throws BeansException {
146
147                return pvs;
148        }
149
150}