Spring/spring-ws
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

SWS-603 - Drop OXM chapter from ref docs

Browse Source
This commit is contained in:
Arjen Poutsma
2010-04-08 10:52:36 +00:00
parent 8b8d3a8b18
commit 6c8ac54bb8
8 changed files with 21 additions and 787 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
src/docbkx/client.xml
View File

@@ -7,7 +7,7 @@
<title>Introduction</title>
<para>
Spring-WS provides a client-side Web service API that allows for consistent, XML-driven access to
Web services. It also caters for the use of <link linkend="oxm">marshallers and unmarshallers</link>
Web services. It also caters for the use of marshallers and unmarshallers
so that your service tier code can deal exclusively with Java objects.
</para>
<para>
@@ -284,7 +284,9 @@ public class WebServiceClient {
<classname>WebServiceTemplate</classname> class delegates the conversion of the request object
to XML to a <interfacename>Marshaller</interfacename>, and the conversion of the response
XML to an object to an <interfacename>Unmarshaller</interfacename>. (For more information
about marshalling and unmarshaller, refer to <xref linkend="oxm"/>.) By using the
about marshalling and unmarshaller, refer to
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/oxm.html">the Spring documentation</ulink>.)
By using the
marshallers, your application code can focus on the business object that is being sent or
received and not be concerned with the details of how it is represented as XML. In order to
use the marshalling functionality, you have to set a marshaller and unmarshaller with the

6
src/docbkx/index.xml
View File

@@ -59,16 +59,14 @@
to both client- and server-side WS, a chapter devoted to the specifics
of <link linkend="server">writing server-side Web services</link>,
a chapter about using Web services on
<link linkend="client">the client-side</link>, and chapters on using
<link linkend="security">WS-Security</link> and
<link linkend="oxm">Object/XML mapping</link>.
<link linkend="client">the client-side</link>, and a chapters on using
<link linkend="security">WS-Security</link>.
</para>
</partintro>
<xi:include href="common.xml"/>
<xi:include href="server.xml"/>
<xi:include href="client.xml"/>
<xi:include href="security.xml"/>
<xi:include href="oxm.xml"/>
</part>
<part id="resources">
<title>Other Resources</title>

747
src/docbkx/oxm.xml
View File

@@ -1,747 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="oxm">
<title>Marshalling XML using O/X Mappers</title>
<section id="oxm-introduction">
<title>Introduction</title>
<para>
In this chapter, we will describe Spring's Object/XML Mapping support. Object/XML Mapping, or O/X mapping
for short, is the act of converting an XML document to and from an object. This conversion process is also
known as XML Marshalling, or XML Serialization. This chapter uses these terms interchangeably.
</para>
<para>
Within the field of O/X mapping, a <emphasis>marshaller</emphasis> is responsible for serializing an
object (graph) to XML. In similar fashion, an <emphasis>unmarshaller</emphasis> deserializes the XML to an
object graph. This XML can take the form of a DOM document, an input or output stream, or a SAX handler.
</para>
<para>Some of the benefits of using Spring for your O/X mapping needs are:</para>
<formalpara>
<title>Ease of configuration</title>
<para>
Spring's bean factory makes it easy to configure marshallers, without needing to construct JAXB context,
JiBX binding factories, etc. The marshallers can be configured as any other bean in your application
context. Additionally, XML Schema-based configuration is available for a number of marshallers, making
the configuration even simpler.
</para>
</formalpara>
<formalpara>
<title>Consistent Interfaces</title>
<para>
Spring's O/X mapping operates through two global interfaces: the
<interfacename>Marshaller</interfacename> and <interfacename>Unmarshaller</interfacename> interface.
These abstractions allow you to switch O/X mapping
frameworks with relative ease, with little or no changes required on the classes that do the
marshalling. This approach has the additional benefit of making it possible to do XML marshalling with
a mix-and-match approach (e.g. some marshalling performed using JAXB, other using XMLBeans) in a
non-intrusive fashion, leveraging the strength of each technology.
</para>
</formalpara>
<formalpara>
<title>Consistent Exception Hierarchy</title>
<para>
Spring provides a conversion from exceptions from the underlying O/X mapping tool to its own exception
hierarchy with the <classname>XmlMappingException</classname> as the root exception. As can be expected,
these runtime exceptions wrap the original exception so no information is lost.
</para>
</formalpara>
</section>
<section id="oxm-marshaller-unmarshaller">
<title>Marshaller and Unmarshaller</title>
<para>
As stated in the introduction, a <emphasis>marshaller</emphasis> serializes an object to XML, and an
<emphasis>unmarshaller</emphasis> deserializes XML stream to an object. In this section, we will describe
the two Spring interfaces used for this purpose.
</para>
<section>
<title>Marshaller</title>
<para>
Spring abstracts all marshalling operations behind the
<interfacename>org.springframework.oxm.Marshaller</interfacename> interface, the main methods of which
is listed below.
<programlisting><![CDATA[
public interface Marshaller {
/**
* Marshals the object graph with the given root into the provided Result.
*/
void marshal(Object graph, Result result)
throws XmlMappingException, IOException;
}]]></programlisting>
The <interfacename>Marshaller</interfacename> interface has one main method, which marshals the given
object to a given <interfacename>javax.xml.transform.Result</interfacename>. Result is a tagging
interface that basically represents an XML output abstraction: concrete implementations wrap various XML
representations, as indicated in the table below.
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry><interfacename>javax.xml.transform.Result</interfacename> implementation</entry>
<entry>Wraps XML representation</entry>
</row>
</thead>
<tbody>
<row>
<entry><classname>javax.xml.transform.dom.DOMResult</classname></entry>
<entry><interfacename>org.w3c.dom.Node</interfacename></entry>
</row>
<row>
<entry><classname>javax.xml.transform.sax.SAXResult</classname></entry>
<entry><interfacename>org.xml.sax.ContentHandler</interfacename></entry>
</row>
<row>
<entry><interfacename>javax.xml.transform.stream.StreamResult</interfacename></entry>
<entry>
<classname>java.io.File</classname>,
<classname>java.io.OutputStream</classname>, or
<classname>java.io.Writer</classname>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<note>
<para>
Although the <methodname>marshal</methodname> method accepts a plain object as its first
parameter, most <classname>Marshaller</classname> implementations cannot handle arbitrary
objects. Instead, an object class must be mapped in a mapping file, registered with the
marshaller, or have a common base class. Refer to the further sections in this chapter to
determine how your O/X technology of choice manages this.
</para>
</note>
</para>
</section>
<section>
<title>Unmarshaller</title>
<para>
Similar to the <interfacename>Marshaller</interfacename>, there is the
<interfacename>org.springframework.oxm.Unmarshaller</interfacename> interface.
<programlisting><![CDATA[
public interface Unmarshaller {
/**
* Unmarshals the given provided Source into an object graph.
*/
Object unmarshal(Source source)
throws XmlMappingException, IOException;
}]]></programlisting>
This interface also has one method, which reads from the given
<interfacename>javax.xml.transform.Source</interfacename> (an XML input abstraction), and returns the
object read. As with Result, Source is a tagging interface that has three concrete implementations. Each
wraps a different XML representation, as indicated in the table below.
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry><interfacename>javax.xml.transform.Source</interfacename> implementation</entry>
<entry>Wraps XML representation</entry>
</row>
</thead>
<tbody>
<row>
<entry><classname>javax.xml.transform.dom.DOMSource</classname></entry>
<entry><interfacename>org.w3c.dom.Node</interfacename></entry>
</row>
<row>
<entry><classname>javax.xml.transform.sax.SAXSource</classname></entry>
<entry>
<classname>org.xml.sax.InputSource</classname>, and
<interfacename>org.xml.sax.XMLReader</interfacename>
</entry>
</row>
<row>
<entry><classname>javax.xml.transform.stream.StreamSource</classname></entry>
<entry>
<classname>java.io.File</classname>,
<classname>java.io.InputStream</classname>, or
<classname>java.io.Reader</classname>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</section>
<para>
Even though there are two separate marshalling interfaces (<interfacename>Marshaller</interfacename>
and <interfacename>Unmarshaller</interfacename>), all implementations found in Spring-WS implement both in
one class. This means that you can wire up one marshaller class and refer to it both as a marshaller and an
unmarshaller in your <filename>applicationContext.xml</filename>.
</para>
<section>
<title>XmlMappingException</title>
<para>
Spring converts exceptions from the underlying O/X mapping tool to its own exception hierarchy with the
<classname>XmlMappingException</classname> as the root exception. As can be expected, these runtime
exceptions wrap the original exception so no information will be lost.
</para>
<para>
Additionally, the <classname>MarshallingFailureException</classname> and
<classname>UnmarshallingFailureException</classname> provide a distinction between marshalling and
unmarshalling operations, even though the underlying O/X mapping tool does not do so.
</para>
<para>
The O/X Mapping exception hierarchy is shown in the following figure:
<mediaobject>
<imageobject role="fo">
<imagedata fileref="src/docbkx/resources/images/oxm-exceptions.svg"
format="SVG" align="center"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="images/oxm-exceptions.png"
format="PNG" align="center"/>
</imageobject>
<caption>
<para>
O/X Mapping exception hierarchy
</para>
</caption>
</mediaobject>
</para>
</section>
</section>
<section id="oxm-usage">
<title>Using Marshaller and Unmarshaller</title>
<para>
Spring's OXM can be used for a wide variety of situations. In the following example, we will use it to
marshal the settings of a Spring-managed application as an XML file. We will use a simple JavaBean to
represent the settings:
<programlisting><![CDATA[
public class Settings {
private boolean fooEnabled;
public boolean isFooEnabled() {
return fooEnabled;
}
public void setFooEnabled(boolean fooEnabled) {
this.fooEnabled = fooEnabled;
}
}]]></programlisting>
</para>
<para>
The application class uses this bean to store its settings. Besides a main method, the class has two
methods: <methodname>saveSettings</methodname> saves the settings bean to a file named
<filename>settings.xml</filename>, and <methodname>loadSettings</methodname> loads these settings again. A
<methodname>main</methodname> method constructs a Spring application context, and calls these two methods.
<programlisting><![CDATA[
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import javax.xml.transform.stream.StreamResult;
import javax.xml.transform.stream.StreamSource;
import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;
import org.springframework.oxm.Marshaller;
import org.springframework.oxm.Unmarshaller;
public class Application {
private static final String FILE_NAME = "settings.xml";
private Settings settings = new Settings();
private Marshaller marshaller;
private Unmarshaller unmarshaller;
public void setMarshaller(Marshaller marshaller) {
this.marshaller = marshaller;
}
public void setUnmarshaller(Unmarshaller unmarshaller) {
this.unmarshaller = unmarshaller;
}
public void saveSettings() throws IOException {
FileOutputStream os = null;
try {
os = new FileOutputStream(FILE_NAME);
this.marshaller.marshal(settings, new StreamResult(os));
} finally {
if (os != null) {
os.close();
}
}
}
public void loadSettings() throws IOException {
FileInputStream is = null;
try {
is = new FileInputStream(FILE_NAME);
this.settings = (Settings) this.unmarshaller.unmarshal(new StreamSource(is));
} finally {
if (is != null) {
is.close();
}
}
}
public static void main(String[] args) throws IOException {
ApplicationContext appContext =
new ClassPathXmlApplicationContext("applicationContext.xml");
Application application = (Application) appContext.getBean("application");
application.saveSettings();
application.loadSettings();
}
}]]></programlisting>
The <classname>Application</classname> requires both a <property>marshaller</property>
and <property>unmarshaller</property> property to be set. We can do so using the following
<filename>applicationContext.xml</filename>:
<programlisting><![CDATA[
<beans>
<bean id="application" class="Application">
<property name="marshaller" ref="castorMarshaller" />
<property name="unmarshaller" ref="castorMarshaller" />
</bean>
<bean id="castorMarshaller" class="org.springframework.oxm.castor.CastorMarshaller"/>
</beans>
]]></programlisting>
This application context uses Castor, but we could have used any of the other marshaller instances described
later in this chapter. Note that Castor does not require any further configuration by default, so the bean
definition is rather simple. Also note that the <classname>CastorMarshaller</classname> implements both
<interfacename>Marshaller</interfacename> and <interfacename>Unmarshaller</interfacename>, so we can refer
to the <varname>castorMarshaller</varname> bean in both the <property>marshaller</property> and
<property>unmarshaller</property> property of the application.
</para>
<para>
This sample application produces the following <filename>settings.xml</filename> file:
<programlisting><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<settings foo-enabled="false"/>
]]></programlisting>
</para>
</section>
<section>
<title>XML Schema-based Configuration</title>
<para>
Marshallers could be configured more concisely using tags from the OXM namespace.
To make these tags available, the appropriate schema has to be referenced first in the preamble of the XML configuration file.
The emboldened text in the below snippet references the OXM schema:
</para>
<programlisting><![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"><![CDATA[xmlns:oxm="http://www.springframework.org/schema/oxm"]]></emphasis>
<![CDATA[xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
]]><emphasis role="bold"><![CDATA[http://www.springframework.org/schema/oxm http://www.springframework.org/schema/oxm/spring-oxm-1.5.xsd"]]></emphasis><![CDATA[>
]]></programlisting>
<para>
Currently, the following tags are available:
<itemizedlist>
<listitem>
<para><link linkend="oxm-jaxb1-xsd"><literal>jaxb1-marshaller</literal></link></para>
</listitem>
<listitem>
<para><link linkend="oxm-jaxb2-xsd"><literal>jaxb2-marshaller</literal></link></para>
</listitem>
<listitem>
<para><link linkend="oxm-xmlbeans-xsd"><literal>xmlbeans-marshaller</literal></link></para>
</listitem>
<listitem>
<para><link linkend="oxm-jibx-xsd"><literal>jibx-marshaller</literal></link></para>
</listitem>
</itemizedlist>
</para>
<para>
Each tag will be explained in its respective marshaller's section. As an example though, here is how
the configuration of a JAXB2 marshaller might look like:
</para>
<programlisting><![CDATA[<oxm:jaxb2-marshaller id="marshaller" contextPath="org.springframework.ws.samples.airline.schema"/>]]></programlisting>
</section>
<section id="oxm-jaxb">
<title>JAXB</title>
<para>
The JAXB binding compiler translates a W3C XML Schema into one or more Java classes, a
<filename>jaxb.properties</filename> file, and possibly other files, depending on the specific
implementation of JAXB. Alternatively, JAXB2 offers a way to generate a schema from annotated Java classes.
</para>
<para>
Spring supports both the JAXB 1.0 and the JAXB 2.0 API as XML marshalling strategies, following the
<interfacename>Marshaller</interfacename> and <interfacename>Unmarshaller</interfacename>
interfaces described in <xref linkend="oxm-marshaller-unmarshaller"/>. The corresponding integration
classes reside in the <package>org.springframework.oxm.jaxb</package> package.
</para>
<section>
<title>Jaxb1Marshaller</title>
<para>
The <classname>Jaxb1Marshaller</classname> class implements both the Spring
<interfacename>Marshaller</interfacename> and <interfacename>Unmarshaller</interfacename>interface. It
requires a context path to operate, which you can set using the <property>contextPath</property>
property. The context path is a list of colon (:) separated Java package names that contain schema
derived classes. The marshaller has an additional <property>validating</property> property which
defines whether to validate incoming XML.
</para>
<para>
The next sample bean configuration shows how to configure a <classname>JaxbMarshaller</classname>
using the classes generated to <varname>org.springframework.ws.samples.airline.schema</varname>.
</para>
<programlisting><![CDATA[
<beans>
<bean id="jaxb1Marshaller" class="org.springframework.oxm.jaxb.Jaxb1Marshaller">
<property name="contextPath" value="org.springframework.ws.samples.airline.schema"/>
</bean>
...
</beans>]]></programlisting>
<section id="oxm-jaxb1-xsd">
<title>XML Schema-based Configuration</title>
<para>
The <literal>jaxb1-marshaller</literal> tag configures a <classname>org.springframework.oxm.jaxb.Jaxb1Marshaller</classname>.
Here is an example:
</para>
<programlisting><![CDATA[<oxm:jaxb1-marshaller id="marshaller" contextPath="org.springframework.ws.samples.airline.schema"/>]]></programlisting>
<para>
Available attributes are:
<informaltable>
<tgroup cols="3">
<colspec colwidth="1.5*"/>
<colspec colwidth="4*"/>
<colspec colwidth="1*"/>
<thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>id</literal></entry>
<entry>the id of the marshaller</entry>
<entry>no</entry>
</row>
<row>
<entry><literal>contextPath</literal></entry>
<entry>the JAXB Context path</entry>
<entry>yes</entry>
</row>
<row>
<entry><literal>validating</literal></entry>
<entry>indicates whether the incoming XML should be validated</entry>
<entry>no</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</section>
</section>
<section id="oxm-jaxb2">
<title>Jaxb2Marshaller</title>
<para>
The <classname>Jaxb2Marshaller</classname> can be configured using the same
<property>contextPath</property> property as the <classname>Jaxb1Marshaller</classname>. However, it
also offers a <property>classesToBeBound</property> property, which allows you to set an array of
classes to be supported by the marshaller. Schema validation is performed by specifying one or more
schema resource to the bean, like so:
</para>
<programlisting><![CDATA[
<beans>
<bean id="jaxb2Marshaller" class="org.springframework.oxm.jaxb.Jaxb2Marshaller">
<property name="classesToBeBound">
<list>
<value>org.springframework.oxm.jaxb.Flight</value>
<value>org.springframework.oxm.jaxb.Flights</value>
</list>
</property>
<property name="schema" value="classpath:org/springframework/oxm/schema.xsd"/>
</bean>
...
</beans>]]></programlisting>
<section id="oxm-jaxb2-xsd">
<title>XML Schema-based Configuration</title>
<para>
The <literal>jaxb2-marshaller</literal> tag configures a <classname>org.springframework.oxm.jaxb.Jaxb2Marshaller</classname>.
Here is an example:
</para>
<programlisting><![CDATA[<oxm:jaxb2-marshaller id="marshaller" contextPath="org.springframework.ws.samples.airline.schema"/>]]></programlisting>
<para>
Alternatively, the list of classes to bind can be provided to the marshaller via the <literal>class-to-be-bound</literal> child tag:
</para>
<programlisting><![CDATA[<oxm:jaxb2-marshaller id="marshaller">
<oxm:class-to-be-bound name="org.springframework.ws.samples.airline.schema.Airport"/>
<oxm:class-to-be-bound name="org.springframework.ws.samples.airline.schema.Flight"/>
...
</oxm:jaxb2-marshaller>
]]></programlisting>
<para>
Available attributes are:
<informaltable>
<tgroup cols="3">
<colspec colwidth="1.5*"/>
<colspec colwidth="4*"/>
<colspec colwidth="1*"/>
<thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>id</literal></entry>
<entry>the id of the marshaller</entry>
<entry>no</entry>
</row>
<row>
<entry><literal>contextPath</literal></entry>
<entry>the JAXB Context path</entry>
<entry>no</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</section>
</section>
</section>
<section id="oxm-castor">
<title>Castor</title>
<para>
Castor XML mapping is an open source XML binding framework. It allows you to transform the data contained in
a java object model into/from an XML document. By default, it does not require any further configuration,
though a mapping file can be used to have more control over the behavior of Castor.
</para>
<para>
For more information on Castor, refer to the <ulink url="http://castor.org/xml-framework.html">
<citetitle>Castor web site</citetitle></ulink>. The Spring integration classes reside in the
<package>org.springframework.oxm.castor</package> package.
</para>
<section>
<title>CastorMarshaller</title>
<para>
As with JAXB, the <classname>CastorMarshaller</classname> implements both the
<interfacename>Marshaller</interfacename> and <interfacename>Unmarshaller</interfacename> interface.
It can be wired up as follows:
</para>
<programlisting><![CDATA[
<beans>
<bean id="castorMarshaller" class="org.springframework.oxm.castor.CastorMarshaller" />
...
</beans>]]></programlisting>
</section>
<section>
<title>Mapping</title>
<para>
Although it is possible to rely on Castor's default marshalling behavior, it might be necessary to have
more control over it. This can be accomplished using a Castor mapping file. For more information, refer
to <ulink url="http://castor.org/xml-mapping.html">Castor XML Mapping</ulink>.
</para>
<para>
The mapping can be set using the <property>mappingLocation</property> resource property, indicated
below with a classpath resource.
</para>
<programlisting><![CDATA[
<beans>
<bean id="castorMarshaller" class="org.springframework.oxm.castor.CastorMarshaller" >
<property name="mappingLocation" value="classpath:mapping.xml" />
</bean>
</beans>
]]></programlisting>
</section>
</section>
<section id="oxm-xmlbeans">
<title>XMLBeans</title>
<para>
XMLBeans is an XML binding tool that has full XML Schema support, and offers full XML Infoset
fidelity. It takes a different approach to that of most other O/X mapping frameworks, in that
all classes that are generated from an XML Schema are all derived from
<interfacename>XmlObject</interfacename>, and contain XML binding information in them.
</para>
<para>
For more information on XMLBeans, refer to the <ulink url="http://xmlbeans.apache.org/">
<citetitle>XMLBeans web site </citetitle></ulink>. The Spring-WS integration classes reside
in the <package>org.springframework.oxm.xmlbeans</package> package.
</para>
<section>
<title>XmlBeansMarshaller</title>
<para>
The <classname>XmlBeansMarshaller</classname>
implements both the <interfacename>Marshaller</interfacename>
and <interfacename>Unmarshaller</interfacename>
interfaces. It can be configured as follows:
</para>
<programlisting><![CDATA[
<beans>
<bean id="xmlBeansMarshaller" class="org.springframework.oxm.xmlbeans.XmlBeansMarshaller" />
...
</beans>]]></programlisting>
<note>
<para>
Note that the <classname>XmlBeansMarshaller</classname>
can only marshal objects of type <interfacename>XmlObject</interfacename>,
and not every <classname>java.lang.Object</classname>.
</para>
</note>
<section id="oxm-xmlbeans-xsd">
<title>XML Schema-based Configuration</title>
<para>
The <literal>xmlbeans-marshaller</literal> tag configures a <classname>org.springframework.oxm.xmlbeans.XmlBeansMarshaller</classname>.
Here is an example:
</para>
<programlisting><![CDATA[<oxm:xmlbeans-marshaller id="marshaller"/>]]></programlisting>
<para>
Available attributes are:
<informaltable>
<tgroup cols="3">
<colspec colwidth="1.5*"/>
<colspec colwidth="4*"/>
<colspec colwidth="1*"/>
<thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>id</literal></entry>
<entry>the id of the marshaller</entry>
<entry>no</entry>
</row>
<row>
<entry><literal>options</literal></entry>
<entry>the bean name of the XmlOptions that is to be used for this marshaller. Typically a
<classname>XmlOptionsFactoryBean</classname> definition</entry>
<entry>no</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</section>
</section>
</section>
<section id="oxm-jibx">
<title>JiBX</title>
<para>
The JiBX framework offers a solution similar to that which JDO provides for ORM: a binding definition defines the
rules for how your Java objects are converted to or from XML. After preparing the binding and compiling the
classes, a JiBX binding compiler enhances the class files, and adds code to handle converting instances of
the classes from or to XML.
</para>
<para>
For more information on JiBX, refer to the <ulink url="http://jibx.sourceforge.net/">
<citetitle>JiBX web site</citetitle></ulink>. The Spring integration classes reside in the
<package>org.springframework.oxm.jibx</package> package.
</para>
<section>
<title>JibxMarshaller</title>
<para>
The <classname>JibxMarshaller</classname> class implements both the
<interfacename>Marshaller</interfacename> and <interfacename>Unmarshaller</interfacename> interface.
To operate, it requires the name of the class to marshall in, which you can set using the
<property>targetClass</property> property. Optionally, you can set the binding name using the
<property>bindingName</property> property. In the next sample, we bind the
<classname>Flights</classname> class:
</para>
<programlisting><![CDATA[
<beans>
<bean id="jibxFlightsMarshaller" class="org.springframework.oxm.jibx.JibxMarshaller">
<property name="targetClass">org.springframework.oxm.jibx.Flights</property>
</bean>
...
]]></programlisting>
<para>
A <classname>JibxMarshaller</classname> is configured for a single class. If you want to marshal
multiple classes, you have to configure multiple <classname>JibxMarshaller</classname>s with
different <property>targetClass</property> property values.
</para>
<section id="oxm-jibx-xsd">
<title>XML Schema-based Configuration</title>
<para>
The <literal>jibx-marshaller</literal> tag configures a <classname>org.springframework.oxm.jibx.JibxMarshaller</classname>.
Here is an example:
</para>
<programlisting><![CDATA[<oxm:jibx-marshaller id="marshaller" target-class="org.springframework.ws.samples.airline.schema.Flight"/>]]></programlisting>
<para>
Available attributes are:
<informaltable>
<tgroup cols="3">
<colspec colwidth="1.5*"/>
<colspec colwidth="4*"/>
<colspec colwidth="1*"/>
<thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>id</literal></entry>
<entry>the id of the marshaller</entry>
<entry>no</entry>
</row>
<row>
<entry><literal>target-class</literal></entry>
<entry>the target class for this marshaller</entry>
<entry>yes</entry>
</row>
<row>
<entry><literal>bindingName</literal></entry>
<entry>the binding name used by this marshaller</entry>
<entry>no</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</section>
</section>
</section>
<section id="oxm-xstream">
<title>XStream</title>
<para>
XStream is a simple library to serialize objects to XML and back again. It does not require any mapping, and
generates clean XML.
</para>
<para>
For more information on XStream, refer to the <ulink url="http://xstream.codehaus.org/">
<citetitle>XStream web site</citetitle></ulink>. The Spring integration classes reside in the
<package>org.springframework.oxm.xstream</package> package.
</para>
<section>
<title>XStreamMarshaller</title>
<para>
The <classname>XStreamMarshaller</classname> does not require any configuration, and can be configured
in an application context directly. To further customize the XML, you can set an
<emphasis>alias map</emphasis>, which consists of string aliases mapped to classes:
</para>
<programlisting><![CDATA[
<beans>
<bean id="xstreamMarshaller" class="org.springframework.oxm.xstream.XStreamMarshaller">
<property name="aliases">
<props>
<prop key="Flight">org.springframework.oxm.xstream.Flight</prop>
</props>
</property>
</bean>
...
</beans>]]></programlisting>
<note>
<para>
Note that XStream is an XML serialization library, not a data binding library. Therefore, it has
limited namespace support. As such, it is rather unsuitable for usage within Web services.
</para>
</note>
</section>
</section>
</chapter>

5
src/docbkx/preface.xml
View File

@@ -16,11 +16,10 @@
on this XML, and not on Java.
</para>
<para>
Spring Web Services focusses on creating these document-driven Web services.
Spring Web Services focuses on creating these document-driven Web services.
Spring Web Services facilitates contract-first SOAP service development, allowing for the creation of
flexible web services using one of the many ways to manipulate XML payloads.
Spring-WS provides a powerful <link linkend="server">message dispatching framework</link>, various <link
linkend="oxm">XML marshalling</link> techniques that can be used outside a Web service environment, a <link
Spring-WS provides a powerful <link linkend="server">message dispatching framework</link>, a <link
linkend="security">WS-Security</link> solution that integrates with your existing application security
solution, and a <link linkend="client">Client-side API</link> that follows the familiar Spring template pattern.
</para>

BIN
src/docbkx/resources/images/spring-deps.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 17 KiB

After

Width:  |  Height:  |  Size: 17 KiB

23
src/docbkx/server.xml
View File

@@ -24,7 +24,7 @@
Spring-WS's XML handling is extremely flexible. An endpoint can choose from
a large amount of XML handling libraries supported by Spring-WS, including the DOM family (W3C DOM, JDOM,
dom4j, and XOM), SAX or StAX for faster performance, XPath to extract information from the message, or even
<link linkend="oxm">marshalling techniques</link> (JAXB, Castor, XMLBeans, JiBX, or XStream) to convert
marshalling techniques (JAXB, Castor, XMLBeans, JiBX, or XStream) to convert
the XML to objects and vice-versa.
</para>
</section>
@@ -314,18 +314,6 @@
the dispatcher servlet does not load the default adapters, and is unable to handle standard Spring-MVC
<interfacename>Controllers</interfacename>. Therefore, we add the
<classname>SimpleControllerHandlerAdapter</classname> at the end.
<footnote>
<para>
By default, the Spring MVC <classname>DispatcherServlet</classname> configures the following
handler adapters in version 2.5:
<itemizedlist>
<listitem><para><classname>org.springframework.web.servlet.mvc.HttpRequestHandlerAdapter</classname></para></listitem>
<listitem><para><classname>org.springframework.web.servlet.mvc.SimpleControllerHandlerAdapter</classname></para></listitem>
<listitem><para><classname>org.springframework.web.servlet.mvc.throwaway.ThrowawayControllerHandlerAdapter</classname></para></listitem>
<listitem><para><classname>org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter</classname></para></listitem>
</itemizedlist>
</para>
</footnote>
</para>
<para>
In a similar fashion, you can wire up a <classname>WsdlDefinitionHandlerAdapter</classname> to make sure
@@ -669,7 +657,7 @@ public class SampleEndpoint extends AbstractDomPayloadEndpoint {
Rather than handling XML directly using DOM, you can use marshalling to convert the payload of the XML
message into a Java Object. Spring Web Services offers the
<classname>AbstractMarshallingPayloadEndpoint</classname> for this purpose, which is built on the
marshalling abstraction described in <xref linkend="oxm"/>. The
Spring's OXM package. The
<classname>AbstractMarshallingPayloadEndpoint</classname> has two properties:
<property>marshaller</property> and <property>unmarshaller</property>, in which you can inject in the
constructor or by setters.
@@ -721,7 +709,9 @@ public class MarshallingOrderEndpoint extends AbstractMarshallingPayloadEndpoint
]]><lineannotation>&lt;!-- Other beans, such as the endpoint mapping --&gt;</lineannotation><![CDATA[
</beans>]]></programlisting>
<para>
In this sample, we configure a <link linkend="oxm-jaxb2">Jaxb2Marshaller</link> for the
In this sample, we configure a
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/oxm.html#oxm-jaxb2">Jaxb2Marshaller</ulink>
for the
<classname>OrderRequest</classname> and <classname>Order</classname> classes, and inject that
marshaller together with the
<classname>DefaultOrderService</classname> into our endpoint. This business service is not shown, but
@@ -756,7 +746,8 @@ public class MarshallingOrderEndpoint extends AbstractMarshallingPayloadEndpoint
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>]]></programlisting>
<para>
Instead of JAXB 2, we could have used any of the other marshallers described in <xref linkend="oxm"/>.
Instead of JAXB 2, we could have used <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/oxm.html">any Spring OXM marshallers</ulink>.
The only thing that would change in the above example is the configuration of the
<literal>marshaller</literal> bean.
</para>

