4/22/25, 12:06 PM Bean Overview :: Spring Framework

Spring Framework / Core Technologies / The IoC Container / Bean Overview

Bean Overview
Bean Overview
Overriding Beans
Naming Beans
Aliasing a Bean outside the Bean Definition
Instantiating Beans
Instantiation with a Constructor
Instantiation with a Static Factory Method
Instantiation by Using an Instance Factory Method
Determining a Bean’s Runtime Type
A Spring IoC container manages one or more beans. These beans are created with the configuration metadata that you supply to the container (for example, in
the form of XML <bean/> definitions).
Within the container itself, these bean definitions are represented as BeanDefinition objects, which contain (among other information) the following
metadata:
A package-qualified class name: typically, the actual implementation class of the bean being defined.
Bean behavioral configuration elements, which state how the bean should behave in the container (scope, lifecycle callbacks, and so forth).
References to other beans that are needed for the bean to do its work. These references are also called collaborators or dependencies.
Other configuration settings to set in the newly created object — for example, the size limit of the pool or the number of connections to use in a bean that
manages a connection pool.
This metadata translates to a set of properties that make up each bean definition. The following table describes these properties:
Table 1. The bean definition
Property Explained in…​
Class Instantiating Beans
Name Naming Beans
Scope Bean Scopes
Constructor arguments Dependency Injection
Properties Dependency Injection
Autowiring mode Autowiring Collaborators
Lazy initialization mode Lazy-initialized Beans
Initialization method Initialization Callbacks
Destruction method Destruction Callbacks

In addition to bean definitions that contain information on how to create a specific bean, the ApplicationContext implementations also permit the registra‐
tion of existing objects that are created outside the container (by users). This is done by accessing the ApplicationContext’s BeanFactory through the
getAutowireCapableBeanFactory() method, which returns the DefaultListableBeanFactory implementation. DefaultListableBeanFactory sup‐
ports this registration through the registerSingleton(..) and registerBeanDefinition(..) methods. However, typical applications work solely with
beans defined through regular bean definition metadata.
Bean metadata and manually supplied singleton instances need to be registered as early as possible, in order for the container to properly reason about them during au‐
towiring and other introspection steps. While overriding existing metadata and existing singleton instances is supported to some degree, the registration of new beans at
runtime (concurrently with live access to the factory) is not officially supported and may lead to concurrent access exceptions, inconsistent state in the bean container, or
both.

Overriding Beans
Bean overriding occurs when a bean is registered using an identifier that is already allocated. While bean overriding is possible, it makes the configuration hard‐
er to read.
Bean overriding will be deprecated in a future release.

https://docs.spring.io/spring-framework/reference/core/beans/definition.html 1/5
4/22/25, 12:06 PM Bean Overview :: Spring Framework

To disable bean overriding altogether, you can set the allowBeanDefinitionOverriding flag to false on the ApplicationContext before it is refreshed.
In such a setup, an exception is thrown if bean overriding is used.
By default, the container logs every attempt to override a bean at INFO level so that you can adapt your configuration accordingly. While not recommended,
you can silence those logs by setting the allowBeanDefinitionOverriding flag to true .

Java Configuration
If you use Java Configuration, a corresponding @Bean method always silently overrides a scanned bean class with the same component name as long as
the return type of the @Bean method matches that bean class. This simply means that the container will call the @Bean factory method in favor of any
pre-declared constructor on the bean class.

We acknowledge that overriding beans in test scenarios is convenient, and there is explicit support for this as of Spring Framework 6.2. Please refer to this section for more
details.

