1133 lines
69 KiB
XML
1133 lines
69 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<appendix id="xsd-config">
|
|
<title>XML Schema-based configuration</title>
|
|
<section id="xsd-config-introduction">
|
|
<title>Introduction</title>
|
|
<para>This appendix details the XML Schema-based configuration introduced in Spring 2.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><bean/></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><bean/></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><bean/></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 id="xsd-config-body">
|
|
<title>XML Schema-based configuration</title>
|
|
<section 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><!-- <literal><bean/></literal> definitions here --></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-2.5.xsd">
|
|
|
|
]]><lineannotation><!-- <literal><bean/></literal> definitions here --></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><bean/></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>
|
|
</section>
|
|
<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 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 emboldened 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-2.5.xsd
|
|
]]><emphasis role="bold">http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.5.xsd"</emphasis><![CDATA[>
|
|
|
|
]]><lineannotation><!-- <literal><bean/></literal> definitions here --></lineannotation><![CDATA[
|
|
|
|
</beans>]]></programlisting>
|
|
<section id="xsd-config-body-schemas-util-constant">
|
|
<title><literal><util:constant/></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 (unneccessarily)
|
|
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 id="xsd-config-body-schemas-util-frfb">
|
|
<title>Setting a bean property or constructor arg from a field value</title>
|
|
<para>
|
|
<ulink url="http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/beans/factory/config/FieldRetrievingFactoryBean.html"><classname>FieldRetrievingFactoryBean</classname></ulink>
|
|
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 <ulink url="http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/beans/factory/config/FieldRetrievingFactoryBean.html#setStaticField(java.lang.String)"><literal>staticField</literal></ulink>
|
|
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
|
|
<ulink url="http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/beans/factory/config/FieldRetrievingFactoryBean.html"><classname>FieldRetrievingFactoryBean</classname></ulink>
|
|
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 id="xsd-config-body-schemas-util-property-path">
|
|
<title><literal><util:property-path/></literal></title>
|
|
<para>Before...</para>
|
|
<programlisting language="xml"><lineannotation><!-- target bean to be referenced by name --></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><!-- will result in 10, which is the value of property 'age' of bean 'testBean' --></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><!-- target bean to be referenced by name --></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><!-- will result in 10, which is the value of property 'age' of bean 'testBean' --></lineannotation><![CDATA[
|
|
<util:property-path id="name" path="testBean.age"/>]]></programlisting>
|
|
<para>The value of the <literal>'path'</literal> attribute of the
|
|
<literal><property-path/></literal> tag follows the form <literal>'beanName.beanProperty'</literal>.</para>
|
|
<section id="xsd-config-body-schemas-util-property-path-dependency">
|
|
<title>Using <literal><util:property-path/></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><!-- will result in 12, which is the value of property 'age' of the inner bean --></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><!-- will result in 10, which is the value of property 'age' of bean 'person' --></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 id="xsd-config-body-schemas-util-properties">
|
|
<title><literal><util:properties/></literal></title>
|
|
<para>Before...</para>
|
|
<programlisting language="xml"><lineannotation><!-- creates a <classname>java.util.Properties</classname> instance with values loaded from the supplied location --></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><!-- creates a <classname>java.util.Properties</classname> instance with values loaded from the supplied location --></lineannotation><![CDATA[
|
|
<util:properties id="jdbcConfiguration" location="classpath:com/foo/jdbc-production.properties"/>]]></programlisting>
|
|
</section>
|
|
<section id="xsd-config-body-schemas-util-list">
|
|
<title><literal><util:list/></literal></title>
|
|
<para>Before...</para>
|
|
<programlisting language="xml"><lineannotation><!-- creates a <classname>java.util.List</classname> instance with values loaded from the supplied <literal>'sourceList'</literal> --></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><!-- creates a <classname>java.util.List</classname> instance with values loaded from the supplied <literal>'sourceList'</literal> --></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><util:list/></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>
|
|
<para>Finally, you can also control the merging behavior using the
|
|
<literal>'merge'</literal> attribute of the <literal><util:list/></literal>
|
|
element; collection merging is described in more detail in the section entitled
|
|
<xref linkend="beans-collection-elements-merging"/>.</para>
|
|
</section>
|
|
<section id="xsd-config-body-schemas-util-map">
|
|
<title><literal><util:map/></literal></title>
|
|
<para>Before...</para>
|
|
<programlisting language="xml"><lineannotation><!-- creates a <classname>java.util.Map</classname> instance with values loaded from the supplied <literal>'sourceMap'</literal> --></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><!-- creates a <classname>java.util.Map</classname> instance with values loaded from the supplied <literal>'sourceMap'</literal> --></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><util:map/></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>
|
|
<para>Finally, you can also control the merging behavior using the
|
|
<literal>'merge'</literal> attribute of the <literal><util:map/></literal>
|
|
element; collection merging is described in more detail in the section entitled
|
|
<xref linkend="beans-collection-elements-merging"/>.</para>
|
|
</section>
|
|
<section id="xsd-config-body-schemas-util-set">
|
|
<title><literal><util:set/></literal></title>
|
|
<para>Before...</para>
|
|
<programlisting language="xml"><lineannotation><!-- creates a <classname>java.util.Set</classname> instance with values loaded from the supplied <literal>'sourceSet'</literal> --></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><!-- creates a <classname>java.util.Set</classname> instance with values loaded from the supplied <literal>'sourceSet'</literal> --></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><util:set/></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>
|
|
<para>Finally, you can also control the merging behavior using the
|
|
<literal>'merge'</literal> attribute of the <literal><util:set/></literal>
|
|
element; collection merging is described in more detail in the section entitled
|
|
<xref linkend="beans-collection-elements-merging"/>.</para>
|
|
</section>
|
|
</section>
|
|
<section id="xsd-config-body-schemas-jee">
|
|
<title>The <literal>jee</literal> schema</title>
|
|
<para>The <literal>jee</literal> tags deal with JEE (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 emboldened 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-2.5.xsd
|
|
]]><emphasis role="bold">http://www.springframework.org/schema/jee http://www.springframework.org/schema/jee/spring-jee-2.5.xsd"</emphasis><![CDATA[>
|
|
|
|
]]><lineannotation><!-- <literal><bean/></literal> definitions here --></lineannotation><![CDATA[
|
|
|
|
</beans>]]></programlisting>
|
|
<section id="xsd-config-body-schemas-jee-jndi-lookup">
|
|
<title><literal><jee:jndi-lookup/></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><!-- Spring will do the cast automatically (as usual) --></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><!-- Spring will do the cast automatically (as usual) --></lineannotation><![CDATA[
|
|
<property name="dataSource" ref="]]><emphasis role="bold">dataSource</emphasis>"/><![CDATA[
|
|
</bean>]]></programlisting>
|
|
</section>
|
|
<section id="xsd-config-body-schemas-jee-jndi-lookup-environment-single">
|
|
<title><literal><jee:jndi-lookup/></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 id="xsd-config-body-schemas-jee-jndi-lookup-evironment-multiple">
|
|
<title><literal><jee:jndi-lookup/></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><!-- newline-separated, key-value pairs for the environment (standard <classname>Properties</classname> format) --></lineannotation><![CDATA[
|
|
<jee:environment>
|
|
foo=bar
|
|
ping=pong
|
|
</jee:environment>
|
|
</jee:jndi-lookup>]]></programlisting>
|
|
</section>
|
|
<section id="xsd-config-body-schemas-jee-jndi-lookup-complex">
|
|
<title><literal><jee:jndi-lookup/></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 id="xsd-config-body-schemas-jee-local-slsb">
|
|
<title><literal><jee:local-slsb/></literal> (simple)</title>
|
|
<para>The <literal><jee:local-slsb/></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 id="xsd-config-body-schemas-jee-local-slsb-complex">
|
|
<title><literal><jee:local-slsb/></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 id="xsd-config-body-schemas-jee-remote-slsb">
|
|
<title><literal><jee:remote-slsb/></literal></title>
|
|
<para>The <literal><jee:remote-slsb/></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 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 emboldened 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-2.5.xsd
|
|
]]><emphasis role="bold">http://www.springframework.org/schema/lang http://www.springframework.org/schema/lang/spring-lang-2.5.xsd"</emphasis><![CDATA[>
|
|
|
|
]]><lineannotation><!-- <literal><bean/></literal> definitions here --></lineannotation><![CDATA[
|
|
|
|
</beans>]]></programlisting>
|
|
</section>
|
|
<section 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 emboldened 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-2.5.xsd
|
|
]]><emphasis role="bold">http://www.springframework.org/schema/jms http://www.springframework.org/schema/jms/spring-jms-2.5.xsd"</emphasis><![CDATA[>
|
|
|
|
]]><lineannotation><!-- <literal><bean/></literal> definitions here --></lineannotation><![CDATA[
|
|
|
|
</beans>]]></programlisting>
|
|
</section>
|
|
<section 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-2.5.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 emboldened 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-2.5.xsd
|
|
]]><emphasis role="bold">http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsd</emphasis><![CDATA[
|
|
http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-2.5.xsd">
|
|
|
|
]]><lineannotation><!-- <literal><bean/></literal> definitions here --></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 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 emboldened 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-2.5.xsd
|
|
]]><emphasis role="bold">http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-2.5.xsd"</emphasis><![CDATA[>
|
|
|
|
]]><lineannotation><!-- <literal><bean/></literal> definitions here --></lineannotation><![CDATA[
|
|
|
|
</beans>]]></programlisting>
|
|
</section>
|
|
|
|
<section 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-2.5.xsd
|
|
]]><emphasis role="bold">http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd"</emphasis><![CDATA[>
|
|
|
|
]]><lineannotation><!-- <literal><bean/></literal> definitions here --></lineannotation><![CDATA[
|
|
|
|
</beans>]]></programlisting>
|
|
<note>
|
|
<para>The <literal>context</literal> schema was only introduced in Spring 2.5.</para>
|
|
</note>
|
|
<section id="xsd-config-body-schemas-context-pphc">
|
|
<title><literal><property-placeholder/></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 id="xsd-config-body-schemas-context-ac">
|
|
<title><literal><annotation-config/></literal></title>
|
|
<para>Activates the Spring infrastructure for various annotations to be detected in bean classes:
|
|
Spring's <link linkend="metadata-annotations-required"><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 explictly.</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><tx:annotation-driven/></literal></link> element
|
|
for that purpose.</para>
|
|
</note>
|
|
</section>
|
|
<section id="xsd-config-body-schemas-context-component-scan">
|
|
<title><literal><component-scan/></literal></title>
|
|
<para>This element is detailed in the section entitled <xref linkend="beans-annotation-config"/>.</para>
|
|
</section>
|
|
<section id="xsd-config-body-schemas-context-ltw">
|
|
<title><literal><load-time-weaver/></literal></title>
|
|
<para>This element is detailed in the section entitled <xref linkend="aop-aj-ltw"/>.</para>
|
|
</section>
|
|
<section id="xsd-config-body-schemas-context-sc">
|
|
<title><literal><spring-configured/></literal></title>
|
|
<para>This element is detailed in the section entitled <xref linkend="aop-atconfigurable"/>.</para>
|
|
</section>
|
|
<section id="xsd-config-body-schemas-context-mbe">
|
|
<title><literal><mbean-export/></literal></title>
|
|
<para>This element is detailed in the section entitled <xref linkend="jmx-context-mbeanexport"/>.</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section 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-2.5.xsd'</literal> in the
|
|
<literal>'src/org/springframework/beans/factory/xml'</literal> directory of the
|
|
Spring source distribution.</para>
|
|
</section>
|
|
<section 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 the section entitled <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><bean/></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><meta/></literal> tag in the context
|
|
of a surrounding <literal><bean/></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-2.5.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>
|
|
<section 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
|
|
<ulink url="http://opensource.atlassian.com/projects/spring/secure/Dashboard.jspa">raise an issue</ulink>
|
|
and an example with your favorite IDE/editor <emphasis>may</emphasis> be included
|
|
in the next release.</para>
|
|
<section id="xsd-config-setup-eclipse">
|
|
<title>Setting up Eclipse</title>
|
|
<procedure>
|
|
<para>The following steps illustrate setting up
|
|
<ulink url="http://www.eclipse.org/">Eclipse</ulink> 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-2.5.xsd
|
|
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.5.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>
|
|
<ulink url="http://www.eclipse.org/webtools/"/>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>A list of Eclipse XML plugins</para>
|
|
</entry>
|
|
<entry>
|
|
<ulink url="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
|
|
<ulink url="http://opensource.atlassian.com/projects/spring/secure/Dashboard.jspa">JIRA Issue Tracker</ulink>
|
|
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
|
|
<ulink url="http://springide.org/blog/">Spring IDE</ulink> 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
|
|
<ulink url="http://springide.org/project/wiki/SpringideInstall">Spring IDE installation page</ulink>.</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 id="xsd-config-setup-idea">
|
|
<title>Setting up IntelliJ IDEA</title>
|
|
<procedure>
|
|
<para>The following steps illustrate setting up the
|
|
<ulink url="http://www.jetbrains.com/idea/">IntelliJ IDEA</ulink> 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-2.5.xsd
|
|
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.5.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-2.5.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>'<'</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 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 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 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,
|
|
<ulink url="http://www.caucho.com/resin-3.0/xml/jaxp.xtp#xerces">http://www.caucho.com/resin-3.0/xml/jaxp.xtp#xerces</ulink>,
|
|
for further details.</para>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
</appendix>
|