<?xml version="1.0" encoding="UTF-8"?>
<appendix xml:id="xsd-config"
    xmlns="http://docbook.org/ns/docbook" version="5.0"
    xmlns:xl="http://www.w3.org/1999/xlink"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
        http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
        http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd">
    <title>XML Schema-based configuration</title>
    <section xml:id="xsd-config-introduction">
        <title>Introduction</title>
        <para>This appendix details the XML Schema-based configuration introduced in Spring 2.0 and enhanced and extended in Spring 2.5 and 3.0.</para>
        <sidebar>
            <title>DTD support?</title>
            <para>Authoring Spring configuration files using the older DTD style
            is still fully supported.</para>
            <para>Nothing will break if you forego the use of the new XML Schema-based
            approach to authoring Spring XML configuration files. All that you lose
            out on is the opportunity to have more succinct and clearer configuration.
            Regardless of whether the XML configuration is DTD- or Schema-based, in the end
            it all boils down to the same object model in the container (namely one or
            more <interfacename>BeanDefinition</interfacename> instances).</para>
        </sidebar>
        <para>The central motivation for moving to XML Schema based configuration files was
        to make Spring XML configuration easier. The <emphasis>'classic'</emphasis>
        <literal>&lt;bean/&gt;</literal>-based approach is good, but its generic-nature comes
        with a price in terms of configuration overhead.</para>
        <para>From the Spring IoC containers point-of-view, <emphasis>everything</emphasis>
        is a bean. That's great news for the Spring IoC container, because if everything is
        a bean then everything can be treated in the exact same fashion. The same, however,
        is not true from a developer's point-of-view. The objects defined in a Spring
        XML configuration file are not all generic, vanilla beans. Usually, each bean requires
        some degree of specific configuration.</para>
        <para>Spring 2.0's new XML Schema-based configuration addresses this issue.
        The <literal>&lt;bean/&gt;</literal> element is still present, and if you
        wanted to, you could continue to write the <emphasis>exact same</emphasis>
        style of Spring XML configuration using only <literal>&lt;bean/&gt;</literal>
        elements. The new XML Schema-based configuration does, however, make
        Spring XML configuration files substantially clearer to read. In addition, it allows
        you to express the intent of a bean definition.</para>
        <para>The key thing to remember is that the new custom tags work best for infrastructure
        or integration beans: for example, AOP, collections, transactions, integration with
        3rd-party frameworks such as Mule, etc., while the existing bean tags are best suited to
        application-specific beans, such as DAOs, service layer objects, validators, etc.</para>
        <para>The examples included below will hopefully convince you that the inclusion
        of XML Schema support in Spring 2.0 was a good idea. The reception in the community
        has been encouraging; also, please note the fact that this new configuration mechanism
        is totally customisable and extensible. This means you can write your own domain-specific
        configuration tags that would better represent your application's domain; the process
        involved in doing so is covered in the appendix entitled <xref linkend="extensible-xml"/>.</para>
    </section>
    <section xml:id="xsd-config-body">
        <title>XML Schema-based configuration</title>
        <section xml:id="xsd-config-body-referencing">
            <title>Referencing the schemas</title>
            <para>To switch over from the DTD-style to the new XML Schema-style, you need
            to make the following change.</para>
            <programlisting language="xml">
<![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN 2.0//EN"
    "http://www.springframework.org/dtd/spring-beans-2.0.dtd">

<beans>

]]><lineannotation>&lt;!-- bean definitions here --&gt;</lineannotation><![CDATA[

</beans>]]></programlisting>
            <para>The equivalent file in the XML Schema-style would be...</para>
            <programlisting language="xml">
