001: /*
002: * Copyright 2002-2007 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: * http://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:
017: package org.springframework.beans.factory.config;
018:
019: import java.beans.PropertyDescriptor;
020:
021: import org.springframework.beans.BeansException;
022: import org.springframework.beans.PropertyValues;
023:
024: /**
025: * Subinterface of {@link BeanPostProcessor} that adds a before-instantiation callback,
026: * and a callback after instantiation but before explicit properties are set or
027: * autowiring occurs.
028: *
029: * <p>Typically used to suppress default instantiation for specific target beans,
030: * for example to create proxies with special TargetSources (pooling targets,
031: * lazily initializing targets, etc), or to implement additional injection strategies
032: * such as field injection.
033: *
034: * <p><b>NOTE:</b> This interface is a special purpose interface, mainly for
035: * internal use within the framework. It is recommended to implement the plain
036: * {@link BeanPostProcessor} interface as far as possible, or to derive from
037: * {@link InstantiationAwareBeanPostProcessorAdapter} in order to be shielded
038: * from extensions to this interface.
039: *
040: * @author Juergen Hoeller
041: * @author Rod Johnson
042: * @since 1.2
043: * @see org.springframework.aop.framework.autoproxy.AbstractAutoProxyCreator#setCustomTargetSourceCreators
044: * @see org.springframework.aop.framework.autoproxy.target.LazyInitTargetSourceCreator
045: */
046: public interface InstantiationAwareBeanPostProcessor extends
047: 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 only be applied to bean definitions with a bean class.
058: * In particular, it will not be applied to beans with a "factory-method".
059: * <p>Post-processors may implement the extended
060: * {@link SmartInstantiationAwareBeanPostProcessor} interface in order
061: * to predict the type of the bean object that they are going to return here.
062: * @param beanClass the class of the bean to be instantiated
063: * @param beanName the name of the bean
064: * @return the bean object to expose instead of a default instance of the target bean,
065: * or <code>null</code> to proceed with default instantiation
066: * @throws org.springframework.beans.BeansException in case of errors
067: * @see org.springframework.beans.factory.support.AbstractBeanDefinition#hasBeanClass
068: * @see org.springframework.beans.factory.support.AbstractBeanDefinition#getFactoryMethodName
069: */
070: Object postProcessBeforeInstantiation(Class beanClass,
071: String beanName) throws BeansException;
072:
073: /**
074: * Perform operations after the bean has been instantiated, via a constructor or factory method,
075: * but before Spring property population (from explicit properties or autowiring) occurs.
076: * @param bean the bean instance created, but whose properties have not yet been set
077: * @param beanName the name of the bean
078: * @return <code>true</code> if properties should be set on the bean; <code>false</code>
079: * if property population should be skipped. Normal implementations should return <code>true</code>.
080: * Returning <code>false</code> will also prevent any subsequent InstantiationAwareBeanPostProcessor
081: * instances being invoked on this bean instance.
082: * @throws org.springframework.beans.BeansException in case of errors
083: */
084: boolean postProcessAfterInstantiation(Object bean, String beanName)
085: throws BeansException;
086:
087: /**
088: * Post-process the given property values before the factory applies them
089: * to the given bean. Allows for checking whether all dependencies have been
090: * satisfied, for example based on a "Required" annotation on bean property setters.
091: * <p>Also allows for replacing the property values to apply, typically through
092: * creating a new MutablePropertyValues instance based on the original PropertyValues,
093: * adding or removing specific values.
094: * @param pvs the property values that the factory is about to apply (never <code>null</code>)
095: * @param pds the relevant property descriptors for the target bean (with ignored
096: * dependency types - which the factory handles specifically - already filtered out)
097: * @param bean the bean instance created, but whose properties have not yet been set
098: * @param beanName the name of the bean
099: * @return the actual property values to apply to to the given bean
100: * (can be the passed-in PropertyValues instance), or <code>null</code>
101: * to skip property population
102: * @throws org.springframework.beans.BeansException in case of errors
103: * @see org.springframework.beans.MutablePropertyValues
104: */
105: PropertyValues postProcessPropertyValues(PropertyValues pvs,
106: PropertyDescriptor[] pds, Object bean, String beanName)
107: throws BeansException;
108:
109: }
|