Naming Beans
Every bean has one or more identifiers. These identifiers must be unique within the container that hosts the bean. A bean usually has only one identifier.
However, if it requires more than one, the extra ones can be considered aliases.
In XML-based configuration metadata, you use the id attribute, the name attribute, or both to specify bean identifiers. The id attribute lets you specify ex‐
actly one id . Conventionally, these names are alphanumeric ('myBean', 'someService', etc.), but they can contain special characters as well. If you want to in‐
troduce other aliases for the bean, you can also specify them in the name attribute, separated by a comma ( , ), semicolon ( ; ), or white space. Although the
id attribute is defined as an xsd:string type, bean id uniqueness is enforced by the container, though not by XML parsers.

You are not required to supply a name or an id for a bean. If you do not supply a name or id explicitly, the container generates a unique name for that bean.
However, if you want to refer to that bean by name, through the use of the ref element or a Service Locator style lookup, you must provide a name.
Motivations for not supplying a name are related to using inner beans and autowiring collaborators.

Bean Naming Conventions

The convention is to use the standard Java convention for instance field names when naming beans. That is, bean names start with a lowercase letter and
are camel-cased from there. Examples of such names include accountManager , accountService , userDao , loginController , and so forth.
Naming beans consistently makes your configuration easier to read and understand. Also, if you use Spring AOP, it helps a lot when applying advice to a
set of beans related by name.

With component scanning in the classpath, Spring generates bean names for unnamed components, following the rules described earlier: essentially, taking the simple
class name and turning its initial character to lower-case. However, in the (unusual) special case when there is more than one character and both the first and second char‐
acters are upper case, the original casing gets preserved. These are the same rules as defined by java.beans.Introspector.decapitalize (which Spring uses here).

Aliasing a Bean outside the Bean Definition

In a bean definition itself, you can supply more than one name for the bean, by using a combination of up to one name specified by the id attribute and any
number of other names in the name attribute. These names can be equivalent aliases to the same bean and are useful for some situations, such as letting each
component in an application refer to a common dependency by using a bean name that is specific to that component itself.
Specifying all aliases where the bean is actually defined is not always adequate, however. It is sometimes desirable to introduce an alias for a bean that is de‐
fined elsewhere. This is commonly the case in large systems where configuration is split amongst each subsystem, with each subsystem having its own set of
object definitions. In XML-based configuration metadata, you can use the <alias/> element to accomplish this. The following example shows how to do so:
XML
<alias name="fromName" alias="toName"/>

In this case, a bean (in the same container) named fromName may also, after the use of this alias definition, be referred to as toName .
For example, the configuration metadata for subsystem A may refer to a DataSource by the name of subsystemA-dataSource . The configuration metadata for
subsystem B may refer to a DataSource by the name of subsystemB-dataSource . When composing the main application that uses both these subsystems,
the main application refers to the DataSource by the name of myApp-dataSource . To have all three names refer to the same object, you can add the following
alias definitions to the configuration metadata:
XML
<alias name="myApp-dataSource" alias="subsystemA-dataSource"/>
<alias name="myApp-dataSource" alias="subsystemB-dataSource"/>

Now each component and the main application can refer to the dataSource through a name that is unique and guaranteed not to clash with any other definition
(effectively creating a namespace), yet they refer to the same bean.

https://docs.spring.io/spring-framework/reference/core/beans/definition.html 2/5
4/22/25, 12:06 PM Bean Overview :: Spring Framework

Java-configuration
If you use Java Configuration, the @Bean annotation can be used to provide aliases. See Using the @Bean Annotation for details.

Instantiating Beans
A bean definition is essentially a recipe for creating one or more objects. The container looks at the recipe for a named bean when asked and uses the configu‐
ration metadata encapsulated by that bean definition to create (or acquire) an actual object.
If you use XML-based configuration metadata, you specify the type (or class) of object that is to be instantiated in the class attribute of the <bean/> ele‐
ment. This class attribute (which, internally, is a Class property on a BeanDefinition instance) is usually mandatory. (For exceptions, see Instantiation by
Using an Instance Factory Method and Bean Definition Inheritance.) You can use the Class property in one of two ways:
Typically, to specify the bean class to be constructed in the case where the container itself directly creates the bean by calling its constructor reflectively,
somewhat equivalent to Java code with the new operator.
To specify the actual class containing the static factory method that is invoked to create the object, in the less common case where the container in‐
vokes a static factory method on a class to create the bean. The object type returned from the invocation of the static factory method may be the
same class or another class entirely.

