Spring JavaConfig Reference Guide

For the purposes of this document, a general familiarity with the core concepts of the Spring IoC container are assumed. It is beyond the scope of this document to discuss such matters at length. If the following concepts are not familiar, it is recommended that you first read Chapter 3. IoC from the core Spring Framework documentation (or that you reference its relevant sections on an as-needed basis while reading this document): inversion of control (IoC) and/or dependency injection (DI), spring-managed beans, bean scoping, autowiring, BeanFactory, ApplicationContext, BeanFactoryPostProcessor , BeanPostProcessor, Spring's initialization, destruction, and other bean lifecycle callback mechanisms.

If general aspect oriented programming (AOP) concepts are unfamiliar, or AOP with Spring and AspectJ 5's @Aspect style are unfamiliar, it is recommended that you first read Chapter 6. AOP from the Core Spring Framework documentation.

ant jar publish-maven-local
            

Milestone builds are available from Spring's milestone build area.

To access milestone builds using Maven, add the following repositories to your Maven pom:

<repository>
    <id>com.springsource.repository.bundles.milestone</id>
    <name>SpringSource Enterprise Bundle Repository - SpringSource Milestone Releases</name>
    <url>http://repository.springsource.com/maven/bundles/milestone</url>
</repository>

<repository>
    <id>com.springsource.repository.bundles.external</id>
    <name>SpringSource Enterprise Bundle Repository - External Releases</name>
    <url>http://repository.springsource.com/maven/bundles/external</url>
</repository>
                

Then add the following dependency:

<dependency>
    <groupId>org.springframework.javaconfig</groupId>
    <artifactId>org.springframework.config.java</artifactId>
    <version>1.0.0.M4</version>
</dependency>
                

To access milestone builds using Ivy, add the following repositories to your Ivy config:

