org.springframework.context.annotation.Configuration Maven / Gradle / Ivy
/*
* Copyright 2002-2016 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
*
* http://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.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 {@link AnnotationConfigApplicationContext} Javadoc for further details and see
* {@link org.springframework.web.context.support.AnnotationConfigWebApplicationContext
* AnnotationConfigWebApplicationContext} for {@code web.xml} configuration instructions.
*
* 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:
*
* {@code
*
* }
*
* In the example above, {@code Via component scanning
*
* {@code @Configuration} is meta-annotated with {@link Component @Component}, therefore
* {@code @Configuration} classes are candidates for component scanning (typically using
* Spring XML's {@code
{@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} javadoc 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 using the {@code @Autowired} or the {@code @Inject} annotation:
*
*
* @Configuration
* public class AppConfig {
*
* @Inject 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 org.springframework.core.env.PropertySources @PropertySources} 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 {@link org.springframework.core.env.Environment Environment}
* and {@link PropertySource @PropertySource} Javadoc for further details.
*
* Using the {@code @Value} annotation
*
* Externalized values may be 'wired 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 most useful when using Spring's
* {@link org.springframework.context.support.PropertySourcesPlaceholderConfigurer
* PropertySourcesPlaceholderConfigurer}, usually enabled via XML with
* {@code Composing {@code @Configuration} classes
*
* With the {@code @Import} annotation
*
* {@code @Configuration} classes may be composed using the {@link Import @Import} annotation,
* not unlike 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 using {@code @Autowired} or {@code @Inject}:
*
*
* @Configuration
* public class DatabaseConfig {
*
* @Bean
* public DataSource dataSource() {
* // instantiate, configure and return DataSource
* }
* }
*
* @Configuration
* @Import(DatabaseConfig.class)
* public class AppConfig {
*
* @Inject DatabaseConfig 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("embedded")
* @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
* }
* }
*
* 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 using {@code @Autowired} or {@code @Inject}:
*
*
* @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} {@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 as of Spring 3.1 can
* accept an array of {@code @Configuration} {@code Class} objects:
*
*
* @RunWith(SpringJUnit4ClassRunner.class)
* @ContextConfiguration(classes={AppConfig.class, DatabaseConfig.class})
* public class MyTests {
*
* @Autowired MyBean myBean;
*
* @Autowired DataSource dataSource;
*
* @Test
* public void test() {
* // assertions against myBean ...
* }
* }
*
* See 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 non-final
*
- @Configuration classes must be non-local (may not be declared within a method)
*
- @Configuration classes must have a default/no-arg constructor and may not use
* {@link Autowired @Autowired} constructor parameters. Any nested configuration classes
* must be {@code static}.
*
*
* @author Rod Johnson
* @author Chris Beams
* @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 this Configuration class. If left unspecified (the common case),
* a bean name will be automatically generated.
* The custom name applies only if the Configuration class is picked up via
* component scanning or supplied directly to a {@link AnnotationConfigApplicationContext}.
* If the Configuration class is registered as a traditional XML bean definition,
* the name/id of the bean element will take precedence.
* @return the specified bean name, if any
* @see org.springframework.beans.factory.support.DefaultBeanNameGenerator
*/
String value() default "";
}