Nested class names

If you want to configure a bean definition for a nested class, you may use either the binary name or the source name of the nested class.
For example, if you have a class called SomeThing in the com.example package, and this SomeThing class has a static nested class called
OtherThing , they can be separated by a dollar sign ( $ ) or a dot ( . ). So the value of the class attribute in a bean definition would be
com.example.SomeThing$OtherThing or com.example.SomeThing.OtherThing .

Instantiation with a Constructor

When you create a bean by the constructor approach, all normal classes are usable by and compatible with Spring. That is, the class being developed does not
need to implement any specific interfaces or to be coded in a specific fashion. Simply specifying the bean class should suffice. However, depending on what
type of IoC you use for that specific bean, you may need a default (empty) constructor.
The Spring IoC container can manage virtually any class you want it to manage. It is not limited to managing true JavaBeans. Most Spring users prefer actual
JavaBeans with only a default (no-argument) constructor and appropriate setters and getters modeled after the properties in the container. You can also have
more exotic non-bean-style classes in your container. If, for example, you need to use a legacy connection pool that absolutely does not adhere to the JavaBean
specification, Spring can manage it as well.
With XML-based configuration metadata you can specify your bean class as follows:
XML
<bean id="exampleBean" class="examples.ExampleBean"/>

<bean name="anotherExample" class="examples.ExampleBeanTwo"/>

For details about the mechanism for supplying arguments to the constructor (if required) and setting object instance properties after the object is constructed,
see Injecting Dependencies.
In the case of constructor arguments, the container can select a corresponding constructor among several overloaded constructors. That said, to avoid ambiguities, it is
recommended to keep your constructor signatures as straightforward as possible.

Instantiation with a Static Factory Method

When defining a bean that you create with a static factory method, use the class attribute to specify the class that contains the static factory method and
an attribute named factory-method to specify the name of the factory method itself. You should be able to call this method (with optional arguments, as de‐
scribed later) and return a live object, which subsequently is treated as if it had been created through a constructor. One use for such a bean definition is to call
static factories in legacy code.

The following bean definition specifies that the bean will be created by calling a factory method. The definition does not specify the type (class) of the returned
object, but rather the class containing the factory method. In this example, the createInstance() method must be a static method. The following example
shows how to specify a factory method:
XML
<bean id="clientService"
class="examples.ClientService"
factory-method="createInstance"/>

The following example shows a class that would work with the preceding bean definition:

https://docs.spring.io/spring-framework/reference/core/beans/definition.html 3/5
4/22/25, 12:06 PM Bean Overview :: Spring Framework

Java Kotlin
JAVA
public class ClientService {
private static ClientService clientService = new ClientService();
private ClientService() {}

public static ClientService createInstance() {

return clientService;
}
}

For details about the mechanism for supplying (optional) arguments to the factory method and setting object instance properties after the object is returned
from the factory, see Dependencies and Configuration in Detail.
In the case of factory method arguments, the container can select a corresponding method among several overloaded methods of the same name. That said, to avoid ambi‐
guities, it is recommended to keep your factory method signatures as straightforward as possible.

A typical problematic case with factory method overloading is Mockito with its many overloads of the mock method. Choose the most specific variant of mock possible:
<bean id="clientService" class="org.mockito.Mockito" factory-method="mock">
<constructor-arg type="java.lang.Class" value="examples.ClientService"/>
<constructor-arg type="java.lang.String" value="clientService"/>
</bean>

Instantiation by Using an Instance Factory Method