<url name="com.springsource.repository.bundles.milestone">
    <ivy pattern="http://repository.springsource.com/ivy/bundles/milestone/
                  [organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
    <artifact pattern="http://repository.springsource.com/ivy/bundles/milestone/
                       [organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
</url>

<url name="com.springsource.repository.bundles.external">
    <ivy pattern="http://repository.springsource.com/ivy/bundles/external/
                  [organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
    <artifact pattern="http://repository.springsource.com/ivy/bundles/external/
                       [organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
</url>
                

Then declare the following dependency:

<dependency org="org.springframework.javaconfig" name="org.springframework.config.java"
            rev="1.0.0.M4" conf="compile->runtime"/>
                

Nightly builds are available from Spring's snapshot build area.

To access nightly builds using Maven, add the following repositories to your Maven pom:

<repository>
    <id>com.springsource.repository.bundles.snapshot</id>
    <name>SpringSource Enterprise Bundle Repository - SpringSource Snapshot Builds</name>
    <url>http://repository.springsource.com/maven/bundles/snapshot</url>
</repository>

<repository>
    <id>com.springsource.repository.bundles.external</id>
    <name>SpringSource Enterprise Bundle Repository - External Releases</name>
    <url>http://repository.springsource.com/maven/bundles/external</url>
</repository>
                

Then add the following dependency:

<dependency>
    <groupId>org.springframework.javaconfig</groupId>
    <artifactId>org.springframework.config.java</artifactId>
    <version>1.0.0.BUILD-SNAPSHOT</version>
</dependency>
                

To access nightly builds using Ivy, add the following repositories to your Ivy config:

<url name="com.springsource.repository.bundles.snapshot">
    <ivy pattern="http://repository.springsource.com/ivy/bundles/snapshot/
                  [organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
    <artifact pattern="http://repository.springsource.com/ivy/bundles/snapshot/
                       [organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
</url>

<url name="com.springsource.repository.bundles.external">
    <ivy pattern="http://repository.springsource.com/ivy/bundles/external/
                  [organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
    <artifact pattern="http://repository.springsource.com/ivy/bundles/external/
                       [organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/>
</url>
                

Then declare the following dependency:

<dependency org="org.springframework.javaconfig" name="org.springframework.config.java"
            rev="1.0.0.BUILD-SNAPSHOT" conf="compile->runtime"/>
                

To declare a bean, simply annotate a method with the @Bean annotation. When JavaConfig encounters such a method, it will execute that method and register the return value as a bean within a BeanFactory. By default, the bean name will be the same as the method name (see bean naming for details on how to customize this behavior). The following is a simple example of a @Bean method declaration:

@Configuration
public class AppConfig {
    @Bean
    public TransferService transferService() {
        return new TransferServiceImpl();
    }
}
                

For comparison sake, the configuration above is exactly equivalent to the following Spring XML:

<beans>
    <bean name="transferService" class="com.acme.TransferServiceImpl"/>
</beans>
                

Both will result in a bean named transferService being available in the BeanFactory / ApplicationContext, bound to an object instance of type TransferServiceImpl:

transferService -> com.acme.TransferServiceImpl
                

When @Beans have dependencies on one another, expressing that dependency is as simple as having one bean method call another:

@Configuration
public class AppConfig {
    @Bean
    public Foo foo() {
        return new Foo(bar());
    }

    @Bean
    public Bar bar() {
        return new Bar();
    }
}
                

In the example above, the foo bean recevies a reference to bar via constructor injection.

The standard set of *Aware interfaces such as BeanFactoryAware, BeanNameAware, MessageSourceAware, ApplicationContextAware, etc. are fully supported. Consider an example class that implements BeanFactoryAware:

public class AwareBean implements BeanFactoryAware {

    private BeanFactory factory;

    // BeanFactoryAware setter (called by Spring during bean instantiation)
    public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
        this.factory = beanFactory;
    }

    public void close(){
        // do clean-up
    }
}
                

If the class above were declared as a bean as follows:

@Configuration
public class AppConfig {
    @Bean
    public AwareBean awareBean() {
        return new AwareBean();
    }
}
                

its setBeanFactory method will be called during initialization, providing the bean with access to its enclosing BeanFactory.

By default, JavaConfig uses a @Bean method's name as the name of the resulting bean. This functionality can be overridden, however, using the BeanNamingStrategy extension point.

public class Main {
    public static void main(String[] args) {
        JavaConfigApplicationContext ctx = new JavaConfigApplicationContext();
        ctx.setBeanNamingStrategy(new CustomBeanNamingStrategy());
        ctx.addConfigClass(MyConfig.class);
        ctx.refresh();
        ctx.getBean("customBeanName");
    }
}
                

	Note
	JavaConfigApplicationContext will be covered in detail in Chapter 3, Using @Configuration classes For more details, see the API documentation for BeanNamingStrategy.

Spring provides many implementations of the FactoryBean interface. Usually these classes are used to support integrations with other frameworks. Take for example org.springframework.orm.hibernate3.LocalSessionFactoryBean. This class is used to create a Hibernate SessionFactory and requires as dependencies the location of Hibernate mapping files and a DataSource. Here's how it is commonly used in XML:

<beans>
    <bean id="sessionFactory"
          class="org.springframework.orm.hibernate3.LocalSessionFactoryBean">
        <property name="dataSource" ref="dataSource"/>
        <property name="mappingResources">
             <list>
                 <value>com/acme/Bank.hbm.xml</value>
                 <value>com/acme/Account.hbm.xml</value>
                 <value>com/acme/Customer.hbm.xml</value>
             </list>
        </property>
    </bean>

    <bean id="dataSource" class="...">
        <!-- ... -->
    </bean>
</beans>
                

The Spring container recognizes that LocalSessionFactoryBean implements the FactoryBean interface, and thus treats this bean specially: An instance of LocalSessionFactoryBean is instantiated, but instead of being directly returned, instead the getObject() method is invoked. It is the object returned from this call getObject() that is ultimately registered as the sessionFactory bean.

How then would we use LocalSessionFactoryBean in JavaConfig? The best approach is to extend the ConfigurationSupport base class and use the getObject() method:

@Configuration
public class DataAccessConfig extends ConfigurationSupport {
    @Bean
    public SessionFactory sessionFactory() {
        LocalSessionFactoryBean factoryBean = new LocalSessionFactoryBean();
        factoryBean.setDataSource(dataSource());
        ArrayList<String> mappingFiles = new ArrayList<String>();
        mappingFiles.add("com/acme/Bank.hbm.xml");
        mappingFiles.add("com/acme/Account.hbm.xml");
        mappingFiles.add("com/acme/Customer.hbm.xml");
        factoryBean.setMappingResources(mappingFiles);
        return this.getObject(SessionFactory.class, factoryBean);
    }
    // ... other beans, including dataSource() ...
}

                

Notice the call to this.getObject(Class, FactoryBean)? This call ensures that any container callbacks are invoked on the FactoryBean object, and then returns the value from the FactoryBean's getObject() in a type-safe fashion.

Instantiating the JavaConfigApplicationContext can be done by supplying @Configuration class literals to the constructor, and/or strings representing packages to scan for @Configuration classes.

JavaConfigApplicationContext context = new JavaConfigApplicationContext(AppConfig.class);
Service service = context.getBean(Service.class);
                    

JavaConfigApplicationContext context =
    new JavaConfigApplicationContext(AppConfig.class, DataConfig.class);
Service service = context.getBean(Service.class);
                    

3.1.1.2. Construction by base package

Base packages will be scanned for the existence of any @Configuration classes. Any candidate classes will then be processed much as if they had been supplied directly as class literals to the constructor.

JavaConfigApplicationContext context =
    new JavaConfigApplicationContext("com.acme.app.configuration");
Service service = context.getBean(Service.class);
                    

Passing multiple base packages:

JavaConfigApplicationContext context =
    new JavaConfigApplicationContext("com.acme.configuration", "com.acme.other");
Service service = context.getBean(Service.class);
                    

Matching packages and classes by wildcard:

JavaConfigApplicationContext context =
    new JavaConfigApplicationContext("**/configuration/**/*.class", "**/other/*Config.class");
Service service = context.getBean(Service.class);
                    

	Note
	The wildcard syntax for matching packages and classes above is based on Ant Patterns

JavaConfigApplicationContext context = new JavaConfigApplicationContext();
context.setParent(otherConfig);
context.setConfigClasses(AppConfig.class, DataConfig.class);
context.setBasePackages("com.acme.configuration");
context.refresh();
Service service = (Service) context.getBean("serviceA");
                    

	Note
	Whenever multiple packages and/or classes are used to instantiate a JavaConfigApplicationContext, order matters. This is important when considering what happens if two configuration classes define a bean with the same name. The last-specified class wins.

JavaConfigApplicationContext provides several variants of the getBean() method for accessing beans.

JavaConfigApplicationContext context = new JavaConfigApplicationContext(...);
Service service = context.getBean(Service.class);
                    

@Configuration
public class MyConfig {
    @Bean(primary=Primary.TRUE)
    public Service myService() {
        return new Service();
    }

    @Bean
    public Service backupService() {
        return new Service();
    }
}
                            

JavaConfigApplicationContext context = new JavaConfigApplicationContext(...);
Service service = context.getBean(Service.class); // returns the myService() primary bean
                            

JavaConfigApplicationContext context = new JavaConfigApplicationContext(...);
Service service = context.getBean(Service.class, "myService");
                            

JavaConfigApplicationContext context = new JavaConfigApplicationContext(...);
Map matchingBeans = context.getBeansOfType(Service.class);
                            

JavaConfigApplicationContext context = new JavaConfigApplicationContext(...);
Service service = (Service) context.getBean("myService");
                    

One @Configuration class may directly reference bean instances registered from another using Spring's @Autowired annotation.

@Configuration
public class ConfigOne {
    @Bean
    public AccountRepository accountRepository() {
        // create and return an AccountRepository object
    }
}

@Configuration
@AnnotationDrivenConfig
public class ConfigTwo {
    @Autowired AccountRepository accountRepository;

    @Bean
    public TransferService transferService() {
        return new TransferServiceImpl(accountRepository);
    }
}
                

Given that both these configuration classes are supplied to the application context at runtime, the AccountRepository bean declared in ConfigOne will be autowired (injected) into the AccountRepository field in ConfigTwo.

JavaConfigApplicationContext context =
    new JavaConfigApplicationContext(ConfigOne.class, ConfigTwo.class);
                

In addition to being able to reference any particular bean definition as seen above, one @Configuration class may reference the instance of any other @Configuration class using @Autowired. This works because the @Configuration classes themselves are instantiated and managed as individual Spring beans.

@Configuration
public class ConfigOne {
    @Bean
    public AccountRepository accountRepository() {
        // create and return an AccountRepository object
    }
}

@Configuration
@AnnotationDrivenConfig
public class ConfigTwo {
    @Autowired ConfigOne configOne;

    @Bean
    public TransferService transferService() {
         // transferService references accountRepository in a 'fully-qualified' fashion:
        return new TransferServiceImpl(configOne.accountRepository());
    }
}
                

	Tip
	The 'fully-qualified' approach is generally preferred as it provides a the significant advantage of being able to easily navigate within an IDE to the source of the referenced bean.

@Configuration
@PropertiesValueSource("classpath:com/acme/db.properties")
public class AppConfig {
    @ExternalValue("datasource.username") String username;

    @Bean
    public TestBean testBean() {
        return new TestBean(username);
    }
}
            

com/acme/db.properties will be read from the classpath and the value associated with key datasource.username will be injected into the username field. The contents of db.properties might be as follows:

datasource.username=scott
datasource.password=tiger
...
                

	Note
	An array of properties file locations may be supplied to @PropertiesValueSource, and along with classpath:, all of the standard Spring resource-loading prefixes are supported, such as file: and http:. @Configuration @PropertiesValueSource({"classpath:com/acme/a.properties", "file:/opt/acme/b.properties"}) public class AppConfig { // ... }

@ExternalValue may also be used as a method-level annotation

@Configuration
@PropertiesValueSource("classpath:com/acme/db.properties")
public abstract class AppConfig {
    @ExternalValue("datasource.username")
    abstract String username();

    @Bean
    public TestBean testBean() {
        return new TestBean(username());
    }
}
                

The primary advantage to using @ExternalValue methods is that rather than injecting the external value just once (as is done in the case of @ExternalValue fields), @ExternalValue methods are evaluated every time they're referenced. As this is not usually required, @ExternalValue fields are the preferred method. A downside of @ExternalValue methods is that they should be abstract, requiring you to declare the entire @Configuration class abstract, and this is not in alignment with the semantics users typically associate with using the abstract keyword.

You may desire or be required to use XML as the primary mechanism for configuring the container, but wish to selectively use @Configuration classes to define certain beans. For such cases, JavaConfig provides ConfigurationPostProcessor, a Spring BeanPostProcessor capable of processing @Configuration classes.

<beans>
    <!-- first, define your individual @Configuration classes as beans -->
    <bean class="com.myapp.config.AppConfig"/>
    <bean class="com.myapp.config.DataConfig"/>

    <!-- be sure to include the JavaConfig bean post-processor -->
    <bean class="org.springframework.config.java.process.ConfigurationPostProcessor"/>
</beans>
                

Then, bootstrap an XML ApplicationContext:

ApplicationContext context = new ClassPathXmlApplicationContext("application-config.xml");
                

The beans defined in AppConfig and DataConfig will be available via context.

<beans>
    <!-- a possible "configurable configuration" -->
    <bean class="org.my.company.config.AppConfiguration">
        <property name="env" value="TESTING"/>
        <property name="monitoring" value="true"/>
        <property name="certificates" value="classpath:/META-INF/config/MyCompany.certs"/>
    </bean>
    <!-- JavaConfig post-processor -->
    <bean class="org.springframework.config.java.process.ConfigurationPostProcessor"/>
</beans>
                    

The @ImportXml annotation is provided to support importing beans defined in XML into @Configuration classes.

<beans>
    <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource">
        <property name="url" value="jdbc:hsqldb:hsql://localhost:9001"/>
        <property name="driverClassName" value="org.hsqldb.jdbcDriver"/>
        <property name="username" value="sa"/>
        <property name="password" value=""/>
    </bean>
</beans>

            

@Configuration
@AnnotationDrivenConfig // enable the @Autowired annotation
@ImportXml("classpath:com/company/app/datasource-config.xml")
public class Config {
    // autowire the DataSource bean declared in datasource-config.xml
    @Autowired DataSource dataSource;

    @Bean
    public FooRepository fooRepository() {
        // inject the autowired-from-XML dataSource
        return new JdbcFooRepository(dataSource);
    }

    @Bean
    public FooService fooService() {
        return new FooServiceImpl(fooRepository());
    }
}
            

Spring 2.5 introduced a new style of dependency injection with Annotation-Driven Injection. In Spring XML, Annotation-Driven Injection is enabled in the container by declaring

<context:annotation-config/>
                

In JavaConfig, this same functionality is enabled with the @AnnotationDrivenConfig annotation

@Configuration
@AnnotationDrivenConfig
public class Config {
    // may now use @Autowired to reference beans from other @Configuration classes, XML, etc
}
                

An equivalent for Spring XML's <context:component-scan/> is provided with the @ComponentScan annotation.

package com.company.foo;

@Service
public class FooServiceImpl implements FooService {
    private final FooRepository fooRepository;

    @Autowired
    public FooService(FooRepository fooRepository) {
        this.fooRepository = fooRepository;
    }

    // ...
}
                

package com.company.foo;

@Repository
public class JdbcFooRepository implements FooRepository {
    private final DataSource dataSource;

    @Autowired
    public FooRepository(DataSource dataSource) {
        this.dataSource = dataSource;
    }

    // ...
}
                

@Configuration
@ComponentScan("com.company") // search the com.company package for @Component classes
@ImportXml("classpath:com/company/data-access-config.xml") // XML with DataSource bean
public class Config {
}
                

Because Spring's @Service and @Repository stereotype annotations are each meta-annotated with @Component, they are candidates for component scanning. Because FooServiceImpl and JdbcFooRepository both reside underneath the com.company package, they will be discovered during component scanning and will be autowired together. @ImportXml pulls in the DataSource bean, ensuring it will be available for autowiring into JdbcFooRepository.

With the above very minimal configuration in the Config class, we can bootstrap and use the application as follows:

public class Main {
    public static void main(String[] args) {
        JavaConfigApplicationContext ctx = new JavaConfigApplicationContext(Config.class);
        FooService fooService = ctx.getBean(FooService.class);
        fooService.doStuff();
    }
}
                

Please see "Chapter 3, IoC" of the core spring documentation for additional detail on Annotation-Driven Injection support.

As a convenience, @Configuration classes may themselves be annotated with @Aspect, allowing for inline advice methods. Modifying the example above, the Config class could be rewritten as follows, and PropertyChangeTracker could be eliminated entirely:

@Aspect
@Configuration
@AspectJAutoProxy
public class Config {
    private Logger logger = Logger.getLogger(Config.class);

    // declare the advice method locally, eliminating the need for PropertyChangeTracker
    @Before("execution(void set*(*))")
    public void trackChange() {
        logger.info("property about to change");
    }

    @Bean
    public Cache cache() {
        return new SimpleCache();
    }
}