The Spring Framework has forever changed the face of enterprise Java development, making it easier than ever to configure and assemble application objects and services in a loosely-coupled manner. As you develop your Spring-enabled applications, you'll find this reference card to be a handy resource for Spring context configuration. It catalogs the XML elements available as of Spring 2.5, highlighting the most commonly used elements. In addition to Spring XML configuration, there'll also be a guide to Spring's rich set of annotations, which are useful for minimizing the amount of XML needed to configure Spring.

Although the Spring Framework does many things, dependency injection is the foundational functionality provided by the Spring container.

Any non-trivial application is composed of two or more objects that collaborate to perform some business logic. Traditionally, each of those objects is responsible for obtaining references to those objects that it collaborates with (its dependencies). This leads to tightly-coupled and hard-to-test code.

With dependency injection, however, objects are given their dependencies by some external entity. In other words, dependencies are injected into the objects that need them. In the case of a Spring-enabled application, it is the Spring container that injects objects into the objects that depend on them.

As of Spring 2.0, you are encouraged to use Spring's XML Schema-based configuration, which is more flexible than the legacy DTD-based XML. A typical Spring 2.5 configuration will have, at minimum, the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">

<!-- place configuration details here -->

</beans>

Within the <beans> element, you'll place bean declarations and other elements that configure your application's context. The "beans" namespace was the first and is still the primary namespace in Spring's XML configuration, but it isn't alone. Spring also comes with seven more namespaces that will be described in this reference card. If you wish to use one of the other namespaces, you'll need to be sure to declare them. For example, if you want to use the "context" namespace, you should declare it in XML as follows:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context-2.5.xsd">

<!-- place configuration details here -->

</beans>

Schema URI
www.springframework.org/schema/beans

Schema XSD
www.springframework.org/schema/beans/spring-beans-2.5.xsd

The beans namespace is the core Spring namespace and the one you'll use most when configuring Spring. The root element is the <beans> element. It typically contains one or more <bean> elements, but it may include elements from other namespaces and may not even include a <bean> element at all.

Spring XML Diagram Key

The Spring XML diagrams use the following notations to indicate required elements, cardinality, and containment:

Bean Namespace Diagram

Bean Namespace Elements

The <bean> Element Distilled

Even though there are several XML elements that can be used to configure a Spring context, the one you'll probably use the most often is the <bean> element. Therefore, it only seems right that you get to know the attributes of <bean> in detail.

Bean Namespace Example

The following Spring XML configures two beans, one injected into the other:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
<bean id="pirate" class="Pirate">
<constructor-arg value="Long John Silver" />
<property name="map" ref="treasureMap" />
</bean>
<bean id="treasureMap" class="TreasureMap" />
</beans>

The first bean is given "pirate" as its ID and is of type "Pirate." It is to be constructed through a constructor that takes a String as an argument, in this case, it will be constructed with "Long John Silver" as that value. In addition, its "map" property is wired with a reference to the "treasureMap" bean, which is defined as being an instance of TreasureMap.

<import resource="service-layer-config.xml" />
<import resource="data-layer-config.xml" />
<import resource="transaction-config.xml" />

Schema URI
www.springframework.org/schema/context

Schema XSD
www.springframework.org/schema/context/spring-context-2.5.xsd

The context namespace was added in Spring 2.5 to provide several application context-specific configurations. It includes support for annotation-based configuration, JMX, and domain object injection.

Context Namespace Elements

Context Namespace Example

The following Spring configuration uses <context:component-scan> to automatically register certain beans from the "com.springinaction.service" namespace:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context-2.5.xsd">
<context:component-scan base-package="com.springinaction.
service" />
</beans>

As configured above, <context:component-scan> will scan the "com.springinaction.service" package and will automatically register as beans all of the classes it finds that are annotated with @Component, @Controller, @Repository, @Service, or @Aspect.

<context:property-placeholder location="file:////etc/pirate.properties"

<bean id="pirate" class="Pirate">
<constructor-arg value="${pirate.name}" />
<bean>

Schema URI
www.springframework.org/schema/aop

Schema XSD
www.springframework.org/schema/aop/spring-aop-2.5.xsd

The aop namespace makes it possible to declare aspects, pointcuts, and advice in a Spring context. It also provides support for annotation-based aspects using @AspectJ annotations. Using aspects, you can define functionality that is applied (or "woven") across many points of your application.

AOP Namespace Diagram

AOP Namespace Elements

AOP Namespace Example