Similar to instantiation through a static factory method , instantiation with an instance factory method invokes a non-static method of an existing bean from the
container to create a new bean. To use this mechanism, leave the class attribute empty and, in the factory-bean attribute, specify the name of a bean in
the current (or parent or ancestor) container that contains the instance method that is to be invoked to create the object. Set the name of the factory method it‐
self with the factory-method attribute. The following example shows how to configure such a bean:
XML
<!-- the factory bean, which contains a method called createClientServiceInstance() -->
<bean id="serviceLocator" class="examples.DefaultServiceLocator">
<!-- inject any dependencies required by this locator bean -->
</bean>

<!-- the bean to be created via the factory bean -->

<bean id="clientService"
factory-bean="serviceLocator"
factory-method="createClientServiceInstance"/>

The following example shows the corresponding class:

Java Kotlin
JAVA
public class DefaultServiceLocator {

private static ClientService clientService = new ClientServiceImpl();

public ClientService createClientServiceInstance() {

return clientService;
}
}

One factory class can also hold more than one factory method, as the following example shows:
XML
<bean id="serviceLocator" class="examples.DefaultServiceLocator">
<!-- inject any dependencies required by this locator bean -->
</bean>

<bean id="clientService"
factory-bean="serviceLocator"
factory-method="createClientServiceInstance"/>

<bean id="accountService"
factory-bean="serviceLocator"
factory-method="createAccountServiceInstance"/>

The following example shows the corresponding class:

Java Kotlin
JAVA
public class DefaultServiceLocator {

private static ClientService clientService = new ClientServiceImpl();

https://docs.spring.io/spring-framework/reference/core/beans/definition.html 4/5
4/22/25, 12:06 PM Bean Overview :: Spring Framework

private static AccountService accountService = new AccountServiceImpl();

public ClientService createClientServiceInstance() {

return clientService;
}

public AccountService createAccountServiceInstance() {

return accountService;
}
}

This approach shows that the factory bean itself can be managed and configured through dependency injection (DI). See Dependencies and Configuration in
Detail.
In Spring documentation, "factory bean" refers to a bean that is configured in the Spring container and that creates objects through an instance or static factory method. By
contrast, FactoryBean (notice the capitalization) refers to a Spring-specific FactoryBean implementation class.

Determining a Bean’s Runtime Type

The runtime type of a specific bean is non-trivial to determine. A specified class in the bean metadata definition is just an initial class reference, potentially com‐
bined with a declared factory method or being a FactoryBean class which may lead to a different runtime type of the bean, or not being set at all in case of an
instance-level factory method (which is resolved via the specified factory-bean name instead). Additionally, AOP proxying may wrap a bean instance with an
interface-based proxy with limited exposure of the target bean’s actual type (just its implemented interfaces).
The recommended way to find out about the actual runtime type of a particular bean is a BeanFactory.getType call for the specified bean name. This takes
all of the above cases into account and returns the type of object that a BeanFactory.getBean call is going to return for the same bean name.

Copyright © 2005 - 2025 Broadcom. All Rights Reserved. The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.
Terms of Use • Privacy • Trademark Guidelines • Thank you • Your California Privacy Rights •

Apache®, Apache Tomcat®, Apache Kafka®, Apache Cassandra™, and Apache Geode™ are trademarks or registered trademarks of the Apache Software
Foundation in the United States and/or other countries. Java™, Java™ SE, Java™ EE, and OpenJDK™ are trademarks of Oracle and/or its affiliates. Kubernetes® is a
registered trademark of the Linux Foundation in the United States and other countries. Linux® is the registered trademark of Linus Torvalds in the United States
and other countries. Windows® and Microsoft® Azure are registered trademarks of Microsoft Corporation. “AWS” and “Amazon Web Services” are trademarks or
registered trademarks of Amazon.com Inc. or its affiliates. All other trademarks and copyrights are property of their respective owners and are only mentioned for
informative purposes. Other names may be trademarks of their respective owners.

https://docs.spring.io/spring-framework/reference/core/beans/definition.html 5/5