001/*
002 * Copyright 2002-2020 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 org.springframework.beans.BeanMetadataElement;
020import org.springframework.beans.MutablePropertyValues;
021import org.springframework.core.AttributeAccessor;
022import org.springframework.core.ResolvableType;
023import org.springframework.lang.Nullable;
024
025/**
026 * A BeanDefinition describes a bean instance, which has property values,
027 * constructor argument values, and further information supplied by
028 * concrete implementations.
029 *
030 * <p>This is just a minimal interface: The main intention is to allow a
031 * {@link BeanFactoryPostProcessor} to introspect and modify property values
032 * and other bean metadata.
033 *
034 * @author Juergen Hoeller
035 * @author Rob Harrop
036 * @since 19.03.2004
037 * @see ConfigurableListableBeanFactory#getBeanDefinition
038 * @see org.springframework.beans.factory.support.RootBeanDefinition
039 * @see org.springframework.beans.factory.support.ChildBeanDefinition
040 */
041public interface BeanDefinition extends AttributeAccessor, BeanMetadataElement {
042
043        /**
044         * Scope identifier for the standard singleton scope: {@value}.
045         * <p>Note that extended bean factories might support further scopes.
046         * @see #setScope
047         * @see ConfigurableBeanFactory#SCOPE_SINGLETON
048         */
049        String SCOPE_SINGLETON = ConfigurableBeanFactory.SCOPE_SINGLETON;
050
051        /**
052         * Scope identifier for the standard prototype scope: {@value}.
053         * <p>Note that extended bean factories might support further scopes.
054         * @see #setScope
055         * @see ConfigurableBeanFactory#SCOPE_PROTOTYPE
056         */
057        String SCOPE_PROTOTYPE = ConfigurableBeanFactory.SCOPE_PROTOTYPE;
058
059
060        /**
061         * Role hint indicating that a {@code BeanDefinition} is a major part
062         * of the application. Typically corresponds to a user-defined bean.
063         */
064        int ROLE_APPLICATION = 0;
065
066        /**
067         * Role hint indicating that a {@code BeanDefinition} is a supporting
068         * part of some larger configuration, typically an outer
069         * {@link org.springframework.beans.factory.parsing.ComponentDefinition}.
070         * {@code SUPPORT} beans are considered important enough to be aware
071         * of when looking more closely at a particular
072         * {@link org.springframework.beans.factory.parsing.ComponentDefinition},
073         * but not when looking at the overall configuration of an application.
074         */
075        int ROLE_SUPPORT = 1;
076
077        /**
078         * Role hint indicating that a {@code BeanDefinition} is providing an
079         * entirely background role and has no relevance to the end-user. This hint is
080         * used when registering beans that are completely part of the internal workings
081         * of a {@link org.springframework.beans.factory.parsing.ComponentDefinition}.
082         */
083        int ROLE_INFRASTRUCTURE = 2;
084
085
086        // Modifiable attributes
087
088        /**
089         * Set the name of the parent definition of this bean definition, if any.
090         */
091        void setParentName(@Nullable String parentName);
092
093        /**
094         * Return the name of the parent definition of this bean definition, if any.
095         */
096        @Nullable
097        String getParentName();
098
099        /**
100         * Specify the bean class name of this bean definition.
101         * <p>The class name can be modified during bean factory post-processing,
102         * typically replacing the original class name with a parsed variant of it.
103         * @see #setParentName
104         * @see #setFactoryBeanName
105         * @see #setFactoryMethodName
106         */
107        void setBeanClassName(@Nullable String beanClassName);
108
109        /**
110         * Return the current bean class name of this bean definition.
111         * <p>Note that this does not have to be the actual class name used at runtime, in
112         * case of a child definition overriding/inheriting the class name from its parent.
113         * Also, this may just be the class that a factory method is called on, or it may
114         * even be empty in case of a factory bean reference that a method is called on.
115         * Hence, do <i>not</i> consider this to be the definitive bean type at runtime but
116         * rather only use it for parsing purposes at the individual bean definition level.
117         * @see #getParentName()
118         * @see #getFactoryBeanName()
119         * @see #getFactoryMethodName()
120         */
121        @Nullable
122        String getBeanClassName();
123
124        /**
125         * Override the target scope of this bean, specifying a new scope name.
126         * @see #SCOPE_SINGLETON
127         * @see #SCOPE_PROTOTYPE
128         */
129        void setScope(@Nullable String scope);
130
131        /**
132         * Return the name of the current target scope for this bean,
133         * or {@code null} if not known yet.
134         */
135        @Nullable
136        String getScope();
137
138        /**
139         * Set whether this bean should be lazily initialized.
140         * <p>If {@code false}, the bean will get instantiated on startup by bean
141         * factories that perform eager initialization of singletons.
142         */
143        void setLazyInit(boolean lazyInit);
144
145        /**
146         * Return whether this bean should be lazily initialized, i.e. not
147         * eagerly instantiated on startup. Only applicable to a singleton bean.
148         */
149        boolean isLazyInit();
150
151        /**
152         * Set the names of the beans that this bean depends on being initialized.
153         * The bean factory will guarantee that these beans get initialized first.
154         */
155        void setDependsOn(@Nullable String... dependsOn);
156
157        /**
158         * Return the bean names that this bean depends on.
159         */
160        @Nullable
161        String[] getDependsOn();
162
163        /**
164         * Set whether this bean is a candidate for getting autowired into some other bean.
165         * <p>Note that this flag is designed to only affect type-based autowiring.
166         * It does not affect explicit references by name, which will get resolved even
167         * if the specified bean is not marked as an autowire candidate. As a consequence,
168         * autowiring by name will nevertheless inject a bean if the name matches.
169         */
170        void setAutowireCandidate(boolean autowireCandidate);
171
172        /**
173         * Return whether this bean is a candidate for getting autowired into some other bean.
174         */
175        boolean isAutowireCandidate();
176
177        /**
178         * Set whether this bean is a primary autowire candidate.
179         * <p>If this value is {@code true} for exactly one bean among multiple
180         * matching candidates, it will serve as a tie-breaker.
181         */
182        void setPrimary(boolean primary);
183
184        /**
185         * Return whether this bean is a primary autowire candidate.
186         */
187        boolean isPrimary();
188
189        /**
190         * Specify the factory bean to use, if any.
191         * This the name of the bean to call the specified factory method on.
192         * @see #setFactoryMethodName
193         */
194        void setFactoryBeanName(@Nullable String factoryBeanName);
195
196        /**
197         * Return the factory bean name, if any.
198         */
199        @Nullable
200        String getFactoryBeanName();
201
202        /**
203         * Specify a factory method, if any. This method will be invoked with
204         * constructor arguments, or with no arguments if none are specified.
205         * The method will be invoked on the specified factory bean, if any,
206         * or otherwise as a static method on the local bean class.
207         * @see #setFactoryBeanName
208         * @see #setBeanClassName
209         */
210        void setFactoryMethodName(@Nullable String factoryMethodName);
211
212        /**
213         * Return a factory method, if any.
214         */
215        @Nullable
216        String getFactoryMethodName();
217
218        /**
219         * Return the constructor argument values for this bean.
220         * <p>The returned instance can be modified during bean factory post-processing.
221         * @return the ConstructorArgumentValues object (never {@code null})
222         */
223        ConstructorArgumentValues getConstructorArgumentValues();
224
225        /**
226         * Return if there are constructor argument values defined for this bean.
227         * @since 5.0.2
228         */
229        default boolean hasConstructorArgumentValues() {
230                return !getConstructorArgumentValues().isEmpty();
231        }
232
233        /**
234         * Return the property values to be applied to a new instance of the bean.
235         * <p>The returned instance can be modified during bean factory post-processing.
236         * @return the MutablePropertyValues object (never {@code null})
237         */
238        MutablePropertyValues getPropertyValues();
239
240        /**
241         * Return if there are property values defined for this bean.
242         * @since 5.0.2
243         */
244        default boolean hasPropertyValues() {
245                return !getPropertyValues().isEmpty();
246        }
247
248        /**
249         * Set the name of the initializer method.
250         * @since 5.1
251         */
252        void setInitMethodName(@Nullable String initMethodName);
253
254        /**
255         * Return the name of the initializer method.
256         * @since 5.1
257         */
258        @Nullable
259        String getInitMethodName();
260
261        /**
262         * Set the name of the destroy method.
263         * @since 5.1
264         */
265        void setDestroyMethodName(@Nullable String destroyMethodName);
266
267        /**
268         * Return the name of the destroy method.
269         * @since 5.1
270         */
271        @Nullable
272        String getDestroyMethodName();
273
274        /**
275         * Set the role hint for this {@code BeanDefinition}. The role hint
276         * provides the frameworks as well as tools an indication of
277         * the role and importance of a particular {@code BeanDefinition}.
278         * @since 5.1
279         * @see #ROLE_APPLICATION
280         * @see #ROLE_SUPPORT
281         * @see #ROLE_INFRASTRUCTURE
282         */
283        void setRole(int role);
284
285        /**
286         * Get the role hint for this {@code BeanDefinition}. The role hint
287         * provides the frameworks as well as tools an indication of
288         * the role and importance of a particular {@code BeanDefinition}.
289         * @see #ROLE_APPLICATION
290         * @see #ROLE_SUPPORT
291         * @see #ROLE_INFRASTRUCTURE
292         */
293        int getRole();
294
295        /**
296         * Set a human-readable description of this bean definition.
297         * @since 5.1
298         */
299        void setDescription(@Nullable String description);
300
301        /**
302         * Return a human-readable description of this bean definition.
303         */
304        @Nullable
305        String getDescription();
306
307
308        // Read-only attributes
309
310        /**
311         * Return a resolvable type for this bean definition,
312         * based on the bean class or other specific metadata.
313         * <p>This is typically fully resolved on a runtime-merged bean definition
314         * but not necessarily on a configuration-time definition instance.
315         * @return the resolvable type (potentially {@link ResolvableType#NONE})
316         * @since 5.2
317         * @see ConfigurableBeanFactory#getMergedBeanDefinition
318         */
319        ResolvableType getResolvableType();
320
321        /**
322         * Return whether this a <b>Singleton</b>, with a single, shared instance
323         * returned on all calls.
324         * @see #SCOPE_SINGLETON
325         */
326        boolean isSingleton();
327
328        /**
329         * Return whether this a <b>Prototype</b>, with an independent instance
330         * returned for each call.
331         * @since 3.0
332         * @see #SCOPE_PROTOTYPE
333         */
334        boolean isPrototype();
335
336        /**
337         * Return whether this bean is "abstract", that is, not meant to be instantiated.
338         */
339        boolean isAbstract();
340
341        /**
342         * Return a description of the resource that this bean definition
343         * came from (for the purpose of showing context in case of errors).
344         */
345        @Nullable
346        String getResourceDescription();
347
348        /**
349         * Return the originating BeanDefinition, or {@code null} if none.
350         * <p>Allows for retrieving the decorated bean definition, if any.
351         * <p>Note that this method returns the immediate originator. Iterate through the
352         * originator chain to find the original BeanDefinition as defined by the user.
353         */
354        @Nullable
355        BeanDefinition getOriginatingBeanDefinition();
356
357}