The following Spring configuration creates an aspect using elements from the aop namespace:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:aop="http://www.springframework.org/schema/aop"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/aop
http://www.springframework.org/schema/aop/spring-aop-2.5.xsd">
<bean id="pirateTalker" class="PirateTalker" />
<aop:config>
<aop:pointcut id="plunderPointcut"
expression="execution(* *.plunder(..))" />
<aop:aspect ref="pirateTalker">
<aop:before pointcut-ref="plunderPointcut"
method="sayAvastMeHearties" />
<aop:after-returning pointcut-ref="plunderPointcut"
method="sayYarr" />
</aop:aspect>
</aop:config>
</beans>

The aspect is made up of one pointcut and two advice definitions. The pointcut is defined as the execution of the plunder() method on any object. The <aop:before> advice is configured to call the sayAvastMeHearties() method on the "pirateTalker" bean when the plunder() method is executed. Likewise, the sayYarr() method will be invoked upon execution of the plunder() method on any object.

Schema URI
www.springframework.org/schema/jee

Schema XSD
www.springframework.org/schema/jee/spring-jee-2.5.xsd

The JEE namespace provides configuration elements for looking up objects from JNDI as well as wiring references to EJBs into a Spring context.

JEE Namespace Diagram

JEE Namespace Elements

JEE Namespace Example

The following Spring configuration uses a few of the jee namespace"s elements to retrieve objects from outside of Spring and configure them as Spring beans:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jee="http://www.springframework.org/schema/jee"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/jee
http://www.springframework.org/schema/jee/spring-jee-2.5.xsd">
<jee:remote-slsb id="hispaniola"
jndi-name="ejb/PirateShip"
business-interface="com.pirate.PirateShipEjb"
resource-ref="true" />
<jee:jndi-lookup id="parrot"
jndi-name="pirate/Parrot"
resource-ref="false" />
</beans>

The first element, <jee:remote-slsb>, configures a bean named "Hispaniola" which is actually a reference to an EJB 2 remote stateless session bean. The EJB"s home interface is found in JNDI under the name "java:comp/env/ejb/PirateShip". The resource-ref attribute indicates that the value in jndi-name should be prefixed by "java:comp/env/". The EJB implements methods defined in the PirateShipEjb business interface.

The other element, <jee:jndi-lookup>, retrieves a reference to an object from JNDI (it could be an EJB 3 session bean or just a plain Java object). The object is found in JNDI under the name "pirate/Parrot". Because resource-ref is "false", the jndi-name is not prefixed with "java:comp/env/".

Schema URI
www.springframework.org/schema/jms

Schema XSD
www.springframework.org/schema/jms/spring-jms-2.5.xsd

The JMS namespace provides elements for configuring message-driven POJOs, beans that respond to messages that arrive on a JMS destination (either a topic or a queue).

JMS Namespace Diagram

JMS Namespace Elements

JMS Namespace Example

The following Spring configuration sets up a message-driven POJO that responds to messages that arrive on a queue.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jms="http://www.springframework.org/schema/jms"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/jms
http://www.springframework.org/schema/jms/spring-jms-2.5.xsd">
...
<bean id="connectionFactory"
class="org.apache.activemq.ActiveMQConnectionFactory">
<property name="brokerURL" value="tcp://localhost:61616" />
</bean>
<bean id="messageHandlerService" class="com.pirate.MessageHandlerImpl"
/>
<jms:listener-container connection-factory="connectionFactory">
<jms:listener
destination="queue.bottle"
ref="messageHandlerService"
method="readMessageFromBottle" />
</jms:listener-container>
</beans>

The <jms:listener-container> configures a container for handling messages arriving on topics or queues coming in on the JMS connection factory. Within this element you may declare one or more <jms:listener> elements to respond to specific topics. In this case, the single <jms:listener> reacts to messages arriving in the "queue.bottle" topic, invoking the readMessageFromBottle() method of the "messageHandlerService" bean when they arrive.

Schema URI
www.springframework.org/schema/lang

Schema XSD
www.springframework.org/schema/lang/spring-lang-2.5.xsd

The "lang" namespace enables you to wire scripted objects into Spring. These objects can be written in either Groovy, JRuby, or BeanShell.

Lang Namespace Diagram

Lang Namespace Elements

Lang Namespace Example

In this Spring context, a Pirate bean is injected with scripted beans defined with <lang:groovy> and <lang:jruby>:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:lang="http://www.springframework.org/schema/lang"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/lang
http://www.springframework.org/schema/lang/spring-lang-2.5.xsd">
<bean id="jackSparrow" class="Pirate">
<constructor-arg value="Jack Sparrow" />
<property name="compass" ref="compass" />
<property name="hat" ref="hat" />
</bean>
<lang:groovy id="compass"
script-source="classpath:Compass.groovy"
refresh-check-delay="10000" />
<lang:jruby id="hat"
script-source="classpath:PirateHat.rb"
script-interface="PirateHat"
refresh-check-delay="60000" />
</beans>