<![CDATA[<?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.xsd">

]]><lineannotation>&lt;!-- bean definitions here --&gt;</lineannotation><![CDATA[

</beans>]]></programlisting>
            <note>
                <para>The <literal>'xsi:schemaLocation'</literal> fragment is not actually required,
                but can be included to reference a local copy of a schema (which can be useful
                during development).</para>
            </note>
            <para>The above Spring XML configuration fragment is boilerplate that you can copy and paste
            (!) and then plug <literal>&lt;bean/&gt;</literal> definitions into like you have always
            done. However, the entire point of switching over is to
            take advantage of the new Spring 2.0 XML tags since they make configuration easier. The
            section entitled <xref linkend="xsd-config-body-schemas-util"/> demonstrates how you can
            start immediately by using some of the more common utility tags.</para>
            <para>The rest of this chapter is devoted to showing examples of the new Spring XML Schema
            based configuration, with at least one example for every new tag. The format follows
            a before and after style, with a <emphasis>before</emphasis> snippet of XML showing
            the old (but still 100% legal and supported) style, followed immediately
            by an <emphasis>after</emphasis> example showing the equivalent in the new XML Schema-based
            style.</para>
        </section>
        <section xml:id="xsd-config-body-schemas-util">
            <title>The <literal>util</literal> schema</title>
            <para>First up is coverage of the <literal>util</literal> tags. As the name
            implies, the <literal>util</literal> tags deal with common, <emphasis>utility</emphasis>
            configuration issues, such as configuring collections, referencing constants,
            and suchlike.</para>
            <para>To use the tags in the <literal>util</literal> schema, you need to have
            the following preamble at the top of your Spring XML configuration file;
            the text in the snippet below references the correct schema so that
            the tags in the <literal>util</literal> namespace are available to you.</para>
            <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       ]]><emphasis role="bold">xmlns:util="http://www.springframework.org/schema/util"</emphasis><![CDATA[
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
]]><emphasis role="bold">http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd"</emphasis><![CDATA[>

]]><lineannotation>&lt;!-- bean definitions here --&gt;</lineannotation><![CDATA[

</beans>]]></programlisting>
            <section xml:id="xsd-config-body-schemas-util-constant">
                <title><literal>&lt;util:constant/&gt;</literal></title>
                <para>Before...</para>
                <programlisting language="xml"><![CDATA[<bean id="..." class="...">
  <property name="isolation">
    <bean id="java.sql.Connection.TRANSACTION_SERIALIZABLE"
    class="org.springframework.beans.factory.config.FieldRetrievingFactoryBean" />
  </property>
</bean>]]></programlisting>
                <para>The above configuration uses a Spring <interfacename>FactoryBean</interfacename>
                implementation, the <classname>FieldRetrievingFactoryBean</classname>, to
                set the value of the <literal>'isolation'</literal> property on a bean
                to the value of the <literal>'java.sql.Connection.TRANSACTION_SERIALIZABLE'</literal>
                constant. This is all well and good, but it is a tad verbose and (unnecessarily)
                exposes Spring's internal plumbing to the end user.
                </para>
                <para>The following XML Schema-based version is more concise
                and clearly expresses the developer's intent (<emphasis>'inject this constant
                value'</emphasis>), and it just reads better.
                </para>
                <programlisting language="xml"><![CDATA[<bean id="..." class="...">
  <property name="isolation">
    <util:constant static-field="java.sql.Connection.TRANSACTION_SERIALIZABLE"/>
  </property>
</bean>]]></programlisting>
                <section xml:id="xsd-config-body-schemas-util-frfb">
                    <title>Setting a bean property or constructor arg from a field value</title>
                    <para>
                        <link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/beans/factory/config/FieldRetrievingFactoryBean.html"><classname>FieldRetrievingFactoryBean</classname></link>
                        is a <interfacename>FactoryBean</interfacename> which retrieves a
                        <literal>static</literal> or non-static field value. It is typically
                        used for retrieving <literal>public</literal> <literal>static</literal>
                        <literal>final</literal> constants, which may then be used to set a
                        property value or constructor arg for another bean.
                    </para>
                    <para>
                        Find below an example which shows how a <literal>static</literal> field is exposed, by
                        using the <link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/beans/factory/config/FieldRetrievingFactoryBean.html#setStaticField(java.lang.String)"><literal>staticField</literal></link>
                        property:
                    </para>
                    <programlisting language="xml"><![CDATA[<bean id="myField"
        class="org.springframework.beans.factory.config.FieldRetrievingFactoryBean">
  <property name="staticField" value="java.sql.Connection.TRANSACTION_SERIALIZABLE"/>
</bean>]]></programlisting>
                    <para>There is also a convenience usage form where the <literal>static</literal>
                    field is specified as the bean name:</para>
                    <programlisting language="xml"><![CDATA[<bean id="java.sql.Connection.TRANSACTION_SERIALIZABLE"
    class="org.springframework.beans.factory.config.FieldRetrievingFactoryBean"/>]]></programlisting>
                    <para>
                        This does mean that there is no longer any choice in what the bean id is (so
                        any other bean that refers to it will also have to use this longer name),
                        but this form is very concise to define, and very convenient to use as an
                        inner bean since the id doesn't have to be specified for the bean
                        reference:
                    </para>
                    <programlisting language="xml"><![CDATA[<bean id="..." class="...">
  <property name="isolation">
    <bean id="java.sql.Connection.TRANSACTION_SERIALIZABLE"
          class="org.springframework.beans.factory.config.FieldRetrievingFactoryBean" />
  </property>
</bean>]]></programlisting>
                    <para>
                        It is also possible to access a non-static (instance) field of another bean,
                        as described in the API documentation for the
                        <link xl:href="http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/beans/factory/config/FieldRetrievingFactoryBean.html"><classname>FieldRetrievingFactoryBean</classname></link>
                        class.
                    </para>
                    <para>
                        Injecting enum values into beans as either property or constructor arguments is very
                        easy to do in Spring, in that you don't actually have to <emphasis>do</emphasis>
                        anything or know anything about the Spring internals (or even about classes such
                        as the <classname>FieldRetrievingFactoryBean</classname>). Let's look at an example
                        to see how easy injecting an enum value is; consider this JDK 5 enum:
                    </para>
                    <programlisting language="java"><![CDATA[package javax.persistence;

public enum PersistenceContextType {

    TRANSACTION,
    EXTENDED

}]]></programlisting>
                    <para>Now consider a setter of type <classname>PersistenceContextType</classname>:</para>
                    <programlisting language="java"><![CDATA[package example;

public class Client {

    private PersistenceContextType persistenceContextType;

    public void setPersistenceContextType(PersistenceContextType type) {
        this.persistenceContextType = type;
    }
}]]></programlisting>
                    <para>.. and the corresponding bean definition:</para>
                    <programlisting language="xml"><![CDATA[<bean class="example.Client">
    <property name="persistenceContextType" value="TRANSACTION" />
</bean>]]></programlisting>
                    <para>
                        This works for classic type-safe emulated enums (on JDK 1.4 and JDK 1.3) as well;
                        Spring will automatically attempt to match the string property value to a constant
                        on the enum class.
                    </para>
                </section>
            </section>
            <section xml:id="xsd-config-body-schemas-util-property-path">
                <title><literal>&lt;util:property-path/&gt;</literal></title>
                <para>Before...</para>
                <programlisting language="xml"><lineannotation>&lt;!-- target bean to be referenced by name --&gt;</lineannotation><![CDATA[
<bean id="testBean" class="org.springframework.beans.TestBean" scope="prototype">
  <property name="age" value="10"/>
  <property name="spouse">
    <bean class="org.springframework.beans.TestBean">
      <property name="age" value="11"/>
    </bean>
  </property>
</bean>

]]><lineannotation>&lt;!-- will result in 10, which is the value of property 'age' of bean 'testBean' --&gt;</lineannotation><![CDATA[
<bean id="testBean.age" class="org.springframework.beans.factory.config.PropertyPathFactoryBean"/>]]></programlisting>
                <para>The above configuration uses a Spring <interfacename>FactoryBean</interfacename>
                implementation, the <classname>PropertyPathFactoryBean</classname>, to
                create a bean (of type <classname>int</classname>) called
                <literal>'testBean.age'</literal> that has a value equal to the <literal>'age'</literal>
                property of the <literal>'testBean'</literal> bean.
                </para>
                <para>After...</para>
                <programlisting language="xml"><lineannotation>&lt;!-- target bean to be referenced by name --&gt;</lineannotation><![CDATA[
<bean id="testBean" class="org.springframework.beans.TestBean" scope="prototype">
  <property name="age" value="10"/>
  <property name="spouse">
    <bean class="org.springframework.beans.TestBean">
      <property name="age" value="11"/>
    </bean>
  </property>
</bean>

]]><lineannotation>&lt;!-- will result in 10, which is the value of property 'age' of bean 'testBean' --&gt;</lineannotation><![CDATA[
<util:property-path id="name" path="testBean.age"/>]]></programlisting>
                <para>The value of the <literal>'path'</literal> attribute of the
                <literal>&lt;property-path/&gt;</literal> tag follows the form <literal>'beanName.beanProperty'</literal>.</para>
                <section xml:id="xsd-config-body-schemas-util-property-path-dependency">
                    <title>Using <literal>&lt;util:property-path/&gt;</literal> to set a bean property or constructor-argument</title>
                    <para><classname>PropertyPathFactoryBean</classname> is a
                    <interfacename>FactoryBean</interfacename> that evaluates a property path on a given
                    target object. The target object can be specified directly or via a bean
                    name. This value may then be used in another bean definition as a property
                    value or constructor argument.</para>
                    <para>Here's an example where a path is used against another bean, by name:</para>
                    <programlisting language="xml"><![CDATA[// target bean to be referenced by name
<bean id="person" class="org.springframework.beans.TestBean" scope="prototype">
  <property name="age" value="10"/>
  <property name="spouse">
    <bean class="org.springframework.beans.TestBean">
      <property name="age" value="11"/>
    </bean>
  </property>
</bean>

]]><lineannotation>// will result in 11, which is the value of property 'spouse.age' of bean 'person'</lineannotation><![CDATA[
<bean id="theAge"
    class="org.springframework.beans.factory.config.PropertyPathFactoryBean">
  <property name="targetBeanName" value="person"/>
  <property name="propertyPath" value="spouse.age"/>
