Mastering Spring Bean Definitions: Naming, Aliases, and Instantiation

1 BeanDefinition Metadata

Spring creates beans from configuration metadata such as @Bean -annotated methods. Internally each bean is represented by a BeanDefinition object that stores attributes describing the bean class name, scope, lifecycle callbacks, required dependencies, and other properties.

Bean Class and Implementation

The actual implementation class of a defined bean is shown in the diagram.

Bean Scope and Behavior

Bean scope indicates how the container manages the bean's lifecycle. The default scope is singleton .

Other Bean References

Beans can depend on other beans; these dependencies are expressed as references in the metadata.

The container registers external objects via DefaultListableBeanFactory.registerSingleton or registerBeanDefinition. registerSingleton(String beanName, Object singletonObject) registers an existing instance.

registerBeanDefinition(String beanName, BeanDefinition beanDefinition)

registers a definition that the container will instantiate.

2 Bean Naming

Each bean must have a unique identifier within its container. The identifier can be specified using the id attribute (single name) and the name attribute (multiple aliases separated by commas, semicolons, or spaces). Since Spring 3.1 the id attribute is a plain string, but uniqueness is still enforced.

Multiple names are treated as aliases, allowing different components to refer to the same bean using distinct names.

2.1 Naming Conventions

Bean names follow the same convention as Java field names: lower‑case first letter followed by camel‑case (e.g., userService, roleController).

When scanning classpath components, Spring generates a bean name by decapitalizing the simple class name using java.beans.Introspector.decapitalize:

public static String decapitalize(String name) {
    if (name == null || name.length() == 0) {
        return name;
    }
    // If the first two characters are both uppercase, keep the name unchanged
    if (name.length() > 1 && Character.isUpperCase(name.charAt(1)) &&
        Character.isUpperCase(name.charAt(0))) {
        return name;
    }
    char[] chars = name.toCharArray();
    chars[0] = Character.toLowerCase(chars[0]);
    return new String(chars);
}

2.2 Multiple Aliases for a Single Bean

XML configuration uses the <alias> tag: <alias name="srcName" alias="extName"/> Java configuration can provide an array of names to the name attribute of @Bean:

@Configuration
public class AppConfig {
    @Bean({"dataSource", "subA-ds", "subB-ds"})
    public DataSource dataSource() {
        // ...
    }
}

3 Bean Instantiation

A BeanDefinition acts as a recipe for creating an object. The container consults the definition when a bean is requested and either creates a new instance or returns a cached one.

3.1 Constructor Instantiation

The container uses the class specified in the class attribute (or the method return type) to instantiate the bean, typically via a no‑argument constructor unless a specific constructor is selected.

3.2 Static Factory Method

When a static factory method is used, the class attribute points to the class containing the method, and factory-method specifies the method name.

<bean id="serverService" class="examples.ServerService" factory-method="initInstance"/>

Corresponding class example:

public class ServerService {
    private static ServerService serverService = new ServerService();
    private ServerService() {}
    public static ServerService createInstance() {
        return serverService;
    }
}

3.3 Instance Factory Method

For an instance factory method, the factory-bean attribute references an existing bean that contains the non‑static method, while factory-method names the method to invoke.

4 Determining a Bean's Runtime Type

The bean definition may specify a class, a factory method, or a FactoryBean, making the actual runtime type non‑trivial to infer. The recommended way to obtain the concrete type is to call BeanFactory.getType(String beanName), which returns the type that a subsequent getBean call would produce, handling FactoryBean cases correctly.

Class<?> type = beanFactory.getType("myBean");

This method considers all possible bean creation paths and returns the most accurate runtime class.

Reference: https://spring.io