You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1141 lines
69 KiB
1141 lines
69 KiB
<?xml version="1.0" encoding="UTF-8"?> |
|
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
|
|
|
<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 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><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-3.0.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 bold 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-3.0.xsd |
|
]]><emphasis role="bold">http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-3.0.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/3.0.x/javadoc-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/3.0.x/javadoc-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/3.0.x/javadoc-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 the supplied values --></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> |
|
<!-- 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><util:list/></literal> |
|
element; collection merging is described in more detail in |
|
<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 the supplied key-value pairs --></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> |
|
<!-- 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><util:map/></literal> |
|
element; collection merging is described in more detail in |
|
<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 the supplied values --></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> |
|
<!-- 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><util:set/></literal> |
|
element; collection merging is described in more detail in |
|
<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 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 bold 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-3.0.xsd |
|
]]><emphasis role="bold">http://www.springframework.org/schema/jee http://www.springframework.org/schema/jee/spring-jee-3.0.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 bold 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-3.0.xsd |
|
]]><emphasis role="bold">http://www.springframework.org/schema/lang http://www.springframework.org/schema/lang/spring-lang-3.0.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 bold 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-3.0.xsd |
|
]]><emphasis role="bold">http://www.springframework.org/schema/jms http://www.springframework.org/schema/jms/spring-jms-3.0.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-3.0.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 bold 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-3.0.xsd |
|
]]><emphasis role="bold">http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-3.0.xsd</emphasis><![CDATA[ |
|
http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-3.0.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 bold 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-3.0.xsd |
|
]]><emphasis role="bold">http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-3.0.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-3.0.xsd |
|
]]><emphasis role="bold">http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.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="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 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 <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 <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 <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 <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-3.0.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 <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-3.0.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-3.0.xsd |
|
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-3.0.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-3.0.xsd |
|
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-3.0.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-3.0.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 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 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>
|
|
|