2
src/docbkx/tutorial.xml
View File

@@ -620,7 +620,7 @@ public class HolidayEndpoint extends AbstractJDomPayloadEndpoint {
</programlistingco>
<para>
Using JDOM is just one of the options to handle the XML: other options include DOM, dom4j, XOM,
SAX, and StAX, but also <link linkend="oxm">marshalling techniques</link> like JAXB, Castor, XMLBeans,
SAX, and StAX, but also marshalling techniques like JAXB, Castor, XMLBeans,
JiBX, and XStream. We chose JDOM because it gives us access to the raw XML, and because it
is based on classes (not interfaces and factory methods as with W3C DOM and dom4j), which makes the
code less verbose. We use XPath because it is less fragile than marshalling technologies: we don't

19
src/docbkx/what-is-spring-ws.xml
View File

@@ -79,9 +79,8 @@
<section>
<title>Runtime environment</title>
<para>
Spring Web Services runs within a standard Java 1.3 Runtime Environment. It also supports Java 5.0,
although the Java types which are specific to this release are packaged in a separate modules with the
suffix "tiger" in their JAR filename. Note that the security module also requires Java 5.
Spring Web Services requires a standard Java 1.5 Runtime Environment. Java 1.6 is also supported.
Spring-WS also requires Spring 3.0 or higher.
</para>
<para>
Spring-WS consists of a number of modules, which are described in the remainder of this section.
@@ -96,7 +95,7 @@
</listitem>
<listitem>
<para>
The Core package (<filename>spring-ws-core.jar</filename> and <filename>spring-ws-core-tiger.jar</filename>)
The Core package (<filename>spring-ws-core.jar</filename>)
is the central part of the Spring's Web services functionality.
It provides the central <link linkend="web-service-messages">
<classname>WebServiceMessage</classname></link> and <link linkend="soap-message">
@@ -110,22 +109,14 @@
The <link linkend="security">Security</link> package (<filename>spring-ws-security.jar</filename>)
provides a WS-Security implementation that integrates
with the core Web service package. It allows you to add principal tokens, sign, and decrypt and encrypt SOAP
messages. Addtionally, it allows you to leverage your existing Acegi security implementation for
messages. Additionally, it allows you to leverage your existing Spring Security security implementation for
authentication and authorization.
</para>
</listitem>
<listitem>
<para>
The <link linkend="oxm">OXM</link> package (<filename>spring-oxm.jar</filename> and
<filename>spring-oxm-tiger.jar</filename>) provides integration for popular XML marshalling APIs, including
JAXB 1 and 2. Using the OXM package means that you benefit from a unified exception hierarchy, and can wire
up your favorite XML marshalling technology easily.
</para>
</listitem>
</itemizedlist>
<para>
The following figure illustrates the Spring-WS modules and the dependencies between them. Arrows indicate
dependencies, i.e. Spring-WS Core depends on Spring-XML and Spring-OXM.
dependencies, i.e. Spring-WS Core depends on Spring-XML and the OXM module found in Spring 3.
<mediaobject>
<imageobject role="fo">
<imagedata fileref="src/docbkx/resources/images/spring-deps.png"