Java tutorial
/* * Copyright 2002-2019 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: * * <pre class="code"> * @Configuration * public class AppConfig { * * @Bean * public MyBean myBean() { * // instantiate, configure and return bean ... * } * }</pre> * * <h2>Bootstrapping {@code @Configuration} classes</h2> * * <h3>Via {@code AnnotationConfigApplicationContext}</h3> * * <p>{@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: * * <pre class="code"> * AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext(); * ctx.register(AppConfig.class); * ctx.refresh(); * MyBean myBean = ctx.getBean(MyBean.class); * // use myBean ... * </pre> * * <p>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. * * <h3>Via Spring {@code <beans>} XML</h3> * * <p>As an alternative to registering {@code @Configuration} classes directly against an * {@code AnnotationConfigApplicationContext}, {@code @Configuration} classes may be * declared as normal {@code <bean>} definitions within Spring XML files: * * <pre class="code"> * <beans> * <context:annotation-config/> * <bean class="com.acme.AppConfig"/> * </beans> * </pre> * * <p>In the example above, {@code <context:annotation-config/>} is required in order to * enable {@link ConfigurationClassPostProcessor} and other annotation-related * post processors that facilitate handling {@code @Configuration} classes. * * <h3>Via component scanning</h3> * * <p>{@code @Configuration} is meta-annotated with {@link Component @Component}, therefore * {@code @Configuration} classes are candidates for component scanning (typically using * Spring XML's {@code <context:component-scan/>} element) and therefore may also take * advantage of {@link Autowired @Autowired}/{@link javax.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: * * <pre class="code"> * @Configuration * public class AppConfig { * * private final SomeBean someBean; * * public AppConfig(SomeBean someBean) { * this.someBean = someBean; * } * * // @Bean definition using "SomeBean" * * }</pre> * * <p>{@code @Configuration} classes may not only be bootstrapped using * component scanning, but may also themselves <em>configure</em> component scanning using * the {@link ComponentScan @ComponentScan} annotation: * * <pre class="code"> * @Configuration * @ComponentScan("com.acme.app.services") * public class AppConfig { * // various @Bean definitions ... * }</pre> * * <p>See the {@link ComponentScan @ComponentScan} javadocs for details. * * <h2>Working with externalized values</h2> * * <h3>Using the {@code Environment} API</h3> * * <p>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: * * <pre class="code"> * @Configuration * public class AppConfig { * * @Autowired Environment env; * * @Bean * public MyBean myBean() { * MyBean myBean = new MyBean(); * myBean.setName(env.getProperty("bean.name")); * return myBean; * } * }</pre> * * <p>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: * * <pre class="code"> * @Configuration * @PropertySource("classpath:/com/acme/app.properties") * public class AppConfig { * * @Inject Environment env; * * @Bean * public MyBean myBean() { * return new MyBean(env.getProperty("bean.name")); * } * }</pre> * * <p>See the {@link org.springframework.core.env.Environment Environment} * and {@link PropertySource @PropertySource} javadocs for further details. * * <h3>Using the {@code @Value} annotation</h3> * * <p>Externalized values may be injected into {@code @Configuration} classes using * the {@link Value @Value} annotation: * * <pre class="code"> * @Configuration * @PropertySource("classpath:/com/acme/app.properties") * public class AppConfig { * * @Value("${bean.name}") String beanName; * * @Bean * public MyBean myBean() { * return new MyBean(beanName); * } * }</pre> * * <p>This approach is often used in conjunction with Spring's * {@link org.springframework.context.support.PropertySourcesPlaceholderConfigurer * PropertySourcesPlaceholderConfigurer} that can be enabled <em>automatically</em> * in XML configuration via {@code <context:property-placeholder/>} or <em>explicitly</em> * 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 <em>embedded value * resolver</em> for the {@code ApplicationContext}, Spring will register a default * <em>embedded value resolver</em> 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}. * * <h2>Composing {@code @Configuration} classes</h2> * * <h3>With the {@code @Import} annotation</h3> * * <p>{@code @Configuration} classes may be composed using the {@link Import @Import} annotation, * similar to the way that {@code <import>} 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: * * <pre class="code"> * @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()); * } * }</pre> * * <p>Now both {@code AppConfig} and the imported {@code DatabaseConfig} can be bootstrapped * by registering only {@code AppConfig} against the Spring context: * * <pre class="code"> * new AnnotationConfigApplicationContext(AppConfig.class);</pre> * * <h3>With the {@code @Profile} annotation</h3> * * <p>{@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 <em>active</em>: * * <pre class="code"> * @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 * } * }</pre> * * <p>Alternatively, you may also declare profile conditions at the {@code @Bean} method level * — for example, for alternative bean variants within the same configuration class: * * <pre class="code"> * @Configuration * public class ProfileDatabaseConfig { * * @Bean("dataSource") * @Profile("development") * public DataSource embeddedDatabase() { ... } * * @Bean("dataSource") * @Profile("production") * public DataSource productionDatabase() { ... } * }</pre> * * <p>See the {@link Profile @Profile} and {@link org.springframework.core.env.Environment} * javadocs for further details. * * <h3>With Spring XML using the {@code @ImportResource} annotation</h3> * * <p>As mentioned above, {@code @Configuration} classes may be declared as regular Spring * {@code <bean>} 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: * * <pre class="code"> * @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); * } * }</pre> * * <h3>With nested {@code @Configuration} classes</h3> * * <p>{@code @Configuration} classes may be nested within one another as follows: * * <pre class="code"> * @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(); * } * } * }</pre> * * <p>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} <em>will be registered automatically</em>. This avoids * the need to use an {@code @Import} annotation when the relationship between * {@code AppConfig} and {@code DatabaseConfig} is already implicitly clear. * * <p>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. * * <h2>Configuring lazy initialization</h2> * * <p>By default, {@code @Bean} methods will be <em>eagerly instantiated</em> 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. * * <h2>Testing support for {@code @Configuration} classes</h2> * * <p>The Spring <em>TestContext framework</em> available in the {@code spring-test} module * provides the {@code @ContextConfiguration} annotation which can accept an array of * {@code @Configuration} {@code Class} objects: * * <pre class="code"> * @RunWith(SpringRunner.class) * @ContextConfiguration(classes = {AppConfig.class, DatabaseConfig.class}) * public class MyTests { * * @Autowired MyBean myBean; * * @Autowired DataSource dataSource; * * @Test * public void test() { * // assertions against myBean ... * } * }</pre> * * <p>See the * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/testing.html#testcontext-framework">TestContext framework</a> * reference documentation for details. * * <h2>Enabling built-in Spring features using {@code @Enable} annotations</h2> * * <p>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. * * <h2>Constraints when authoring {@code @Configuration} classes</h2> * * <ul> * <li>Configuration classes must be provided as classes (i.e. not as instances returned * from factory methods), allowing for runtime enhancements through a generated subclass. * <li>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. * <li>Configuration classes must be non-local (i.e. may not be declared within a method). * <li>Any nested configuration classes must be declared as {@code static}. * <li>{@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). * </ul> * * @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. * <p>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. * @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, e.g. 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}. * <p>The default is {@code true}, allowing for 'inter-bean references' within * the configuration class as well as for external calls to this configuration's * {@code @Bean} methods, e.g. 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. * <p>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; }