493 lines
21 KiB
XML
493 lines
21 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!--
|
|
/*
|
|
* Copyright 2002-2010 the original author or authors.
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
-->
|
|
<appendix id="xsd-config" version="5" xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:ns6="http://www.w3.org/1999/xlink"
|
|
xmlns:ns5="http://www.w3.org/1998/Math/MathML"
|
|
xmlns:ns4="http://www.w3.org/1999/xhtml"
|
|
xmlns:ns3="http://www.w3.org/2000/svg"
|
|
xmlns:ns="http://docbook.org/ns/docbook">
|
|
<title>XML Schema-based configuration</title>
|
|
|
|
<section xml:id="xsd-config-introduction">
|
|
<title>Introduction</title>
|
|
|
|
<para>This appendix details the use of XML Schema-based configuration in
|
|
Spring.</para>
|
|
|
|
<para>The <emphasis>'classic' </emphasis>
|
|
<literal><object/></literal>-based schema is good, but its
|
|
generic-nature comes with a price in terms of configuration overhead.
|
|
Creating a custom XML Schema-based configuration makes Spring XML
|
|
configuration files substantially clearer to read. In addition, it allows
|
|
you to express the intent of an object definition.</para>
|
|
|
|
<para>The key thing to remember is that creating custom schema tags work
|
|
best for infrastructure or integration objects: for example, AOP,
|
|
collections, transactions, integration with 3rd-party frameworks, etc.,
|
|
while the existing object tags are best suited to application-specific
|
|
objects, such as DAOs, service layer objects, etc.</para>
|
|
|
|
<para>Please note the fact that the XML configuration mechanism is totally
|
|
customisable and extensible. This means you can write your own
|
|
domain-specific configuration tags that would better represent your
|
|
application's domain; the process involved in doing so is covered in the
|
|
appendix entitled <xref linkend="extensible-xml" />.</para>
|
|
</section>
|
|
|
|
<section xml:id="xsd-config-body">
|
|
<title>XML Schema-based configuration</title>
|
|
|
|
<section xml:id="xsd-config-body-referencing">
|
|
<title>Referencing the schemas</title>
|
|
|
|
<para>As a reminder, you reference the standard objects schema as shown
|
|
below</para>
|
|
|
|
<programlisting language="myxml">
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<objects xmlns="http://www.springframework.net"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xsi:schemaLocation="http://www.springframework.net http://www.springframework.net/schema/objects/spring-objects-1.1.xsd">
|
|
|
|
<lineannotation> <!-- <literal><object/></literal> definitions here --></lineannotation>
|
|
|
|
</objects></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) and assumes the XML
|
|
editor will look to that location and load the schema.</para>
|
|
</note>
|
|
|
|
<para>The above Spring XML configuration fragment is boilerplate that
|
|
you can copy and paste (!) and then plug
|
|
<literal><object/></literal> definitions into like you have always
|
|
done. However, the entire point of using custom schema tags is to make
|
|
configuration easier.</para>
|
|
|
|
<para>The rest of this chapter gives an overview of custom XML Schema
|
|
based configuration that are included with the release.</para>
|
|
|
|
<note>
|
|
<para>As of Spring.NET 1.2.0 it is no longer necessary to explicitly
|
|
configure the namespace parsers that come with Spring via a custom
|
|
section in App.config. You will still need to register custom
|
|
namespace parsers if you are writing your own.</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section xml:id="xsd-config-body-schemas-tx">
|
|
<title>The <literal>tx</literal> (transaction) schema</title>
|
|
|
|
<para>The <literal>tx</literal> tags deal with configuring objects 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-1.1.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="myxml"><?xml version="1.0" encoding="UTF-8"?>
|
|
<object xmlns="http://www.springframework.net"
|
|
xmlns:aop="http://www.springframework.net/aop"
|
|
xmlns:tx="http://www.springframework.net/tx">
|
|
|
|
<lineannotation> <!-- <literal><object/></literal> definitions here --></lineannotation>
|
|
|
|
<!-- <tx/> transaction definitions here -->
|
|
|
|
<!-- <aop/> AOP definitions here -->
|
|
|
|
</object></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>
|
|
|
|
<para>You will also need to configure the AOP and Transaction namespace
|
|
parsers in the main .NET application configuration file as shown
|
|
below</para>
|
|
|
|
<note>
|
|
<para>As of Spring.NET 1.2.0 it is no longer necessary to explicitly
|
|
configure the namespace parsers that come with Spring via a custom
|
|
section in App.config. You will still need to register custom
|
|
namespace parsers if you are writing your own.</para>
|
|
</note>
|
|
|
|
<programlisting language="myxml"><configuration>
|
|
|
|
<configSections>
|
|
<sectionGroup name="spring">
|
|
<!-- other Spring config sections handler like context, typeAliases, etc not shown for brevity -->
|
|
<section name="parsers" type="Spring.Context.Support.NamespaceParsersSectionHandler, Spring.Core"/>
|
|
</sectionGroup>
|
|
</configSections>
|
|
|
|
<spring>
|
|
<parsers>
|
|
<parser type="Spring.Aop.Config.AopNamespaceParser, Spring.Aop" />
|
|
<parser type="Spring.Transaction.Config.TxNamespaceParser, Spring.Data" />
|
|
</parsers>
|
|
</spring>
|
|
|
|
</configuration></programlisting>
|
|
</section>
|
|
|
|
<section xml:id="xsd-config-body-schemas-aop">
|
|
<title>The <literal>aop</literal> schema</title>
|
|
|
|
<para>The <literal>aop</literal> tags deal with configuring all things
|
|
AOP in Spring. 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="myxml"><?xml version="1.0" encoding="UTF-8"?>
|
|
<objects xmlns="http://www.springframework.net"
|
|
xmlns:aop="http://www.springframework.net/aop">
|
|
|
|
<lineannotation> <!-- <literal><object/></literal> definitions here --></lineannotation>
|
|
|
|
<!-- <aop/> AOP definitions here -->
|
|
|
|
</objects></programlisting>
|
|
|
|
<para>You will also need to configure the AOP namespace parser in the
|
|
main .NET application configuration file as shown below</para>
|
|
|
|
<note>
|
|
<para>As of Spring.NET 1.2.0 it is no longer necessary to explicitly
|
|
configure the namespace parsers that come with Spring via a custom
|
|
section in App.config. You will still need to register custom
|
|
namespace parsers if you are writing your own.</para>
|
|
</note>
|
|
|
|
<programlisting language="myxml"><configuration>
|
|
|
|
<configSections>
|
|
<sectionGroup name="spring">
|
|
<!-- other Spring config sections handler like context, typeAliases, etc not shown for brevity -->
|
|
<section name="parsers" type="Spring.Context.Support.NamespaceParsersSectionHandler, Spring.Core"/>
|
|
</sectionGroup>
|
|
</configSections>
|
|
|
|
<spring>
|
|
<parsers>
|
|
<parser type="Spring.Aop.Config.AopNamespaceParser, Spring.Aop" />
|
|
</parsers>
|
|
</spring>
|
|
|
|
</configuration></programlisting>
|
|
</section>
|
|
|
|
<section xml:id="xsd-config-body-schemas-db">
|
|
<title>The <literal>db</literal> schema</title>
|
|
|
|
<para>The <literal>db</literal> tags deal with creating
|
|
<literal>IDbProvider</literal> instances for a given database client
|
|
library. The following snippet references the correct schema so that the
|
|
tags in the <literal>db</literal> namespace are available to you. The
|
|
tags are comprehensively covered in the chapter entitled <xref
|
|
linkend="dbprovider" />.</para>
|
|
|
|
<programlisting language="myxml"><?xml version="1.0" encoding="UTF-8"?>
|
|
<objects xmlns="http://www.springframework.net"
|
|
xmlns:db="http://www.springframework.net/db">
|
|
|
|
<lineannotation> <!-- <literal><object/></literal> definitions here --></lineannotation>
|
|
|
|
<!-- <db/> database definitions here -->
|
|
|
|
</objects></programlisting>
|
|
|
|
<para>You will also need to configure the Database namespace parser in
|
|
the main .NET application configuration file as shown below</para>
|
|
|
|
<note>
|
|
<para>As of Spring.NET 1.2.0 it is no longer necessary to explicitly
|
|
configure the namespace parsers that come with Spring via a custom
|
|
section in App.config. You will still need to register custom
|
|
namespace parsers if you are writing your own.</para>
|
|
</note>
|
|
|
|
<programlisting language="myxml"><configuration>
|
|
|
|
<configSections>
|
|
<sectionGroup name="spring">
|
|
<!-- other Spring config sections handler like context, typeAliases, etc not shown for brevity -->
|
|
<section name="parsers" type="Spring.Context.Support.NamespaceParsersSectionHandler, Spring.Core"/>
|
|
</sectionGroup>
|
|
</configSections>
|
|
|
|
<spring>
|
|
<parsers>
|
|
<parser type="Spring.Data.Config.DatabaseNamespaceParser, Spring.Data" />
|
|
</parsers>
|
|
</spring>
|
|
|
|
</configuration></programlisting>
|
|
</section>
|
|
|
|
<section xml:id="xsd-config-body-schemas-wcf">
|
|
<title>The <literal>wcf</literal> schema</title>
|
|
|
|
<para>The <literal>wcf</literal> schema is used when you would like to
|
|
create a client channel to invoke a WCF service as compared to
|
|
generating a proxy using svcutil.exe. The channel factory approach
|
|
requires that you have a known interface which describes the service.
|
|
This approach is quite common to use when you are controlling both the
|
|
client and the server code, but is not exclusive to that case. The
|
|
advantage of coding to the interface is that it can be easily replaced
|
|
with another implementation, perhaps for testing purposes to facilitate
|
|
unit testing. </para>
|
|
|
|
<para>For example, the following code can be used to create an instance
|
|
of the ICaclulator interface that invokes the remote service.</para>
|
|
|
|
<programlisting language="myxml">ICalculator calculator = ChannelFactory<ICalculator>("calculatorEndpoint").CreateChannel();
|
|
|
|
int result = calculator.Add(1,2);</programlisting>
|
|
|
|
<para>You need to configure the remoting namespace parser in the main
|
|
.NET application configuration file as shown below</para>
|
|
|
|
<note>
|
|
<para>As of Spring.NET 1.2.0 it is no longer necessary to explicitly
|
|
configure the namespace parsers that come with Spring via a custom
|
|
section in App.config. You will still need to register custom
|
|
namespace parsers if you are writing your own.</para>
|
|
</note>
|
|
|
|
<programlisting language="myxml"><configuration>
|
|
|
|
<configSections>
|
|
<sectionGroup name="spring">
|
|
<!-- other Spring config sections handler like context, typeAliases, etc not shown for brevity -->
|
|
<section name="parsers" type="Spring.Context.Support.NamespaceParsersSectionHandler, Spring.Core"/>
|
|
</sectionGroup>
|
|
</configSections>
|
|
|
|
<spring>
|
|
<parsers>
|
|
<parser type="Spring.ServiceModel.Config.WcfNamespaceParser, Spring.Services" />
|
|
</parsers>
|
|
</spring>
|
|
|
|
</configuration></programlisting>
|
|
</section>
|
|
|
|
<section xml:id="xsd-config-body-schemas-remoting">
|
|
<title>The <literal>remoting</literal> schema</title>
|
|
|
|
<para>The <literal>remoting</literal> tags are for use when you want to
|
|
export an existing POCO object as a .NET remoted object or to create a
|
|
client side .NET remoting proxy. The tags are comprehensively covered in
|
|
the chapter <xref linkend="remoting" /></para>
|
|
|
|
<programlisting language="myxml"><?xml version="1.0" encoding="UTF-8"?>
|
|
<objects xmlns="http://www.springframework.net"
|
|
xmlns:r="http://www.springframework.net/remoting">
|
|
|
|
<lineannotation> <!-- <literal><object/></literal> definitions here --></lineannotation>
|
|
|
|
<!-- <r/> remoting definitions here -->
|
|
|
|
</objects></programlisting>
|
|
|
|
<para>You will also need to configure the remoting namespace parser in
|
|
the main .NET application configuration file as shown below</para>
|
|
|
|
<note>
|
|
<para>As of Spring.NET 1.2.0 it is no longer necessary to explicitly
|
|
configure the namespace parsers that come with Spring via a custom
|
|
section in App.config. You will still need to register custom
|
|
namespace parsers if you are writing your own.</para>
|
|
</note>
|
|
|
|
<programlisting language="myxml"><configuration>
|
|
|
|
<configSections>
|
|
<sectionGroup name="spring">
|
|
<!-- other Spring config sections handler like context, typeAliases, etc not shown for brevity -->
|
|
<section name="parsers" type="Spring.Context.Support.NamespaceParsersSectionHandler, Spring.Core"/>
|
|
</sectionGroup>
|
|
</configSections>
|
|
|
|
<spring>
|
|
<parsers>
|
|
<parser type="Spring.Remoting.Config.RemotingNamespaceParser, Spring.Services" />
|
|
</parsers>
|
|
</spring>
|
|
|
|
</configuration></programlisting>
|
|
</section>
|
|
|
|
<section xml:id="xsd-config-body-schemas-nms">
|
|
<title>The <literal>nms</literal> messaging schema</title>
|
|
|
|
<para>The <literal>nms</literal> tags are for use when you want to
|
|
configure Spring's messaging support. The tags are comprehensively
|
|
covered in the chapter <xref linkend="messaging" /></para>
|
|
|
|
<programlisting language="myxml"><?xml version="1.0" encoding="UTF-8"?>
|
|
<objects xmlns="http://www.springframework.net"
|
|
xmlns:r="http://www.springframework.net/nms">
|
|
|
|
<lineannotation> <!-- <literal><object/></literal> definitions here --></lineannotation>
|
|
|
|
<!-- <nms/> remoting definitions here -->
|
|
|
|
</objects></programlisting>
|
|
|
|
<para>You will also need to configure the remoting namespace parser in
|
|
the main .NET application configuration file as shown below</para>
|
|
|
|
<note>
|
|
<para>As of Spring.NET 1.2.0 it is no longer necessary to explicitly
|
|
configure the namespace parsers that come with Spring via a custom
|
|
section in App.config. You will still need to register custom
|
|
namespace parsers if you are writing your own.</para>
|
|
</note>
|
|
|
|
<programlisting language="myxml"><configuration>
|
|
|
|
<configSections>
|
|
<sectionGroup name="spring">
|
|
<!-- other Spring config sections handler like context, typeAliases, etc not shown for brevity -->
|
|
<section name="parsers" type="Spring.Context.Support.NamespaceParsersSectionHandler, Spring.Core"/>
|
|
</sectionGroup>
|
|
</configSections>
|
|
|
|
<spring>
|
|
<parsers>
|
|
<parser type="Spring.Messaging.Nms.Config.NmsNamespaceParser, Spring.Messaging.Nms" />
|
|
</parsers>
|
|
</spring>
|
|
|
|
</configuration></programlisting>
|
|
</section>
|
|
|
|
<section xml:id="xsd-config-body-schemas-validation">
|
|
<title>The <literal>validation</literal> schema</title>
|
|
|
|
<para>The <literal>validation</literal> tags are for use when you want
|
|
definte <literal>IValidator</literal> object instances. The tags are
|
|
comprehensively covered in the chapter <xref
|
|
linkend="validation" /></para>
|
|
|
|
<programlisting language="myxml"><?xml version="1.0" encoding="UTF-8"?>
|
|
<objects xmlns="http://www.springframework.net"
|
|
xmlns:v="http://www.springframework.net/validation">
|
|
|
|
<lineannotation> <!-- <literal><object/></literal> definitions here --></lineannotation>
|
|
|
|
<!-- <v/> valdiation definitions here -->
|
|
|
|
</objects></programlisting>
|
|
|
|
<para>You will also need to configure the validation namespace parser in
|
|
the main .NET application configuration file as shown below</para>
|
|
|
|
<note>
|
|
<para>As of Spring.NET 1.2.0 it is no longer necessary to explicitly
|
|
configure the namespace parsers that come with Spring via a custom
|
|
section in App.config. You will still need to register custom
|
|
namespace parsers if you are writing your own.</para>
|
|
</note>
|
|
|
|
<programlisting language="myxml"><configuration>
|
|
|
|
<configSections>
|
|
<sectionGroup name="spring">
|
|
<!-- other Spring config sections handler like context, typeAliases, etc not shown for brevity -->
|
|
<section name="parsers" type="Spring.Context.Support.NamespaceParsersSectionHandler, Spring.Core"/>
|
|
</sectionGroup>
|
|
</configSections>
|
|
|
|
<spring>
|
|
<parsers>
|
|
<parser type="Spring.Validation.Config.ValidationNamespaceParser, Spring.Core" />
|
|
</parsers>
|
|
</spring>
|
|
|
|
</configuration></programlisting>
|
|
</section>
|
|
|
|
<section xml:id="xsd-config-body-schemas-objects">
|
|
<title>The <literal>objects</literal> schema</title>
|
|
|
|
<para>Last but not least we have the tags in the
|
|
<literal>objects</literal> schema. Examples of the various tags in the
|
|
<literal>objects</literal> schema are not shown here because they are
|
|
quite comprehensively covered in the section entitled <xref
|
|
linkend="object-factory-properties-detailed" /> (and indeed in that
|
|
entire <link linkend="objects">chapter</link>).</para>
|
|
|
|
<programlisting language="myxml"><?xml version="1.0" encoding="UTF-8"?>
|
|
<objects xmlns="http://www.springframework.net"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xsi:schemaLocation="http://www.springframework.net http://www.springframework.net/schema/objects/spring-objects-1.1.xsd">
|
|
|
|
<object id="foo" class="X.Y.Foo, X">
|
|
<property name="name" value="Rick"/>
|
|
</object>
|
|
|
|
</objects></programlisting>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="xsd-config-setup">
|
|
<title>Setting up your IDE</title>
|
|
|
|
<para>To setup VS.NET to provide intellisence while editing XML file for
|
|
your custom XML schemas you will need to copy your XSD files to an
|
|
appropriate VS.NET directory. Refer to the following chapter for details,
|
|
<xref linkend="vsnet" /></para>
|
|
|
|
<para>For SharpDevelop, follow the directions on the "<ulink
|
|
url="http://community.sharpdevelop.net/blogs/mattward/articles/FeatureTourEditingXml.aspx">Editing
|
|
XML</ulink>" product documentation.</para>
|
|
</section>
|
|
</appendix>
|