The <lang:groovy> element creates a bean that is implemented as a Groovy script called Compass.groovy and found in the root of the classpath. The refresh-check-delay attribute indicates that the script should be checked every 10 seconds for updates and reloaded if the script changes.

The <lang:jruby> element creates a bean that is implemented as a Ruby (JRuby, specifically) script called PirateHat.rb. It implements a PirateHat interface and is checked for updates once per minute.

Schema URI
www.springframework.org/schema/tx

Schema XSD
www.springframework.org/schema/tx/spring-tx-2.5.xsd

The "tx" namespace provides support for declarative transactions across beans declared in Spring.

TX Namespace Diagram

TX Namespace Elements

TX Namespace Example

The following Spring configuration uses elements in the tx namespace to configure transactional rules and boundaries:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:tx="http://www.springframework.org/schema/tx"
xmlns:aop="http://www.springframework.org/schema/aop"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/aop
http://www.springframework.org/schema/aop/spring-aop-2.5.xsd
http://www.springframework.org/schema/tx
http://www.springframework.org/schema/tx/spring-tx-2.5.xsd">
<tx:jta-transaction-manager />
<tx:advice id="txAdvice">
<tx:attributes>
<tx:method name="plunder*" propagation="REQUIRED" />
<tx:method name="*" propagation="SUPPORTS" />
</tx:attributes>
</tx:advice>
<aop:config>
<aop:advisor
pointcut="execution(* ..Pirate.*(..))"
advice-ref="txAdvice" /<
</aop:config>
</beans>

The <tx:jta-transaction-manager> was added in Spring 2.5 to automatically detect the JTA transaction manager provided by either WebLogic, WebSphere, or OC4J. It exposes the transaction manager as a bean in the Spring context with the name "transactionManager".

Next, the <tx:advice> sets up AOP advice that declares the transactional rules. In this case, any methods with names that start with "plunder" require transactions. All other methods support transactions, but do not require them. Finally, this example borrows from the aop namespace to configure an AOP advisor that uses the transactional advice. The pointcut here is for all methods in the Pirate class.

Schema URI
www.springframework.org/schema/util

Schema XSD
www.springframework.org/schema/util/spring-util-2.5.xsd

The utility namespace provides elements that make it possible to wire collections and other non-bean objects in Spring as if they were any other bean.

Util Namespace Diagram

Util Namespace Elements

Util Namespace Example

The following Spring configuration uses several elements from the "util" namespace:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:util="http://www.springframework.org/schema/util"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/util
http://www.springframework.org/schema/util/spring-util-2.5.xsd">
<util:list id="piratePhrases">
<value>Yo ho ho</value>
<value>Yarr</value>
<value>Avast me hearties!</value>
<value>Blow me down</value>
</util:list>
<util:constant id="pirateCode"
static-field="Pirate.PIRATE_CODE" />
<util:property-path id="doubloonCount"
path="pirate.treasure.doubloonCount" />
</beans>

The <util:list> element is used here to create a list of Strings containing various phrases uttered by pirates. The <util:constant> element creates a reference to the constant (public static field) named PIRATE_CODE of the Pirate class. Finally, the <util:property-path> digs deep into the "pirate" bean, retrieving the value of the doubloonCount property of the treasure property of the bean named "pirate". In all three cases, the resulting values are exposed as beans in the Spring context, suitable for injection into other beans.

Historically, Spring configuration has primarily involved XML. But that is changing as Spring gradually embraces annotation-driven configuration. As of Spring 2.5, there are 36 annotations provided by Spring, not to mention annotations provided by third party libraries and various Spring add-ons.

Context Configuration Annotations

These annotations are used by Spring to guide creation and injection of beans.

Transaction Annotations

The @Transactional annotation is used along with the <tx:annotation-driven> element to declare transactional boundaries and rules as class and method metadata in Java.

Stereotyping Annotations

These annotations are used to stereotype classes with regard to the application tier that they belong to. Classes that are annotated with one of these annotations will automatically be registered in the Spring application context if <context: component-scan> is in the Spring XML configuration.

In addition, if a PersistenceExceptionTranslationPostProcessor is configured in Spring, any bean annotated with @Repository will have SQLExceptions thrown from its methods translated into one of Spring"s unchecked DataAccessExceptions.

Spring MVC Annotations

These annotations were introduced in Spring 2.5 to make it easier to create Spring MVC applications with minimal XML configuration and without extending one of the many implementations of the Controller interface.

JMX Annotations

These annotations, used with the <context:mbean-export> element, declare bean methods and properties as MBean operations and attributes.

Testing Annotations

These annotations are useful for creating unit tests in the JUnit 4 style that depend on Spring beans and/or require a transactional context.