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; 018 019import org.springframework.beans.BeansException; 020import org.springframework.core.ResolvableType; 021 022/** 023 * The root interface for accessing a Spring bean container. 024 * This is the basic client view of a bean container; 025 * further interfaces such as {@link ListableBeanFactory} and 026 * {@link org.springframework.beans.factory.config.ConfigurableBeanFactory} 027 * are available for specific purposes. 028 * 029 * <p>This interface is implemented by objects that hold a number of bean definitions, 030 * each uniquely identified by a String name. Depending on the bean definition, 031 * the factory will return either an independent instance of a contained object 032 * (the Prototype design pattern), or a single shared instance (a superior 033 * alternative to the Singleton design pattern, in which the instance is a 034 * singleton in the scope of the factory). Which type of instance will be returned 035 * depends on the bean factory configuration: the API is the same. Since Spring 036 * 2.0, further scopes are available depending on the concrete application 037 * context (e.g. "request" and "session" scopes in a web environment). 038 * 039 * <p>The point of this approach is that the BeanFactory is a central registry 040 * of application components, and centralizes configuration of application 041 * components (no more do individual objects need to read properties files, 042 * for example). See chapters 4 and 11 of "Expert One-on-One J2EE Design and 043 * Development" for a discussion of the benefits of this approach. 044 * 045 * <p>Note that it is generally better to rely on Dependency Injection 046 * ("push" configuration) to configure application objects through setters 047 * or constructors, rather than use any form of "pull" configuration like a 048 * BeanFactory lookup. Spring's Dependency Injection functionality is 049 * implemented using this BeanFactory interface and its subinterfaces. 050 * 051 * <p>Normally a BeanFactory will load bean definitions stored in a configuration 052 * source (such as an XML document), and use the {@code org.springframework.beans} 053 * package to configure the beans. However, an implementation could simply return 054 * Java objects it creates as necessary directly in Java code. There are no 055 * constraints on how the definitions could be stored: LDAP, RDBMS, XML, 056 * properties file, etc. Implementations are encouraged to support references 057 * amongst beans (Dependency Injection). 058 * 059 * <p>In contrast to the methods in {@link ListableBeanFactory}, all of the 060 * operations in this interface will also check parent factories if this is a 061 * {@link HierarchicalBeanFactory}. If a bean is not found in this factory instance, 062 * the immediate parent factory will be asked. Beans in this factory instance 063 * are supposed to override beans of the same name in any parent factory. 064 * 065 * <p>Bean factory implementations should support the standard bean lifecycle interfaces 066 * as far as possible. The full set of initialization methods and their standard order is: 067 * <ol> 068 * <li>BeanNameAware's {@code setBeanName} 069 * <li>BeanClassLoaderAware's {@code setBeanClassLoader} 070 * <li>BeanFactoryAware's {@code setBeanFactory} 071 * <li>EnvironmentAware's {@code setEnvironment} 072 * <li>EmbeddedValueResolverAware's {@code setEmbeddedValueResolver} 073 * <li>ResourceLoaderAware's {@code setResourceLoader} 074 * (only applicable when running in an application context) 075 * <li>ApplicationEventPublisherAware's {@code setApplicationEventPublisher} 076 * (only applicable when running in an application context) 077 * <li>MessageSourceAware's {@code setMessageSource} 078 * (only applicable when running in an application context) 079 * <li>ApplicationContextAware's {@code setApplicationContext} 080 * (only applicable when running in an application context) 081 * <li>ServletContextAware's {@code setServletContext} 082 * (only applicable when running in a web application context) 083 * <li>{@code postProcessBeforeInitialization} methods of BeanPostProcessors 084 * <li>InitializingBean's {@code afterPropertiesSet} 085 * <li>a custom init-method definition 086 * <li>{@code postProcessAfterInitialization} methods of BeanPostProcessors 087 * </ol> 088 * 089 * <p>On shutdown of a bean factory, the following lifecycle methods apply: 090 * <ol> 091 * <li>{@code postProcessBeforeDestruction} methods of DestructionAwareBeanPostProcessors 092 * <li>DisposableBean's {@code destroy} 093 * <li>a custom destroy-method definition 094 * </ol> 095 * 096 * @author Rod Johnson 097 * @author Juergen Hoeller 098 * @author Chris Beams 099 * @since 13 April 2001 100 * @see BeanNameAware#setBeanName 101 * @see BeanClassLoaderAware#setBeanClassLoader 102 * @see BeanFactoryAware#setBeanFactory 103 * @see org.springframework.context.ResourceLoaderAware#setResourceLoader 104 * @see org.springframework.context.ApplicationEventPublisherAware#setApplicationEventPublisher 105 * @see org.springframework.context.MessageSourceAware#setMessageSource 106 * @see org.springframework.context.ApplicationContextAware#setApplicationContext 107 * @see org.springframework.web.context.ServletContextAware#setServletContext 108 * @see org.springframework.beans.factory.config.BeanPostProcessor#postProcessBeforeInitialization 109 * @see InitializingBean#afterPropertiesSet 110 * @see org.springframework.beans.factory.support.RootBeanDefinition#getInitMethodName 111 * @see org.springframework.beans.factory.config.BeanPostProcessor#postProcessAfterInitialization 112 * @see DisposableBean#destroy 113 * @see org.springframework.beans.factory.support.RootBeanDefinition#getDestroyMethodName 114 */ 115public interface BeanFactory { 116 117 /** 118 * Used to dereference a {@link FactoryBean} instance and distinguish it from 119 * beans <i>created</i> by the FactoryBean. For example, if the bean named 120 * {@code myJndiObject} is a FactoryBean, getting {@code &myJndiObject} 121 * will return the factory, not the instance returned by the factory. 122 */ 123 String FACTORY_BEAN_PREFIX = "&"; 124 125 126 /** 127 * Return an instance, which may be shared or independent, of the specified bean. 128 * <p>This method allows a Spring BeanFactory to be used as a replacement for the 129 * Singleton or Prototype design pattern. Callers may retain references to 130 * returned objects in the case of Singleton beans. 131 * <p>Translates aliases back to the corresponding canonical bean name. 132 * Will ask the parent factory if the bean cannot be found in this factory instance. 133 * @param name the name of the bean to retrieve 134 * @return an instance of the bean 135 * @throws NoSuchBeanDefinitionException if there is no bean with the specified name 136 * @throws BeansException if the bean could not be obtained 137 */ 138 Object getBean(String name) throws BeansException; 139 140 /** 141 * Return an instance, which may be shared or independent, of the specified bean. 142 * <p>Behaves the same as {@link #getBean(String)}, but provides a measure of type 143 * safety by throwing a BeanNotOfRequiredTypeException if the bean is not of the 144 * required type. This means that ClassCastException can't be thrown on casting 145 * the result correctly, as can happen with {@link #getBean(String)}. 146 * <p>Translates aliases back to the corresponding canonical bean name. 147 * Will ask the parent factory if the bean cannot be found in this factory instance. 148 * @param name the name of the bean to retrieve 149 * @param requiredType type the bean must match. Can be an interface or superclass 150 * of the actual class, or {@code null} for any match. For example, if the value 151 * is {@code Object.class}, this method will succeed whatever the class of the 152 * returned instance. 153 * @return an instance of the bean 154 * @throws NoSuchBeanDefinitionException if there is no such bean definition 155 * @throws BeanNotOfRequiredTypeException if the bean is not of the required type 156 * @throws BeansException if the bean could not be created 157 */ 158 <T> T getBean(String name, Class<T> requiredType) throws BeansException; 159 160 /** 161 * Return an instance, which may be shared or independent, of the specified bean. 162 * <p>Allows for specifying explicit constructor arguments / factory method arguments, 163 * overriding the specified default arguments (if any) in the bean definition. 164 * @param name the name of the bean to retrieve 165 * @param args arguments to use when creating a bean instance using explicit arguments 166 * (only applied when creating a new instance as opposed to retrieving an existing one) 167 * @return an instance of the bean 168 * @throws NoSuchBeanDefinitionException if there is no such bean definition 169 * @throws BeanDefinitionStoreException if arguments have been given but 170 * the affected bean isn't a prototype 171 * @throws BeansException if the bean could not be created 172 * @since 2.5 173 */ 174 Object getBean(String name, Object... args) throws BeansException; 175 176 /** 177 * Return the bean instance that uniquely matches the given object type, if any. 178 * <p>This method goes into {@link ListableBeanFactory} by-type lookup territory 179 * but may also be translated into a conventional by-name lookup based on the name 180 * of the given type. For more extensive retrieval operations across sets of beans, 181 * use {@link ListableBeanFactory} and/or {@link BeanFactoryUtils}. 182 * @param requiredType type the bean must match; can be an interface or superclass 183 * @return an instance of the single bean matching the required type 184 * @throws NoSuchBeanDefinitionException if no bean of the given type was found 185 * @throws NoUniqueBeanDefinitionException if more than one bean of the given type was found 186 * @throws BeansException if the bean could not be created 187 * @since 3.0 188 * @see ListableBeanFactory 189 */ 190 <T> T getBean(Class<T> requiredType) throws BeansException; 191 192 /** 193 * Return an instance, which may be shared or independent, of the specified bean. 194 * <p>Allows for specifying explicit constructor arguments / factory method arguments, 195 * overriding the specified default arguments (if any) in the bean definition. 196 * <p>This method goes into {@link ListableBeanFactory} by-type lookup territory 197 * but may also be translated into a conventional by-name lookup based on the name 198 * of the given type. For more extensive retrieval operations across sets of beans, 199 * use {@link ListableBeanFactory} and/or {@link BeanFactoryUtils}. 200 * @param requiredType type the bean must match; can be an interface or superclass 201 * @param args arguments to use when creating a bean instance using explicit arguments 202 * (only applied when creating a new instance as opposed to retrieving an existing one) 203 * @return an instance of the bean 204 * @throws NoSuchBeanDefinitionException if there is no such bean definition 205 * @throws BeanDefinitionStoreException if arguments have been given but 206 * the affected bean isn't a prototype 207 * @throws BeansException if the bean could not be created 208 * @since 4.1 209 */ 210 <T> T getBean(Class<T> requiredType, Object... args) throws BeansException; 211 212 213 /** 214 * Does this bean factory contain a bean definition or externally registered singleton 215 * instance with the given name? 216 * <p>If the given name is an alias, it will be translated back to the corresponding 217 * canonical bean name. 218 * <p>If this factory is hierarchical, will ask any parent factory if the bean cannot 219 * be found in this factory instance. 220 * <p>If a bean definition or singleton instance matching the given name is found, 221 * this method will return {@code true} whether the named bean definition is concrete 222 * or abstract, lazy or eager, in scope or not. Therefore, note that a {@code true} 223 * return value from this method does not necessarily indicate that {@link #getBean} 224 * will be able to obtain an instance for the same name. 225 * @param name the name of the bean to query 226 * @return whether a bean with the given name is present 227 */ 228 boolean containsBean(String name); 229 230 /** 231 * Is this bean a shared singleton? That is, will {@link #getBean} always 232 * return the same instance? 233 * <p>Note: This method returning {@code false} does not clearly indicate 234 * independent instances. It indicates non-singleton instances, which may correspond 235 * to a scoped bean as well. Use the {@link #isPrototype} operation to explicitly 236 * check for independent instances. 237 * <p>Translates aliases back to the corresponding canonical bean name. 238 * Will ask the parent factory if the bean cannot be found in this factory instance. 239 * @param name the name of the bean to query 240 * @return whether this bean corresponds to a singleton instance 241 * @throws NoSuchBeanDefinitionException if there is no bean with the given name 242 * @see #getBean 243 * @see #isPrototype 244 */ 245 boolean isSingleton(String name) throws NoSuchBeanDefinitionException; 246 247 /** 248 * Is this bean a prototype? That is, will {@link #getBean} always return 249 * independent instances? 250 * <p>Note: This method returning {@code false} does not clearly indicate 251 * a singleton object. It indicates non-independent instances, which may correspond 252 * to a scoped bean as well. Use the {@link #isSingleton} operation to explicitly 253 * check for a shared singleton instance. 254 * <p>Translates aliases back to the corresponding canonical bean name. 255 * Will ask the parent factory if the bean cannot be found in this factory instance. 256 * @param name the name of the bean to query 257 * @return whether this bean will always deliver independent instances 258 * @throws NoSuchBeanDefinitionException if there is no bean with the given name 259 * @since 2.0.3 260 * @see #getBean 261 * @see #isSingleton 262 */ 263 boolean isPrototype(String name) throws NoSuchBeanDefinitionException; 264 265 /** 266 * Check whether the bean with the given name matches the specified type. 267 * More specifically, check whether a {@link #getBean} call for the given name 268 * would return an object that is assignable to the specified target type. 269 * <p>Translates aliases back to the corresponding canonical bean name. 270 * Will ask the parent factory if the bean cannot be found in this factory instance. 271 * @param name the name of the bean to query 272 * @param typeToMatch the type to match against (as a {@code ResolvableType}) 273 * @return {@code true} if the bean type matches, 274 * {@code false} if it doesn't match or cannot be determined yet 275 * @throws NoSuchBeanDefinitionException if there is no bean with the given name 276 * @since 4.2 277 * @see #getBean 278 * @see #getType 279 */ 280 boolean isTypeMatch(String name, ResolvableType typeToMatch) throws NoSuchBeanDefinitionException; 281 282 /** 283 * Check whether the bean with the given name matches the specified type. 284 * More specifically, check whether a {@link #getBean} call for the given name 285 * would return an object that is assignable to the specified target type. 286 * <p>Translates aliases back to the corresponding canonical bean name. 287 * Will ask the parent factory if the bean cannot be found in this factory instance. 288 * @param name the name of the bean to query 289 * @param typeToMatch the type to match against (as a {@code Class}) 290 * @return {@code true} if the bean type matches, 291 * {@code false} if it doesn't match or cannot be determined yet 292 * @throws NoSuchBeanDefinitionException if there is no bean with the given name 293 * @since 2.0.1 294 * @see #getBean 295 * @see #getType 296 */ 297 boolean isTypeMatch(String name, Class<?> typeToMatch) throws NoSuchBeanDefinitionException; 298 299 /** 300 * Determine the type of the bean with the given name. More specifically, 301 * determine the type of object that {@link #getBean} would return for the given name. 302 * <p>For a {@link FactoryBean}, return the type of object that the FactoryBean creates, 303 * as exposed by {@link FactoryBean#getObjectType()}. 304 * <p>Translates aliases back to the corresponding canonical bean name. 305 * Will ask the parent factory if the bean cannot be found in this factory instance. 306 * @param name the name of the bean to query 307 * @return the type of the bean, or {@code null} if not determinable 308 * @throws NoSuchBeanDefinitionException if there is no bean with the given name 309 * @since 1.1.2 310 * @see #getBean 311 * @see #isTypeMatch 312 */ 313 Class<?> getType(String name) throws NoSuchBeanDefinitionException; 314 315 /** 316 * Return the aliases for the given bean name, if any. 317 * All of those aliases point to the same bean when used in a {@link #getBean} call. 318 * <p>If the given name is an alias, the corresponding original bean name 319 * and other aliases (if any) will be returned, with the original bean name 320 * being the first element in the array. 321 * <p>Will ask the parent factory if the bean cannot be found in this factory instance. 322 * @param name the bean name to check for aliases 323 * @return the aliases, or an empty array if none 324 * @see #getBean 325 */ 326 String[] getAliases(String name); 327 328}