org.springframework.context.annotation.Configuration Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of spring-context Show documentation
Spring Context
The newest version!
/*
 * Copyright 2002-2023 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.context.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.core.annotation.AliasFor;
import org.springframework.stereotype.Component;

/**
 * Indicates that a class declares one or more {@link Bean @Bean} methods and
 * may be processed by the Spring container to generate bean definitions and
 * service requests for those beans at runtime, for example:
 *
 *  * @Configuration
 * public class AppConfig {
 *
 *     @Bean
 *     public MyBean myBean() {
 *         // instantiate, configure and return bean ...
 *     }
 * }
 *
 * Bootstrapping {@code @Configuration} classes
 *
 * Via {@code AnnotationConfigApplicationContext}
 *
 * {@code @Configuration} classes are typically bootstrapped using either
 * {@link AnnotationConfigApplicationContext} or its web-capable variant,
 * {@link org.springframework.web.context.support.AnnotationConfigWebApplicationContext
 * AnnotationConfigWebApplicationContext}. A simple example with the former follows:
 *
 * 
 * AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext();
 * ctx.register(AppConfig.class);
 * ctx.refresh();
 * MyBean myBean = ctx.getBean(MyBean.class);
 * // use myBean ...
 * 
 *
 * See the {@link AnnotationConfigApplicationContext} javadocs for further details, and see
 * {@link org.springframework.web.context.support.AnnotationConfigWebApplicationContext
 * AnnotationConfigWebApplicationContext} for web configuration instructions in a
 * {@code Servlet} container.
 *
 * 
Via Spring {@code } XML
 *
 * As an alternative to registering {@code @Configuration} classes directly against an
 * {@code AnnotationConfigApplicationContext}, {@code @Configuration} classes may be
 * declared as normal {@code } definitions within Spring XML files:
 *
 * 
 * <beans>
 *    <context:annotation-config/>
 *    <bean class="com.acme.AppConfig"/>
 * </beans>
 * 
 *
 * In the example above, {@code } is required in order to
 * enable {@link ConfigurationClassPostProcessor} and other annotation-related
 * post processors that facilitate handling {@code @Configuration} classes.
 *
 * 
Via component scanning
 *
 * Since {@code @Configuration} is meta-annotated with {@link Component @Component},
 * {@code @Configuration} classes are candidates for component scanning —
 * for example, using {@link ComponentScan @ComponentScan} or Spring XML's
 * {@code } element — and therefore may also take
 * advantage of {@link Autowired @Autowired}/{@link jakarta.inject.Inject @Inject}
 * like any regular {@code @Component}. In particular, if a single constructor is
 * present, autowiring semantics will be applied transparently for that constructor:
 *
 * 
 * @Configuration
 * public class AppConfig {
 *
 *     private final SomeBean someBean;
 *
 *     public AppConfig(SomeBean someBean) {
 *         this.someBean = someBean;
 *     }
 *
 *     // @Bean definition using "SomeBean"
 *
 * }
 *
 * {@code @Configuration} classes may not only be bootstrapped using component
 * scanning, but may also themselves configure component scanning using
 * the {@link ComponentScan @ComponentScan} annotation:
 *
 * 
 * @Configuration
 * @ComponentScan("com.acme.app.services")
 * public class AppConfig {
 *     // various @Bean definitions ...
 * }
 *
 * See the {@link ComponentScan @ComponentScan} javadocs for details.
 *
 * 
Working with externalized values
 *
 * Using the {@code Environment} API
 *
 * Externalized values may be looked up by injecting the Spring
 * {@link org.springframework.core.env.Environment} into a {@code @Configuration}
 * class — for example, using the {@code @Autowired} annotation:
 *
 * 
 * @Configuration
 * public class AppConfig {
 *
 *     @Autowired Environment env;
 *
 *     @Bean
 *     public MyBean myBean() {
 *         MyBean myBean = new MyBean();
 *         myBean.setName(env.getProperty("bean.name"));
 *         return myBean;
 *     }
 * }
 *
 * Properties resolved through the {@code Environment} reside in one or more "property
 * source" objects, and {@code @Configuration} classes may contribute property sources to
 * the {@code Environment} object using the {@link PropertySource @PropertySource}
 * annotation:
 *
 * 
 * @Configuration
 * @PropertySource("classpath:/com/acme/app.properties")
 * public class AppConfig {
 *
 *     @Inject Environment env;
 *
 *     @Bean
 *     public MyBean myBean() {
 *         return new MyBean(env.getProperty("bean.name"));
 *     }
 * }
 *
 * See the {@link org.springframework.core.env.Environment Environment}
 * and {@link PropertySource @PropertySource} javadocs for further details.
 *
 * 
Using the {@code @Value} annotation
 *
 * Externalized values may be injected into {@code @Configuration} classes using
 * the {@link Value @Value} annotation:
 *
 * 
 * @Configuration
 * @PropertySource("classpath:/com/acme/app.properties")
 * public class AppConfig {
 *
 *     @Value("${bean.name}") String beanName;
 *
 *     @Bean
 *     public MyBean myBean() {
 *         return new MyBean(beanName);
 *     }
 * }
 *
 * This approach is often used in conjunction with Spring's
 * {@link org.springframework.context.support.PropertySourcesPlaceholderConfigurer
 * PropertySourcesPlaceholderConfigurer} that can be enabled automatically
 * in XML configuration via {@code } or explicitly
 * in a {@code @Configuration} class via a dedicated {@code static} {@code @Bean} method
 * (see "a note on BeanFactoryPostProcessor-returning {@code @Bean} methods" of
 * {@link Bean @Bean}'s javadocs for details). Note, however, that explicit registration
 * of a {@code PropertySourcesPlaceholderConfigurer} via a {@code static} {@code @Bean}
 * method is typically only required if you need to customize configuration such as the
 * placeholder syntax, etc. Specifically, if no bean post-processor (such as a
 * {@code PropertySourcesPlaceholderConfigurer}) has registered an embedded value
 * resolver for the {@code ApplicationContext}, Spring will register a default
 * embedded value resolver which resolves placeholders against property sources
 * registered in the {@code Environment}. See the section below on composing
 * {@code @Configuration} classes with Spring XML using {@code @ImportResource}; see
 * the {@link Value @Value} javadocs; and see the {@link Bean @Bean} javadocs for details
 * on working with {@code BeanFactoryPostProcessor} types such as
 * {@code PropertySourcesPlaceholderConfigurer}.
 *
 * 
Composing {@code @Configuration} classes
 *
 * With the {@code @Import} annotation
 *
 * {@code @Configuration} classes may be composed using the {@link Import @Import} annotation,
 * similar to the way that {@code } works in Spring XML. Because
 * {@code @Configuration} objects are managed as Spring beans within the container,
 * imported configurations may be injected — for example, via constructor injection:
 *
 * 
 * @Configuration
 * public class DatabaseConfig {
 *
 *     @Bean
 *     public DataSource dataSource() {
 *         // instantiate, configure and return DataSource
 *     }
 * }
 *
 * @Configuration
 * @Import(DatabaseConfig.class)
 * public class AppConfig {
 *
 *     private final DatabaseConfig dataConfig;
 *
 *     public AppConfig(DatabaseConfig dataConfig) {
 *         this.dataConfig = dataConfig;
 *     }
 *
 *     @Bean
 *     public MyBean myBean() {
 *         // reference the dataSource() bean method
 *         return new MyBean(dataConfig.dataSource());
 *     }
 * }
 *
 * Now both {@code AppConfig} and the imported {@code DatabaseConfig} can be bootstrapped
 * by registering only {@code AppConfig} against the Spring context:
 *
 * 
 * new AnnotationConfigApplicationContext(AppConfig.class);
 *
 * With the {@code @Profile} annotation
 *
 * {@code @Configuration} classes may be marked with the {@link Profile @Profile} annotation to
 * indicate they should be processed only if a given profile or profiles are active:
 *
 * 
 * @Profile("development")
 * @Configuration
 * public class EmbeddedDatabaseConfig {
 *
 *     @Bean
 *     public DataSource dataSource() {
 *         // instantiate, configure and return embedded DataSource
 *     }
 * }
 *
 * @Profile("production")
 * @Configuration
 * public class ProductionDatabaseConfig {
 *
 *     @Bean
 *     public DataSource dataSource() {
 *         // instantiate, configure and return production DataSource
 *     }
 * }
 *
 * Alternatively, you may also declare profile conditions at the {@code @Bean} method level
 * — for example, for alternative bean variants within the same configuration class:
 *
 * 
 * @Configuration
 * public class ProfileDatabaseConfig {
 *
 *     @Bean("dataSource")
 *     @Profile("development")
 *     public DataSource embeddedDatabase() { ... }
 *
 *     @Bean("dataSource")
 *     @Profile("production")
 *     public DataSource productionDatabase() { ... }
 * }
 *
 * See the {@link Profile @Profile} and {@link org.springframework.core.env.Environment}
 * javadocs for further details.
 *
 * 
With Spring XML using the {@code @ImportResource} annotation
 *
 * As mentioned above, {@code @Configuration} classes may be declared as regular Spring
 * {@code } definitions within Spring XML files. It is also possible to
 * import Spring XML configuration files into {@code @Configuration} classes using
 * the {@link ImportResource @ImportResource} annotation. Bean definitions imported from
 * XML can be injected — for example, using the {@code @Inject} annotation:
 *
 * 
 * @Configuration
 * @ImportResource("classpath:/com/acme/database-config.xml")
 * public class AppConfig {
 *
 *     @Inject DataSource dataSource; // from XML
 *
 *     @Bean
 *     public MyBean myBean() {
 *         // inject the XML-defined dataSource bean
 *         return new MyBean(this.dataSource);
 *     }
 * }
 *
 * With nested {@code @Configuration} classes
 *
 * {@code @Configuration} classes may be nested within one another as follows:
 *
 * 
 * @Configuration
 * public class AppConfig {
 *
 *     @Inject DataSource dataSource;
 *
 *     @Bean
 *     public MyBean myBean() {
 *         return new MyBean(dataSource);
 *     }
 *
 *     @Configuration
 *     static class DatabaseConfig {
 *         @Bean
 *         DataSource dataSource() {
 *             return new EmbeddedDatabaseBuilder().build();
 *         }
 *     }
 * }
 *
 * When bootstrapping such an arrangement, only {@code AppConfig} need be registered
 * against the application context. By virtue of being a nested {@code @Configuration}
 * class, {@code DatabaseConfig} will be registered automatically. This avoids
 * the need to use an {@code @Import} annotation when the relationship between
 * {@code AppConfig} and {@code DatabaseConfig} is already implicitly clear.
 *
 * 
Note also that nested {@code @Configuration} classes can be used to good effect
 * with the {@code @Profile} annotation to provide two options of the same bean to the
 * enclosing {@code @Configuration} class.
 *
 * 
Configuring lazy initialization
 *
 * By default, {@code @Bean} methods will be eagerly instantiated at container
 * bootstrap time.  To avoid this, {@code @Configuration} may be used in conjunction with
 * the {@link Lazy @Lazy} annotation to indicate that all {@code @Bean} methods declared
 * within the class are by default lazily initialized. Note that {@code @Lazy} may be used
 * on individual {@code @Bean} methods as well.
 *
 * 
Testing support for {@code @Configuration} classes
 *
 * The Spring TestContext framework available in the {@code spring-test} module
 * provides the {@code @ContextConfiguration} annotation which can accept an array of
 * component class references — typically {@code @Configuration} or
 * {@code @Component} classes.
 *
 * 
 * @ExtendWith(SpringExtension.class)
 * @ContextConfiguration(classes = {AppConfig.class, DatabaseConfig.class})
 * class MyTests {
 *
 *     @Autowired MyBean myBean;
 *
 *     @Autowired DataSource dataSource;
 *
 *     @Test
 *     void test() {
 *         // assertions against myBean ...
 *     }
 * }
 *
 * See the
 * TestContext framework
 * reference documentation for details.
 *
 * 
Enabling built-in Spring features using {@code @Enable} annotations
 *
 * Spring features such as asynchronous method execution, scheduled task execution,
 * annotation driven transaction management, and even Spring MVC can be enabled and
 * configured from {@code @Configuration} classes using their respective "{@code @Enable}"
 * annotations. See
 * {@link org.springframework.scheduling.annotation.EnableAsync @EnableAsync},
 * {@link org.springframework.scheduling.annotation.EnableScheduling @EnableScheduling},
 * {@link org.springframework.transaction.annotation.EnableTransactionManagement @EnableTransactionManagement},
 * {@link org.springframework.context.annotation.EnableAspectJAutoProxy @EnableAspectJAutoProxy},
 * and {@link org.springframework.web.servlet.config.annotation.EnableWebMvc @EnableWebMvc}
 * for details.
 *
 * 
Constraints when authoring {@code @Configuration} classes
 *
 * 
 * Configuration classes must be provided as classes (i.e. not as instances returned
 * from factory methods), allowing for runtime enhancements through a generated subclass.
 * 
Configuration classes must be non-final (allowing for subclasses at runtime),
 * unless the {@link #proxyBeanMethods() proxyBeanMethods} flag is set to {@code false}
 * in which case no runtime-generated subclass is necessary.
 * 
Configuration classes must be non-local (i.e. may not be declared within a method).
 * 
Any nested configuration classes must be declared as {@code static}.
 * 
{@code @Bean} methods may not in turn create further configuration classes
 * (any such instances will be treated as regular beans, with their configuration
 * annotations remaining undetected).
 * 
 *
 * @author Rod Johnson
 * @author Chris Beams
 * @author Juergen Hoeller
 * @since 3.0
 * @see Bean
 * @see Profile
 * @see Import
 * @see ImportResource
 * @see ComponentScan
 * @see Lazy
 * @see PropertySource
 * @see AnnotationConfigApplicationContext
 * @see ConfigurationClassPostProcessor
 * @see org.springframework.core.env.Environment
 * @see org.springframework.test.context.ContextConfiguration
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Component
public @interface Configuration {

	/**
	 * Explicitly specify the name of the Spring bean definition associated with the
	 * {@code @Configuration} class. If left unspecified (the common case), a bean
	 * name will be automatically generated.
	 * The custom name applies only if the {@code @Configuration} class is picked
	 * up via component scanning or supplied directly to an
	 * {@link AnnotationConfigApplicationContext}. If the {@code @Configuration} class
	 * is registered as a traditional XML bean definition, the name/id of the bean
	 * element will take precedence.
	 * 
Alias for {@link Component#value}.
	 * @return the explicit component name, if any (or empty String otherwise)
	 * @see AnnotationBeanNameGenerator
	 */
	@AliasFor(annotation = Component.class)
	String value() default "";

	/**
	 * Specify whether {@code @Bean} methods should get proxied in order to enforce
	 * bean lifecycle behavior, for example, to return shared singleton bean instances even
	 * in case of direct {@code @Bean} method calls in user code. This feature
	 * requires method interception, implemented through a runtime-generated CGLIB
	 * subclass which comes with limitations such as the configuration class and
	 * its methods not being allowed to declare {@code final}.
	 * 
The default is {@code true}, allowing for 'inter-bean references' via direct
	 * method calls within the configuration class as well as for external calls to
	 * this configuration's {@code @Bean} methods, for example, from another configuration class.
	 * If this is not needed since each of this particular configuration's {@code @Bean}
	 * methods is self-contained and designed as a plain factory method for container use,
	 * switch this flag to {@code false} in order to avoid CGLIB subclass processing.
	 * 
Turning off bean method interception effectively processes {@code @Bean}
	 * methods individually like when declared on non-{@code @Configuration} classes,
	 * a.k.a. "@Bean Lite Mode" (see {@link Bean @Bean's javadoc}). It is therefore
	 * behaviorally equivalent to removing the {@code @Configuration} stereotype.
	 * @since 5.2
	 */
	boolean proxyBeanMethods() default true;

	/**
	 * Specify whether {@code @Bean} methods need to have unique method names,
	 * raising an exception otherwise in order to prevent accidental overloading.
	 * The default is {@code true}, preventing accidental method overloads which
	 * get interpreted as overloaded factory methods for the same bean definition
	 * (as opposed to separate bean definitions with individual conditions etc).
	 * Switch this flag to {@code false} in order to allow for method overloading
	 * according to those semantics, accepting the risk for accidental overlaps.
	 * @since 6.0
	 */
	boolean enforceUniqueMethods() default true;

}