Defining Beans with @Configuration and @Bean

The Basics: @Configuration and @Bean

The two central pieces of Java-based configuration are the @Configuration and @Bean annotations.

• @Configuration: This is a class-level annotation. It signals to the Spring container that the primary purpose of this class is to be a source of bean definitions.
• @Bean: This is a method-level annotation. When you annotate a method with @Bean, you are telling Spring that this method will produce a bean to be managed by the container. The object returned by the method is the bean instance. By default, the name of the method becomes the bean's name (its unique identifier in the container).

Let's start by reading the official definitions from the Spring documentation.

The relationship between these annotations can be visualized as follows: a @Configuration class acts as a factory for creating one or more beans defined by @Bean methods.

A Practical Demonstration

Theory is good, but seeing it in action makes it concrete. Let's watch a video that walks through creating beans using this explicit approach. The example involves a PaymentService interface with multiple implementations, which is a common scenario in application design.

As you saw, this method gives you explicit control. You are writing the instantiation logic yourself (return new CreditCardService();), and Spring takes over the management of the returned object.

When to Use @Configuration and @Bean

So far, we have two ways to declare beans:

1. Component Scanning: Using @Component (and its specializations @Service, @Repository, @Controller) on your classes.
2. Java Configuration: Using @Bean methods inside a @Configuration class.

When should you choose one over the other? The decision reflects important design considerations.

To summarize and expand on those points, you should use @Configuration and @Bean when:

• Integrating Third-Party Code: This is the most common and compelling reason. You need to create a bean from a class in an external library (e.g., RestTemplate, ObjectMapper, a DataSource). You can't add @Component to that class, so you must define it yourself.
• Complex Instantiation Logic: If creating an object requires complex logic, such as reading from configuration files, making decisions based on environment variables, or calling a static factory method, a @Bean method is the perfect place to encapsulate this logic.
• Defining Beans for Interfaces: As shown in the video, when you're working with interfaces and have multiple implementations, a configuration class can be a clean way to define which implementations should be available as beans.
• Centralizing Configuration: From a system design perspective, grouping related bean definitions into logical configuration classes (PersistenceConfig, SecurityConfig, ApiConfig) can make the application's structure clearer and easier to manage, rather than scattering @Component annotations across many files.

The following code example shows several of these principles in practice, defining beans for different MessageService implementations and injecting one of them into another bean.

Inter-Bean Dependencies and the Magic of CGLIB

In the image above, you saw that the messageProcessor() bean method directly calls the twitterService() method.

@Bean
public MessageProcessor messageProcessor() {
    // A direct call to another @Bean method
    return new MessageProcessor(twitterService()); 
}

A critical question for anyone interested in the underlying mechanics is: what happens when we call twitterService()? Does this create a new instance of TwitterService every time messageProcessor() is called, or does it correctly reuse the singleton bean that Spring is managing?

The answer lies in how Spring processes @Configuration classes. Spring creates a runtime subclass (a proxy) of your configuration class using a library called CGLIB. This proxy intercepts calls to your @Bean methods. When you call twitterService(), the proxy first checks the IoC container to see if a twitterService bean already exists.

• If it exists, the proxy returns the existing singleton instance.
• If it doesn't exist, the proxy calls the original method, creates the bean, registers it in the container, and then returns it.

This ensures that even with direct method calls between @Bean methods, Spring's singleton scope is honored.

This distinction between "full" mode (with @Configuration and proxying) and "lite" mode (without proxying) is an important detail. For most cases, you will want the "full" mode to correctly manage relationships between your beans. The Spring documentation also covers this distinction formally. You don't need to read it now, but it's good to know where to find the official explanation (LINK, section 1).

Conclusion

Today, we've added a second powerful tool to our Spring toolbox. While component scanning is excellent for its convenience and convention-over-configuration approach, Java-based configuration with @Configuration and @Bean provides the explicit control needed for more complex scenarios and third-party integrations.

Key Takeaways:

• Explicit Definition: Use @Configuration on a class and @Bean on methods within it to explicitly define Spring beans. This is an alternative to automatic component scanning.
• Primary Use Case: This method is essential for creating beans from classes you don't control, such as those from external libraries.
• Fine-Grained Control: @Bean methods allow you to implement custom logic for bean creation, configuration, and initialization.
• Inter-Bean Dependencies: When a @Configuration class is used, Spring creates a proxy that intercepts calls to @Bean methods, ensuring that singleton beans are correctly shared and not re-created on every call.
• Clean Design: Grouping related beans into dedicated configuration classes (PersistenceConfig, WebConfig) can lead to a more modular and understandable application architecture.

In the video demonstration, we created two beans (GooglePayService and CreditCardService) that both implement the PaymentService interface. This raises an interesting question: if a component needs a PaymentService injected, how does Spring know which of the two beans to provide? Resolving this ambiguity is the topic of our next lesson, where we'll explore the @Qualifier annotation.