</bean>]]></programlisting>
                    <para>In this example, a path is evaluated against an inner bean:</para>
                    <programlisting language="xml"><lineannotation>&lt;!-- will result in 12, which is the value of property 'age' of the inner bean --&gt;</lineannotation><![CDATA[
<bean id="theAge"
    class="org.springframework.beans.factory.config.PropertyPathFactoryBean">
  <property name="targetObject">
    <bean class="org.springframework.beans.TestBean">
      <property name="age" value="12"/>
    </bean>
  </property>
  <property name="propertyPath" value="age"/>
</bean>]]></programlisting>
                    <para>There is also a shortcut form, where the bean name is the property path.</para>
                    <programlisting language="xml"><lineannotation>&lt;!-- will result in 10, which is the value of property 'age' of bean 'person' --&gt;</lineannotation><![CDATA[
<bean id="person.age"
    class="org.springframework.beans.factory.config.PropertyPathFactoryBean"/>]]></programlisting>
                <para>This form does mean that there is no choice in the name of the bean.
                    Any reference to it will also have to use the same id, which is the path.
                    Of course, if used as an inner bean, there is no need to refer to it at
                    all:</para>
                    <programlisting language="xml"><![CDATA[<bean id="..." class="...">
  <property name="age">
    <bean id="person.age"
        class="org.springframework.beans.factory.config.PropertyPathFactoryBean"/>
  </property>
</bean>]]></programlisting>
                    <para>The result type may be specifically set in the actual definition.
                    This is not necessary for most use cases, but can be of use for some.
                    Please see the Javadocs for more info on this feature.</para>
                </section>
            </section>
            <section xml:id="xsd-config-body-schemas-util-properties">
                <title><literal>&lt;util:properties/&gt;</literal></title>
                <para>Before...</para>
                <programlisting language="xml"><lineannotation>&lt;!-- creates a java.util.Properties instance with values loaded from the supplied location --&gt;</lineannotation><![CDATA[
<bean id="jdbcConfiguration" class="org.springframework.beans.factory.config.PropertiesFactoryBean">
  <property name="location" value="classpath:com/foo/jdbc-production.properties"/>
</bean>]]></programlisting>
                <para>The above configuration uses a Spring <interfacename>FactoryBean</interfacename>
                implementation, the <classname>PropertiesFactoryBean</classname>, to
                instantiate a <classname>java.util.Properties</classname> instance with values loaded from
                the supplied <link linkend="resources"><interfacename>Resource</interfacename></link> location).
                </para>
                <para>After...</para>
                <programlisting language="xml"><lineannotation>&lt;!-- creates a java.util.Properties instance with values loaded from the supplied location --&gt;</lineannotation><![CDATA[
<util:properties id="jdbcConfiguration" location="classpath:com/foo/jdbc-production.properties"/>]]></programlisting>
            </section>
            <section xml:id="xsd-config-body-schemas-util-list">
                <title><literal>&lt;util:list/&gt;</literal></title>
                <para>Before...</para>
                <programlisting language="xml"><lineannotation>&lt;!-- creates a java.util.List instance with values loaded from the supplied 'sourceList' --&gt;</lineannotation><![CDATA[
<bean id="emails" class="org.springframework.beans.factory.config.ListFactoryBean">
  <property name="sourceList">
      <list>
        <value>pechorin@hero.org</value>
        <value>raskolnikov@slums.org</value>
        <value>stavrogin@gov.org</value>
        <value>porfiry@gov.org</value>
      </list>
  </property>
</bean>]]></programlisting>
                <para>The above configuration uses a Spring <interfacename>FactoryBean</interfacename>
                implementation, the <classname>ListFactoryBean</classname>, to
                create a <classname>java.util.List</classname> instance initialized
                with values taken from the supplied <literal>'sourceList'</literal>.
                </para>
                <para>After...</para>
                <programlisting language="xml"><lineannotation>&lt;!-- creates a java.util.List instance with the supplied values --&gt;</lineannotation><![CDATA[
<util:list id="emails">
    <value>pechorin@hero.org</value>
    <value>raskolnikov@slums.org</value>
    <value>stavrogin@gov.org</value>
    <value>porfiry@gov.org</value>
</util:list>]]></programlisting>
                <para>You can also explicitly control the exact type of <interfacename>List</interfacename>
                that will be instantiated and populated via the use of the <literal>'list-class'</literal>
                attribute on the <literal>&lt;util:list/&gt;</literal> element. For example, if we
                really need a <classname>java.util.LinkedList</classname> to be instantiated, we could
                use the following configuration:</para>
                <programlisting language="xml"><![CDATA[<util:list id="emails" list-class="java.util.LinkedList">
    <value>jackshaftoe@vagabond.org</value>
    <value>eliza@thinkingmanscrumpet.org</value>
    <value>vanhoek@pirate.org</value>
    <value>d'Arcachon@nemesis.org</value>
</util:list>]]></programlisting>
                <para>If no <literal>'list-class'</literal> attribute is supplied, a
                <interfacename>List</interfacename> implementation will be chosen by the container.</para>
                <!-- Commented out until SPR-6523 is resolved.
                <para>Finally, you can also control the merging behavior using the
                <literal>'merge'</literal> attribute of the <literal>&lt;util:list/&gt;</literal>
                element; collection merging is described in more detail in
                <xref linkend="beans-collection-elements-merging"/>.</para>
                -->
            </section>
            <section xml:id="xsd-config-body-schemas-util-map">
                <title><literal>&lt;util:map/&gt;</literal></title>
                <para>Before...</para>
                <programlisting language="xml"><lineannotation>&lt;!-- creates a java.util.Map instance with values loaded from the supplied 'sourceMap' --&gt;</lineannotation><![CDATA[
<bean id="emails" class="org.springframework.beans.factory.config.MapFactoryBean">
  <property name="sourceMap">
      <map>
        <entry key="pechorin" value="pechorin@hero.org"/>
        <entry key="raskolnikov" value="raskolnikov@slums.org"/>
        <entry key="stavrogin" value="stavrogin@gov.org"/>
        <entry key="porfiry" value="porfiry@gov.org"/>
      </map>
  </property>
</bean>]]></programlisting>
                <para>The above configuration uses a Spring <interfacename>FactoryBean</interfacename>
                implementation, the <classname>MapFactoryBean</classname>, to
                create a <classname>java.util.Map</classname> instance initialized
                with key-value pairs taken from the supplied <literal>'sourceMap'</literal>.
                </para>
                <para>After...</para>
                <programlisting language="xml"><lineannotation>&lt;!-- creates a java.util.Map instance with the supplied key-value pairs --&gt;</lineannotation><![CDATA[
<util:map id="emails">
    <entry key="pechorin" value="pechorin@hero.org"/>
    <entry key="raskolnikov" value="raskolnikov@slums.org"/>
    <entry key="stavrogin" value="stavrogin@gov.org"/>
    <entry key="porfiry" value="porfiry@gov.org"/>
</util:map>]]></programlisting>
                <para>You can also explicitly control the exact type of <interfacename>Map</interfacename>
                that will be instantiated and populated via the use of the <literal>'map-class'</literal>
                attribute on the <literal>&lt;util:map/&gt;</literal> element. For example, if we
                really need a <classname>java.util.TreeMap</classname> to be instantiated, we could
                use the following configuration:</para>
                <programlisting language="xml"><![CDATA[<util:map id="emails" map-class="java.util.TreeMap">
    <entry key="pechorin" value="pechorin@hero.org"/>
    <entry key="raskolnikov" value="raskolnikov@slums.org"/>
    <entry key="stavrogin" value="stavrogin@gov.org"/>
    <entry key="porfiry" value="porfiry@gov.org"/>
</util:map>]]></programlisting>
                <para>If no <literal>'map-class'</literal> attribute is supplied, a
                <interfacename>Map</interfacename> implementation will be chosen by the container.</para>
                <!-- Commented out until SPR-6523 is resolved.
                <para>Finally, you can also control the merging behavior using the
                <literal>'merge'</literal> attribute of the <literal>&lt;util:map/&gt;</literal>
                element; collection merging is described in more detail in
                <xref linkend="beans-collection-elements-merging"/>.</para>
                -->
            </section>
            <section xml:id="xsd-config-body-schemas-util-set">
                <title><literal>&lt;util:set/&gt;</literal></title>
                <para>Before...</para>
                <programlisting language="xml"><lineannotation>&lt;!-- creates a java.util.Set instance with values loaded from the supplied 'sourceSet' --&gt;</lineannotation><![CDATA[
<bean id="emails" class="org.springframework.beans.factory.config.SetFactoryBean">
  <property name="sourceSet">
      <set>
        <value>pechorin@hero.org</value>
        <value>raskolnikov@slums.org</value>
        <value>stavrogin@gov.org</value>
        <value>porfiry@gov.org</value>
      </set>
  </property>
</bean>]]></programlisting>
                <para>The above configuration uses a Spring <interfacename>FactoryBean</interfacename>
                implementation, the <classname>SetFactoryBean</classname>, to
                create a <classname>java.util.Set</classname> instance initialized
                with values taken from the supplied <literal>'sourceSet'</literal>.
                </para>
                <para>After...</para>
                <programlisting language="xml"><lineannotation>&lt;!-- creates a java.util.Set instance with the supplied values --&gt;</lineannotation><![CDATA[
<util:set id="emails">
    <value>pechorin@hero.org</value>
    <value>raskolnikov@slums.org</value>
    <value>stavrogin@gov.org</value>
    <value>porfiry@gov.org</value>
</util:set>]]></programlisting>
                <para>You can also explicitly control the exact type of <interfacename>Set</interfacename>
                that will be instantiated and populated via the use of the <literal>'set-class'</literal>
                attribute on the <literal>&lt;util:set/&gt;</literal> element. For example, if we
                really need a <classname>java.util.TreeSet</classname> to be instantiated, we could
                use the following configuration:</para>
                <programlisting language="xml"><![CDATA[<util:set id="emails" set-class="java.util.TreeSet">
    <value>pechorin@hero.org</value>
    <value>raskolnikov@slums.org</value>
    <value>stavrogin@gov.org</value>
    <value>porfiry@gov.org</value>
</util:set>]]></programlisting>
                <para>If no <literal>'set-class'</literal> attribute is supplied, a
                <interfacename>Set</interfacename> implementation will be chosen by the container.</para>
                <!-- Commented out until SPR-6523 is resolved.
                <para>Finally, you can also control the merging behavior using the
                <literal>'merge'</literal> attribute of the <literal>&lt;util:set/&gt;</literal>
                element; collection merging is described in more detail in
                <xref linkend="beans-collection-elements-merging"/>.</para>
                -->
            </section>
        </section>
        <section xml:id="xsd-config-body-schemas-jee">
            <title>The <literal>jee</literal> schema</title>
            <para>The <literal>jee</literal> tags deal with Java EE (Java Enterprise Edition)-related
            configuration issues, such as looking up a JNDI object and defining EJB references.</para>
            <para>To use the tags in the <literal>jee</literal> schema, you need to have
            the following preamble at the top of your Spring XML configuration file;
            the text in the following snippet references the correct schema so that
            the tags in the <literal>jee</literal> namespace are available to you.</para>
            <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       ]]><emphasis role="bold">xmlns:jee="http://www.springframework.org/schema/jee"</emphasis><![CDATA[
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
]]><emphasis role="bold">http://www.springframework.org/schema/jee http://www.springframework.org/schema/jee/spring-jee.xsd"</emphasis><![CDATA[>

]]><lineannotation>&lt;!-- bean definitions here --&gt;</lineannotation><![CDATA[

</beans>]]></programlisting>
            <section xml:id="xsd-config-body-schemas-jee-jndi-lookup">
                <title><literal>&lt;jee:jndi-lookup/&gt;</literal> (simple)</title>
                <para>Before...</para>
                <programlisting language="xml"><![CDATA[<bean id="]]><emphasis role="bold"><![CDATA[dataSource]]></emphasis><![CDATA[" class="org.springframework.jndi.JndiObjectFactoryBean">
    <property name="jndiName" value="jdbc/MyDataSource"/>
</bean>

<bean id="userDao" class="com.foo.JdbcUserDao">
    ]]><lineannotation>&lt;!-- Spring will do the cast automatically (as usual) --&gt;</lineannotation><![CDATA[
    <property name="dataSource" ref="]]><emphasis role="bold">dataSource</emphasis>"/><![CDATA[
</bean>]]></programlisting>
                <para>After...</para>
                <programlisting language="xml"><![CDATA[<jee:jndi-lookup id="]]><emphasis role="bold"><![CDATA[dataSource]]></emphasis><![CDATA[" jndi-name="jdbc/MyDataSource"/>

<bean id="userDao" class="com.foo.JdbcUserDao">
    ]]><lineannotation>&lt;!-- Spring will do the cast automatically (as usual) --&gt;</lineannotation><![CDATA[
    <property name="dataSource" ref="]]><emphasis role="bold">dataSource</emphasis>"/><![CDATA[
</bean>]]></programlisting>
            </section>
            <section xml:id="xsd-config-body-schemas-jee-jndi-lookup-environment-single">
                <title><literal>&lt;jee:jndi-lookup/&gt;</literal> (with single JNDI environment setting)</title>
                <para>Before...</para>
                <programlisting language="xml"><![CDATA[<bean id="simple" class="org.springframework.jndi.JndiObjectFactoryBean">
    <property name="jndiName" value="jdbc/MyDataSource"/>
    <property name="jndiEnvironment">
        <props>
            <prop key="foo">bar</prop>
        </props>
    </property>
</bean>]]></programlisting>
                <para>After...</para>
                <programlisting language="xml"><![CDATA[<jee:jndi-lookup id="simple" jndi-name="jdbc/MyDataSource">
    <jee:environment>foo=bar</jee:environment>
</jee:jndi-lookup>]]></programlisting>
            </section>
            <section xml:id="xsd-config-body-schemas-jee-jndi-lookup-evironment-multiple">
                <title><literal>&lt;jee:jndi-lookup/&gt;</literal> (with multiple JNDI environment settings)</title>
                <para>Before...</para>
                <programlisting language="xml"><![CDATA[<bean id="simple" class="org.springframework.jndi.JndiObjectFactoryBean">
    <property name="jndiName" value="jdbc/MyDataSource"/>
    <property name="jndiEnvironment">
        <props>
            <prop key="foo">bar</prop>
            <prop key="ping">pong</prop>
        </props>
    </property>
</bean>]]></programlisting>
                <para>After...</para>
                <programlisting language="xml"><![CDATA[<jee:jndi-lookup id="simple" jndi-name="jdbc/MyDataSource">
    ]]><lineannotation>&lt;!-- newline-separated, key-value pairs for the environment (standard Properties format) --&gt;</lineannotation><![CDATA[
    <jee:environment>
        foo=bar
        ping=pong
    </jee:environment>
</jee:jndi-lookup>]]></programlisting>
            </section>
            <section xml:id="xsd-config-body-schemas-jee-jndi-lookup-complex">
                <title><literal>&lt;jee:jndi-lookup/&gt;</literal> (complex)</title>
                <para>Before...</para>
                <programlisting language="xml"><![CDATA[<bean id="simple" class="org.springframework.jndi.JndiObjectFactoryBean">
    <property name="jndiName" value="jdbc/MyDataSource"/>
    <property name="cache" value="true"/>
    <property name="resourceRef" value="true"/>
    <property name="lookupOnStartup" value="false"/>
    <property name="expectedType" value="com.myapp.DefaultFoo"/>
    <property name="proxyInterface" value="com.myapp.Foo"/>
</bean>]]></programlisting>
                <para>After...</para>
                <programlisting language="xml"><![CDATA[<jee:jndi-lookup id="simple"
             jndi-name="jdbc/MyDataSource"
             cache="true"
             resource-ref="true"
             lookup-on-startup="false"
             expected-type="com.myapp.DefaultFoo"
             proxy-interface="com.myapp.Foo"/>]]></programlisting>
            </section>
            <section xml:id="xsd-config-body-schemas-jee-local-slsb">
                <title><literal>&lt;jee:local-slsb/&gt;</literal> (simple)</title>
                <para>The <literal>&lt;jee:local-slsb/&gt;</literal> tag configures a
                reference to an EJB Stateless SessionBean.</para>
                <para>Before...</para>
                <programlisting language="xml"><![CDATA[<bean id="simple"
      class="org.springframework.ejb.access.LocalStatelessSessionProxyFactoryBean">
  <property name="jndiName" value="ejb/RentalServiceBean"/>
  <property name="businessInterface" value="com.foo.service.RentalService"/>
</bean>]]></programlisting>
                <para>After...</para>
                <programlisting language="xml"><![CDATA[<jee:local-slsb id="simpleSlsb" jndi-name="ejb/RentalServiceBean"
    business-interface="com.foo.service.RentalService"/>]]></programlisting>
            </section>
            <section xml:id="xsd-config-body-schemas-jee-local-slsb-complex">
                <title><literal>&lt;jee:local-slsb/&gt;</literal> (complex)</title>
                <programlisting language="xml"><![CDATA[<bean id="complexLocalEjb"
      class="org.springframework.ejb.access.LocalStatelessSessionProxyFactoryBean">
  <property name="jndiName" value="ejb/RentalServiceBean"/>
  <property name="businessInterface" value="com.foo.service.RentalService"/>
  <property name="cacheHome" value="true"/>
  <property name="lookupHomeOnStartup" value="true"/>
  <property name="resourceRef" value="true"/>
</bean>]]></programlisting>
                <para>After...</para>
                <programlisting language="xml"><![CDATA[<jee:local-slsb id="complexLocalEjb"
    jndi-name="ejb/RentalServiceBean"
    business-interface="com.foo.service.RentalService"
    cache-home="true"
    lookup-home-on-startup="true"
    resource-ref="true">]]></programlisting>
            </section>
            <section xml:id="xsd-config-body-schemas-jee-remote-slsb">
                <title><literal>&lt;jee:remote-slsb/&gt;</literal></title>
                <para>The <literal>&lt;jee:remote-slsb/&gt;</literal> tag configures a
                reference to a <literal>remote</literal> EJB Stateless SessionBean.</para>
                <para>Before...</para>
                <programlisting language="xml"><![CDATA[<bean id="complexRemoteEjb"
      class="org.springframework.ejb.access.SimpleRemoteStatelessSessionProxyFactoryBean">
  <property name="jndiName" value="ejb/MyRemoteBean"/>
  <property name="businessInterface" value="com.foo.service.RentalService"/>
  <property name="cacheHome" value="true"/>
  <property name="lookupHomeOnStartup" value="true"/>
  <property name="resourceRef" value="true"/>
  <property name="homeInterface" value="com.foo.service.RentalService"/>
  <property name="refreshHomeOnConnectFailure" value="true"/>
</bean>]]></programlisting>
                <para>After...</para>
                <programlisting language="xml"><![CDATA[<jee:remote-slsb id="complexRemoteEjb"
    jndi-name="ejb/MyRemoteBean"
    business-interface="com.foo.service.RentalService"
    cache-home="true"
    lookup-home-on-startup="true"
    resource-ref="true"
    home-interface="com.foo.service.RentalService"
    refresh-home-on-connect-failure="true">]]></programlisting>
            </section>
        </section>
        <section xml:id="xsd-config-body-schemas-lang">
            <title>The <literal>lang</literal> schema</title>
            <para>The <literal>lang</literal> tags deal with exposing objects that have been
            written in a dynamic language such as JRuby or Groovy as beans in the Spring
            container.</para>
            <para>These tags (and the dynamic language support) are comprehensively covered
            in the chapter entitled <xref linkend="dynamic-language"/>. Please do consult that
            chapter for full details on this support and the <literal>lang</literal> tags
            themselves.</para>
            <para>In the interest of completeness, to use the tags in the <literal>lang</literal>
            schema, you need to have the following preamble at the top of your Spring XML
            configuration file; the text in the following snippet references the
            correct schema so that the tags in the <literal>lang</literal> namespace are
            available to you.</para>
            <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       ]]><emphasis role="bold">xmlns:lang="http://www.springframework.org/schema/lang"</emphasis><![CDATA[
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
]]><emphasis role="bold">http://www.springframework.org/schema/lang http://www.springframework.org/schema/lang/spring-lang.xsd"</emphasis><![CDATA[>

]]><lineannotation>&lt;!-- bean definitions here --&gt;</lineannotation><![CDATA[

</beans>]]></programlisting>
        </section>
        <section xml:id="xsd-config-body-schemas-jms">
            <title>The <literal>jms</literal> schema</title>
            <para>The <literal>jms</literal> tags deal with configuring JMS-related
            beans such as Spring's <link linkend="jms-mdp">MessageListenerContainers</link>.
            These tags are detailed in the section of the <link linkend="jms">JMS chapter</link>
            entitled <xref linkend="jms-namespace"/>. Please do consult that
            chapter for full details on this support and the <literal>jms</literal> tags
            themselves.</para>
            <para>In the interest of completeness, to use the tags in the <literal>jms</literal>
            schema, you need to have the following preamble at the top of your Spring XML
            configuration file; the text in the following snippet references the
            correct schema so that the tags in the <literal>jms</literal> namespace are
            available to you.</para>
            <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       ]]><emphasis role="bold">xmlns:jms="http://www.springframework.org/schema/jms"</emphasis><![CDATA[
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
]]><emphasis role="bold">http://www.springframework.org/schema/jms http://www.springframework.org/schema/jms/spring-jms.xsd"</emphasis><![CDATA[>

]]><lineannotation>&lt;!-- bean definitions here --&gt;</lineannotation><![CDATA[

</beans>]]></programlisting>
        </section>
        <section xml:id="xsd-config-body-schemas-tx">
            <title>The <literal>tx</literal> (transaction) schema</title>
            <para>The <literal>tx</literal> tags deal with configuring all of those
            beans in Spring's comprehensive support for transactions. These tags are
            covered in the chapter entitled <xref linkend="transaction"/>.</para>
            <tip>
                <para>You are strongly encouraged to look at the
                <filename>'spring-tx.xsd'</filename> file that ships with the Spring
                distribution. This file is (of course), the XML Schema for Spring's
                transaction configuration, and covers all of the various tags in the
                <literal>tx</literal> namespace, including attribute defaults and
                suchlike. This file is documented inline, and thus the information is
                not repeated here in the interests of adhering to the DRY (Don't Repeat
                Yourself) principle.</para>
            </tip>
            <para>In the interest of completeness, to use the tags in the <literal>tx</literal>
            schema, you need to have the following preamble at the top of your Spring XML
            configuration file; the text in the following snippet references the
            correct schema so that the tags in the <literal>tx</literal> namespace are
            available to you.</para>
            <programlisting language="xml"><![CDATA[<?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"
       ]]><emphasis role="bold">xmlns:tx="http://www.springframework.org/schema/tx"</emphasis><![CDATA[
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
]]><emphasis role="bold">http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx.xsd</emphasis><![CDATA[
http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop.xsd">

]]><lineannotation>&lt;!-- bean definitions here --&gt;</lineannotation><![CDATA[

</beans>]]></programlisting>
            <note>
                <para>Often when using the tags in the <literal>tx</literal> namespace you will also be using
                the tags from the <literal>aop</literal> namespace (since the declarative transaction support in Spring is implemented using
                AOP). The above XML snippet contains the relevant lines needed to reference the <literal>aop</literal> schema
                so that the tags in the <literal>aop</literal> namespace are available to you.</para>
            </note>
        </section>
        <section xml:id="xsd-config-body-schemas-aop">
            <title>The <literal>aop</literal> schema</title>
            <para>The <literal>aop</literal> tags deal with configuring all things
            AOP in Spring: this includes Spring's own proxy-based AOP framework and Spring's
            integration with the AspectJ AOP framework. These tags are
            comprehensively covered in the chapter entitled <xref linkend="aop"/>.</para>
            <para>In the interest of completeness, to use the tags in the <literal>aop</literal>
            schema, you need to have the following preamble at the top of your Spring XML
            configuration file; the text in the following snippet references the
            correct schema so that the tags in the <literal>aop</literal> namespace are
            available to you.</para>
            <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       ]]><emphasis role="bold">xmlns:aop="http://www.springframework.org/schema/aop"</emphasis><![CDATA[
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
]]><emphasis role="bold">http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop.xsd"</emphasis><![CDATA[>

]]><lineannotation>&lt;!-- bean definitions here --&gt;</lineannotation><![CDATA[

</beans>]]></programlisting>
        </section>

        <section xml:id="xsd-config-body-schemas-context">
            <title>The <literal>context</literal> schema</title>
            <para>The <literal>context</literal> tags deal with <interfacename>ApplicationContext</interfacename>
            configuration that relates to plumbing - that is, not usually beans that are important to an end-user
            but rather beans that do a lot of grunt work in Spring, such as <interfacename>BeanfactoryPostProcessors</interfacename>.
            The following snippet references the correct schema so that the tags in the <literal>context</literal>
            namespace are available to you.</para>
            <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       ]]><emphasis role="bold">xmlns:context="http://www.springframework.org/schema/context"</emphasis><![CDATA[
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
]]><emphasis role="bold">http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd"</emphasis><![CDATA[>

]]><lineannotation>&lt;!-- bean definitions here --&gt;</lineannotation><![CDATA[

</beans>]]></programlisting>
            <note>
                <para>The <literal>context</literal> schema was only introduced in Spring 2.5.</para>
            </note>
            <section xml:id="xsd-config-body-schemas-context-pphc">
                <title><literal>&lt;property-placeholder/&gt;</literal></title>
                <para>This element activates the replacement of <literal>${...}</literal> placeholders, resolved
                against the specified properties file (as a <link linkend="resources">Spring resource location</link>).
                This element is a convenience mechanism that sets up a
                <link linkend="beans-factory-placeholderconfigurer"><classname>PropertyPlaceholderConfigurer</classname></link>
                for you; if you need more control over the <classname>PropertyPlaceholderConfigurer</classname>, just
                define one yourself explicitly.</para>
            </section>
            <section xml:id="xsd-config-body-schemas-context-ac">
                <title><literal>&lt;annotation-config/&gt;</literal></title>
                <para>Activates the Spring infrastructure for various annotations to be detected in bean classes:
                Spring's <link linkend="beans-required-annotation"><interfacename>@Required</interfacename></link>
                and <link linkend="beans-annotation-config"><interfacename>@Autowired</interfacename></link>, as well as
                JSR 250's <interfacename>@PostConstruct</interfacename>, <interfacename>@PreDestroy</interfacename> and
                <interfacename>@Resource</interfacename> (if available), and JPA's
                <interfacename>@PersistenceContext</interfacename> and <interfacename>@PersistenceUnit</interfacename>
                (if available). Alternatively, you can choose to activate the individual
                <interfacename>BeanPostProcessors</interfacename> for those annotations explicitly.</para>
                <note>
                    <para>This element does <emphasis>not</emphasis> activate processing of Spring's
                    <link linkend="transaction-declarative-annotations"><interfacename>@Transactional</interfacename></link>
                    annotation. Use the
                    <link linkend="tx-decl-explained"><literal>&lt;tx:annotation-driven/&gt;</literal></link> element
                    for that purpose.</para>
                </note>
            </section>
            <section xml:id="xsd-config-body-schemas-context-component-scan">
                <title><literal>&lt;component-scan/&gt;</literal></title>
                <para>This element is detailed in <xref linkend="beans-annotation-config"/>.</para>
            </section>
            <section xml:id="xsd-config-body-schemas-context-ltw">
                <title><literal>&lt;load-time-weaver/&gt;</literal></title>
                <para>This element is detailed in <xref linkend="aop-aj-ltw"/>.</para>
            </section>
            <section xml:id="xsd-config-body-schemas-context-sc">
                <title><literal>&lt;spring-configured/&gt;</literal></title>
                <para>This element is detailed in <xref linkend="aop-atconfigurable"/>.</para>
            </section>
            <section xml:id="xsd-config-body-schemas-context-mbe">
                <title><literal>&lt;mbean-export/&gt;</literal></title>
                <para>This element is detailed in <xref linkend="jmx-context-mbeanexport"/>.</para>
            </section>
        </section>

        <section xml:id="xsd-config-body-schemas-tool">
            <title>The <literal>tool</literal> schema</title>
            <para>The <literal>tool</literal> tags are for use when you want to add
            tooling-specific metadata to your custom configuration elements. This metadata
            can then be consumed by tools that are aware of this metadata, and the tools can
            then do pretty much whatever they want with it (validation, etc.).</para>
            <para>The <literal>tool</literal> tags are not documented in this release of
            Spring as they are currently undergoing review. If you are a third party tool
            vendor and you would like to contribute to this review process, then do mail
            the Spring mailing list. The currently supported <literal>tool</literal>
            tags can be found in the file <literal>'spring-tool.xsd'</literal> in the
            <literal>'src/org/springframework/beans/factory/xml'</literal> directory of the
            Spring source distribution.</para>
        </section>

        <section xml:id="xsd-config-body-schemas-jdbc">
            <title>The <literal>jdbc</literal> schema</title>
            <para>The <literal>jdbc</literal> tags allow you to quickly configure an
            embedded database or initialize an existing data source. These tags are
            documented in <xref linkend="jdbc-embedded-database-support"/> and
            <xref linkend="jdbc-intializing-datasource"/> respectively.</para>
            <para>To use the tags in the <literal>jdbc</literal>
            schema, you need to have the following preamble at the top of your Spring XML
            configuration file; the text in the following snippet references the
            correct schema so that the tags in the <literal>jdbc</literal> namespace are
            available to you.</para>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       ]]><emphasis role="bold">xmlns:jdbc="http://www.springframework.org/schema/jdbc"</emphasis><![CDATA[
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
]]><emphasis role="bold">http://www.springframework.org/schema/jdbc http://www.springframework.org/schema/jdbc/spring-jdbc.xsd"</emphasis><![CDATA[>

]]><lineannotation>&lt;!-- bean definitions here --&gt;</lineannotation><![CDATA[

</beans>]]></programlisting>
        </section>

        <section xml:id="xsd-config-body-schemas-cache">
            <title>The <literal>cache</literal> schema</title>
            <para>The <literal>cache</literal> tags can be used to enable support for Spring's
            <interfacename>@CacheEvict</interfacename>, <interfacename>@CachePut</interfacename>
            and <interfacename>@Caching</interfacename> annotations. It it also supports declarative
            XML-based caching. See  <xref linkend="cache-annotation-enable"/> and
            <xref linkend="cache-declarative-xml"/> for details.</para>
            <para>To use the tags in the <literal>cache</literal>
            schema, you need to have the following preamble at the top of your Spring XML
            configuration file; the text in the following snippet references the
            correct schema so that the tags in the <literal>cache</literal> namespace are
            available to you.</para>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       ]]><emphasis role="bold">xmlns:jdbc="http://www.springframework.org/schema/cache"</emphasis><![CDATA[
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
]]><emphasis role="bold">http://www.springframework.org/schema/cache http://www.springframework.org/schema/jdbc/spring-cache.xsd"</emphasis><![CDATA[>

]]><lineannotation>&lt;!-- bean definitions here --&gt;</lineannotation><![CDATA[

</beans>]]></programlisting>
        </section>

        <section xml:id="xsd-config-body-schemas-beans">
            <title>The <literal>beans</literal> schema</title>
            <para>Last but not least we have the tags in the <literal>beans</literal> schema.
            These are the same tags that have been in Spring since the very dawn of the framework.
            Examples of the various tags in the <literal>beans</literal> schema are not shown here
            because they are quite comprehensively covered in <xref linkend="beans-factory-properties-detailed"/>
            (and indeed in that entire <link linkend="beans">chapter</link>).</para>
            <para>One thing that is new to the beans tags themselves in Spring 2.0 is the idea
            of arbitrary bean metadata. In Spring 2.0 it is now possible to add zero or more
            key / value pairs to <literal>&lt;bean/&gt;</literal> XML definitions. What, if
            anything, is done with this extra metadata is totally up to your own custom logic (and
            so is typically only of use if you are writing your own custom tags as described in
            the appendix entitled <xref linkend="extensible-xml"/>).</para>
            <para>Find below an example of the <literal>&lt;meta/&gt;</literal> tag in the context
            of a surrounding <literal>&lt;bean/&gt;</literal> (please note that without any logic
            to interpret it the metadata is effectively useless as-is).</para>
            <programlisting language="xml"><![CDATA[<?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.xsd">

    <bean id="foo" class="x.y.Foo">
        ]]><emphasis role="bold"><![CDATA[<meta key="cacheName" value="foo"/>]]></emphasis><![CDATA[
        <property name="name" value="Rick"/>
    </bean>

</beans>]]></programlisting>
            <para>In the case of the above example, you would assume that there is some
            logic that will consume the bean definition and set up some caching infrastructure
            using the supplied metadata.</para>
        </section>
    </section>
    <!-- Commented pending resolution of SPR-7521
    <section xml:id="xsd-config-setup">
        <title>Setting up your IDE</title>
        <para>This final section documents the steps involved in setting up a number of
        popular Java IDEs to effect the easier editing of Spring's XML Schema-based
        configuration files. If your favourite Java IDE or editor is not included in the
        list of documented IDEs, then please do
        <link xl:href="http://opensource.atlassian.com/projects/spring/secure/Dashboard.jspa">raise an issue</link>
        and an example with your favorite IDE/editor <emphasis>may</emphasis> be included
        in the next release.</para>
        <section xml:id="xsd-config-setup-eclipse">
        <title>Setting up Eclipse</title>
        <procedure>
            <para>The following steps illustrate setting up
            <link xl:href="http://www.eclipse.org/">Eclipse</link> to be XSD-aware.
            The assumption in the following steps is that you already have an Eclipse
            project open (either a brand new project or an already existing one).</para>
            <note>
                <para>The following steps were created using Eclipse <emphasis role="bold">3.2</emphasis>.
                The setup will probably be the same (or similar) on an earlier or later
                version of Eclipse.</para>
            </note>
            <step>
                <title>Step One</title>
                <para>Create a new XML file. You can name this file whatever you want. In the
                example below, the file is named <literal>'context.xml'</literal>.
                Copy and paste the following text into the file so that it matches the screenshot.</para>
                <programlisting language="xml"><![CDATA[<?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.xsd
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">

</beans>]]></programlisting>
                <para>
                    <mediaobject>
                        <imageobject role="fo">
                            <imagedata fileref="images/eclipse-setup-1.png" format="PNG" align="center" />
                        </imageobject>
                        <imageobject role="html">
                            <imagedata fileref="images/eclipse-setup-1.png" format="PNG" align="center" />
                        </imageobject>
                    </mediaobject>
                </para>
            </step>
            <step>
                <title>Step Two</title>
                <para>As can be seen in the above screenshot (unless you have a customised
                version of Eclipse with the correct plugins) the XML file will be treated
                as plain text. There is no XML editing support out of the box in Eclipse,
                and as such there is not even any syntax highlighting of elements and attributes.
                To address this, you will have to install an XML editor plugin for Eclipse...</para>
                <table id="xsd-config-setup-eclipse-plugins">
                    <title>Eclipse XML editors</title>
                    <tgroup cols="2">
                        <colspec align="left" />
                        <thead>
                            <row>
                                <entry align="center">XML Editor</entry>
                                <entry align="center">Link</entry>
                            </row>
                        </thead>
                        <tbody>
                            <row>
                                <entry>
                                    <para>The Eclipse Web Tools Platform (WTP)</para>
                                </entry>
                                <entry>
                                    <link xl:href="http://www.eclipse.org/webtools/"/>
                                </entry>
                            </row>
                            <row>
                                <entry>
                                    <para>A list of Eclipse XML plugins</para>
                                </entry>
                                <entry>
                                    <link xl:href="http://eclipse-plugins.2y.net/eclipse/plugins.jsp?category=XML"/>
                                </entry>
                            </row>
                        </tbody>
                    </tgroup>
                </table>
                <sidebar>
                    <title>Contributing documentation...</title>
                    <para>Patches showing how to configure an Eclipse XML editor are
                    welcomed. Any such contributions are best submitted as patches via
                    the Spring Framework
                    <link xl:href="http://opensource.atlassian.com/projects/spring/secure/Dashboard.jspa">JIRA Issue Tracker</link>
                    and <emphasis>may</emphasis> be featured in the next release.</para>
                </sidebar>
                <para>Unfortunately, precisely because there is no standard XML editor for Eclipse,
                there are (bar the one below) no further steps showing you how to configure XML
                Schema support in Eclipse... each XML editor plugin would require its very own
                dedicated section, and this is <emphasis>Spring</emphasis> reference documentation,
                not Eclipse XML editor documentation. You will have to read the documentation that
                comes with your XML editor plugin (good luck there) and figure it out for yourself.</para>
            </step>
            <step>
                <title>Spring IDE</title>
                <para>There is a dedicated Spring Framework plugin for Eclipse called
                <link xl:href="http://springide.org/blog/">Spring IDE</link> and it is pretty darn cool. (There's a
                considered and non-biased opinion for you!) This plugin makes using Spring even easier, and it has more
                than just support for the core Spring Framework... Spring Web Flow is supported too. Details of how to
                install Spring IDE can be found on the
                <link xl:href="http://springide.org/project/wiki/SpringideInstall">Spring IDE installation page</link>.</para>
                <para>
                    <mediaobject>
                        <imageobject role="fo">
                            <imagedata fileref="images/eclipse-setup-3.png" format="PNG" align="center" />
                        </imageobject>
                        <imageobject role="html">
                            <imagedata fileref="images/eclipse-setup-3.png" format="PNG" align="center" />
                        </imageobject>
                    </mediaobject>
                </para>
            </step>
            <step>
                <title>Web Tools Platform (WTP) for Eclipse</title>
                <para>If you are using the Web Tools Platform (WTP) for Eclipse, you don't need to
                do anything other than open a Spring XML configuration file using the WTP platform's
                XML editor. As can be seen in the screenshot below, you immediately get some slick
                IDE-level support for autocompleting tags and suchlike.</para>
                <para>
                    <mediaobject>
                        <imageobject role="fo">
                            <imagedata fileref="images/eclipse-setup-2.png" format="PNG" align="center" />
                        </imageobject>
                        <imageobject role="html">
                            <imagedata fileref="images/eclipse-setup-2.png" format="PNG" align="center" />
                        </imageobject>
                    </mediaobject>
                </para>
            </step>
        </procedure>
        </section>
        <section xml:id="xsd-config-setup-idea">
        <title>Setting up IntelliJ IDEA</title>
        <procedure>
            <para>The following steps illustrate setting up the
            <link xl:href="http://www.jetbrains.com/idea/">IntelliJ IDEA</link> IDE to be XSD-aware.
            The assumption in the following steps is that you already have an IDEA project
            open (either a brand new project or an already existing one).</para>
            <step>
                <title>Step One</title>
                <para>Create a new XML file (you can name this file whatever you want). In the
                example below, the file is named <literal>'context.xml'</literal>. Copy and paste
                the following text into the file so that it matches the screenshot.</para>
                <programlisting language="xml"><![CDATA[<?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.xsd
       http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">

</beans>]]></programlisting>
                <para>
                    <mediaobject>
                        <imageobject role="fo">
                            <imagedata fileref="images/idea-setup-1.png" format="PNG" align="center" />
                        </imageobject>
                        <imageobject role="html">
                            <imagedata fileref="images/idea-setup-1.png" format="PNG" align="center" />
                        </imageobject>
                    </mediaobject>
                </para>
            </step>
            <step>
                <title>Step Two</title>
                <para>As can be seen in the above screenshot, the XML file has a number
                of nasty red contextual error markers. To rectify this, IDEA has to be
                made aware of the location of the referenced XSD namespace(s).</para>
                <para>To do this, simply position the cursor over the squiggly red
                area (see the screenshot below); then press the <keycombo action='open'>
                    <keycap>Alt</keycap>
                    <keycap>Enter</keycap>
                    </keycombo> keystroke combination, and press the <keycombo action='open'>
                    <keycap>Enter</keycap>
                 </keycombo> key again when the popup becomes active to fetch the external
                 resource.</para>
                <para>
                    <mediaobject>
                        <imageobject role="fo">
                            <imagedata fileref="images/idea-setup-6.png" format="PNG" align="center" />
                        </imageobject>
                        <imageobject role="html">
                            <imagedata fileref="images/idea-setup-6.png" format="PNG" align="center" />
                        </imageobject>
                    </mediaobject>
                </para>
            </step>
            <step>
                <title>Step Three</title>
                <para>If the external resource could not be fetched (maybe no active Internet
                connection is available), you can manually configure the resource to
                reference a local copy of the XSD file. Simply open up the <literal>'Settings'</literal> dialog
                (using the <keycombo action='open'>
                    <keycap>Ctrl</keycap>
                    <keycap>A</keycap>
                    <keycap>S</keycap>
                 </keycombo> keystroke combination or via the <literal>'File|Settings'</literal> menu),
                 and click on the <literal>'Resources'</literal> button.</para>
                <para>
                    <mediaobject>
                        <imageobject role="fo">
                            <imagedata fileref="images/idea-setup-2.png" format="PNG" align="center" />
                        </imageobject>
                        <imageobject role="html">
                            <imagedata fileref="images/idea-setup-2.png" format="PNG" align="center" />
                        </imageobject>
                    </mediaobject>
                </para>
            </step>
            <step>
                <title>Step Four</title>
                <para>As can be seen in the following screenshot, this will bring up a dialog
                that allows you to add an explicit reference to a local copy of the
                <literal>util</literal> schema file. (You can find all of the various Spring
                XSD files in the <literal>'src'</literal> directory of the Spring distribution.)</para>
                <para>
                    <mediaobject>
                        <imageobject role="fo">
                            <imagedata fileref="images/idea-setup-3.png" format="PNG" align="center" />
                        </imageobject>
                        <imageobject role="html">
                            <imagedata fileref="images/idea-setup-3.png" format="PNG" align="center" />
                        </imageobject>
                    </mediaobject>
                </para>
            </step>
            <step>
                <title>Step Five</title>
                <para>Clicking the <literal>'Add'</literal> button will bring up another dialog
                that allows you to explicitly to associate a namespace URI with the path to the
                relevant XSD file. As can be seen in the following screenshot, the
                <literal>'http://www.springframework.org/schema/util'</literal> namespace
                is being associated with the file resource
                <literal>'C:\bench\spring\src\org\springframework\beans\factory\xml\spring-util.xsd'</literal>.</para>
                <para>
                    <mediaobject>
                        <imageobject role="fo">
                            <imagedata fileref="images/idea-setup-4.png" format="PNG" align="center" />
                        </imageobject>
                        <imageobject role="html">
                            <imagedata fileref="images/idea-setup-4.png" format="PNG" align="center" />
                        </imageobject>
                    </mediaobject>
                </para>
            </step>
            <step>
                <title>Step Six</title>
                <para>Exiting out of the nested dialogs by clicking the <literal>'OK'</literal> button
                will then bring back the main editing window, and as can be seen in the
                following screenshot, the contextual error markers have disappeared; typing
                the <literal>'&lt;'</literal> character into the editing window now also
                brings up a handy dropdown box that contains all of the imported tags from
                the <literal>util</literal> namespace.</para>
                <para>
                    <mediaobject>
                        <imageobject role="fo">
                            <imagedata fileref="images/idea-setup-5.png" format="PNG" align="center" />
                        </imageobject>
                        <imageobject role="html">
                            <imagedata fileref="images/idea-setup-5.png" format="PNG" align="center" />
                        </imageobject>
                    </mediaobject>
                </para>
            </step>
            <para>Repeat as required for setting up IDEA to reference the other Spring XSD files.</para>
        </procedure>
        </section>

        <section xml:id="xsd-config-integration">
            <title>Integration issues</title>
            <para>This final section details integration issues that may arise when you switch over
            to using the above XSD-style for Spring 2.0 and later configuration.</para>
            <para>This section is quite small at the moment (and hopefully it will stay that way).
            It has been included in the Spring documentation as a convenience to Spring users
            so that if you encounter an issue when switching over to the XSD-style in some
            specific environment you can refer to this section for the authoritative answer.</para>
            <section xml:id="xsd-config-integration-resin">
                <title>XML parsing errors in the Resin v.3 application server</title>
                <para>If you are using the XSD-style for Spring 2.0 XML configuration
                and deploying to v.3 of Caucho's Resin application server, you will need
                to set some configuration options prior to startup so that an XSD-aware
                parser is available to Spring.</para>
                <para>Please do read this resource,
                <link xl:href="http://www.caucho.com/resin-3.0/xml/jaxp.xtp#xerces">http://www.caucho.com/resin-3.0/xml/jaxp.xtp#xerces</link>,
                for further details.</para>
            </section>
        </section>
    </section>
    -->
</appendix>
