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 org.springframework.beans.BeansException;
020: import org.springframework.beans.factory.BeanFactory;
021:
022: /**
023: * Extension of the {@link org.springframework.beans.factory.BeanFactory}
024: * interface to be implemented by bean factories that are capable of
025: * autowiring, provided that they want to expose this functionality for
026: * existing bean instances.
027: *
028: * <p>This subinterface of BeanFactory is not meant to be used in normal
029: * application code: stick to {@link org.springframework.beans.factory.BeanFactory}
030: * or {@link org.springframework.beans.factory.ListableBeanFactory} for
031: * typical use cases.
032: *
033: * <p>Integration code for other frameworks can leverage this interface to
034: * wire and populate existing bean instances that Spring does not control
035: * the lifecycle of. This is particularly useful for WebWork Actions and
036: * Tapestry Page objects, for example.
037: *
038: * <p>Note that this interface is not implemented by
039: * {@link org.springframework.context.ApplicationContext} facades,
040: * as it is hardly ever used by application code. That said, it is available
041: * from an application context too, accessible through ApplicationContext's
042: * {@link org.springframework.context.ApplicationContext#getAutowireCapableBeanFactory()}
043: * method.
044: *
045: * <p>You may also implement the {@link org.springframework.beans.factory.BeanFactoryAware}
046: * interface, which exposes the internal BeanFactory even when running in an
047: * ApplicationContext, to get access to an AutowireCapableBeanFactory:
048: * simply cast the passed-in BeanFactory to AutowireCapableBeanFactory.
049: *
050: * @author Juergen Hoeller
051: * @since 04.12.2003
052: * @see org.springframework.beans.factory.BeanFactoryAware
053: * @see org.springframework.beans.factory.config.ConfigurableListableBeanFactory
054: * @see org.springframework.context.ApplicationContext#getAutowireCapableBeanFactory()
055: */
056: public interface AutowireCapableBeanFactory extends BeanFactory {
057:
058: /**
059: * Constant that indicates no autowiring at all
060: * (other than callbacks such as BeanFactoryAware).
061: * @see #createBean
062: * @see #autowire
063: * @see #autowireBeanProperties
064: */
065: int AUTOWIRE_NO = 0;
066:
067: /**
068: * Constant that indicates autowiring bean properties by name.
069: * @see #createBean
070: * @see #autowire
071: * @see #autowireBeanProperties
072: */
073: int AUTOWIRE_BY_NAME = 1;
074:
075: /**
076: * Constant that indicates autowiring bean properties by type.
077: * @see #createBean
078: * @see #autowire
079: * @see #autowireBeanProperties
080: */
081: int AUTOWIRE_BY_TYPE = 2;
082:
083: /**
084: * Constant that indicates autowiring a constructor.
085: * @see #createBean
086: * @see #autowire
087: */
088: int AUTOWIRE_CONSTRUCTOR = 3;
089:
090: /**
091: * Constant that indicates determining an appropriate autowire strategy
092: * through introspection of the bean class.
093: * @see #createBean
094: * @see #autowire
095: */
096: int AUTOWIRE_AUTODETECT = 4;
097:
098: /**
099: * Fully create a new bean instance of the given class with the specified
100: * autowire strategy. All constants defined in this interface are supported here.
101: * <p>Performs full initialization of the bean, including all applicable
102: * {@link BeanPostProcessor BeanPostProcessors}.
103: * @param beanClass the class of the bean to create
104: * @param autowireMode by name or type, using the constants in this interface
105: * @param dependencyCheck whether to perform a dependency check for objects
106: * (not applicable to autowiring a constructor, thus ignored there)
107: * @return the new bean instance
108: * @throws BeansException if instantiation or wiring failed
109: * @see #AUTOWIRE_NO
110: * @see #AUTOWIRE_BY_NAME
111: * @see #AUTOWIRE_BY_TYPE
112: * @see #AUTOWIRE_CONSTRUCTOR
113: * @see #AUTOWIRE_AUTODETECT
114: */
115: Object createBean(Class beanClass, int autowireMode,
116: boolean dependencyCheck) throws BeansException;
117:
118: /**
119: * Instantiate a new bean instance of the given class with the specified autowire
120: * strategy. All constants defined in this interface are supported here.
121: * <p>Does <i>not</i> apply any {@link BeanPostProcessor BeanPostProcessors} or
122: * perform any further initialization of the bean. This interface offers distinct,
123: * fine-grained operations for those purposes, for example {@link #initializeBean}.
124: * @param beanClass the class of the bean to instantiate
125: * @param autowireMode by name or type, using the constants in this interface
126: * @param dependencyCheck whether to perform a dependency check for object
127: * references in the bean instance (not applicable to autowiring a constructor,
128: * thus ignored there)
129: * @return the new bean instance
130: * @throws BeansException if instantiation or wiring failed
131: * @see #AUTOWIRE_NO
132: * @see #AUTOWIRE_BY_NAME
133: * @see #AUTOWIRE_BY_TYPE
134: * @see #AUTOWIRE_CONSTRUCTOR
135: * @see #AUTOWIRE_AUTODETECT
136: * @see #initializeBean
137: * @see #applyBeanPostProcessorsBeforeInitialization
138: * @see #applyBeanPostProcessorsAfterInitialization
139: */
140: Object autowire(Class beanClass, int autowireMode,
141: boolean dependencyCheck) throws BeansException;
142:
143: /**
144: * Autowire the bean properties of the given bean instance by name or type.
145: * @param existingBean the existing bean instance
146: * @param autowireMode by name or type, using the constants in this interface
147: * @param dependencyCheck whether to perform a dependency check for object
148: * references in the bean instance
149: * @throws BeansException if wiring failed
150: * @see #AUTOWIRE_BY_NAME
151: * @see #AUTOWIRE_BY_TYPE
152: */
153: void autowireBeanProperties(Object existingBean, int autowireMode,
154: boolean dependencyCheck) throws BeansException;
155:
156: /**
157: * Apply the property values of the bean definition with the given name
158: * to the given bean instance. The bean definition can either define a
159: * fully self-contained bean, reusing its property values, or just
160: * property values meant to be used for existing bean instances.
161: * <p>Note: This method does <i>not</i> autowire bean properties;
162: * it just applies explicitly defined property values.
163: * Use the {@link #autowireBeanProperties} method to autowire
164: * an existing bean instance.
165: * @param existingBean the existing bean instance
166: * @param beanName the name of the bean definition in the bean factory
167: * (a bean definition of that name has to be available)
168: * @throws org.springframework.beans.factory.NoSuchBeanDefinitionException
169: * if there is no bean with the given name
170: * @throws BeansException if applying the property values failed
171: * @see #autowireBeanProperties
172: */
173: void applyBeanPropertyValues(Object existingBean, String beanName)
174: throws BeansException;
175:
176: /**
177: * Configure the given bean instance: autowiring bean properties, applying
178: * bean property values, applying factory callbacks such as <code>setBeanName</code>
179: * and <code>setBeanFactory</code>, and also applying all bean post processors.
180: * <p>This is effectively a superset of what <code>initializeBean</code>
181: * provides, fully applying the configuration specified by the corresponding
182: * bean definition.
183: * @param existingBean the existing bean instance
184: * @param beanName the name of the bean, to be passed to it if necessary
185: * (a bean definition of that name has to be available)
186: * @return the bean instance to use, either the original or a wrapped one
187: * @throws org.springframework.beans.factory.NoSuchBeanDefinitionException
188: * if there is no bean with the given name
189: * @throws BeansException if the initialization failed
190: * @see #initializeBean
191: */
192: Object configureBean(Object existingBean, String beanName)
193: throws BeansException;
194:
195: /**
196: * Initialize the given bean instance, applying factory callbacks
197: * such as <code>setBeanName</code> and <code>setBeanFactory</code>,
198: * also applying all bean post processors.
199: * <p>Note that no bean definition of the given name has to exist
200: * in the bean factory. The passed-in bean name will simply be used
201: * for callbacks but not checked against the registered bean definitions.
202: * @param existingBean the existing bean instance
203: * @param beanName the name of the bean, to be passed to it if necessary
204: * (only passed to {@link BeanPostProcessor BeanPostProcessors})
205: * @return the bean instance to use, either the original or a wrapped one
206: * @throws BeansException if the initialization failed
207: */
208: Object initializeBean(Object existingBean, String beanName)
209: throws BeansException;
210:
211: /**
212: * Apply {@link BeanPostProcessor BeanPostProcessors} to the given existing bean
213: * instance, invoking their <code>postProcessBeforeInitialization</code> methods.
214: * The returned bean instance may be a wrapper around the original.
215: * @param existingBean the new bean instance
216: * @param beanName the name of the bean
217: * @return the bean instance to use, either the original or a wrapped one
218: * @throws BeansException if any post-processing failed
219: * @see BeanPostProcessor#postProcessBeforeInitialization
220: */
221: Object applyBeanPostProcessorsBeforeInitialization(
222: Object existingBean, String beanName) throws BeansException;
223:
224: /**
225: * Apply {@link BeanPostProcessor BeanPostProcessors} to the given existing bean
226: * instance, invoking their <code>postProcessAfterInitialization</code> methods.
227: * The returned bean instance may be a wrapper around the original.
228: * @param existingBean the new bean instance
229: * @param beanName the name of the bean
230: * @return the bean instance to use, either the original or a wrapped one
231: * @throws BeansException if any post-processing failed
232: * @see BeanPostProcessor#postProcessAfterInitialization
233: */
234: Object applyBeanPostProcessorsAfterInitialization(
235: Object existingBean, String beanName) throws BeansException;
236:
237: }
|