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

Formatting.

Browse Source
This commit is contained in:
Arjen Poutsma
2007-05-14 23:09:54 +00:00
parent dbd7e6a8d2
commit 81f209cfb6
1 changed files with 125 additions and 286 deletions
Download Patch File Download Diff File Expand all files Collapse all files

411
src/docbkx/oxm.xml
View File

@@ -12,12 +12,9 @@
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.
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>
@@ -31,44 +28,37 @@
<formalpara>
<title>Consistent Interfaces</title>
<para>
Spring's O/X mapping operates through two global interfaces: the
<classname>Marshaller</classname>
and
<classname>Unmarshaller</classname>
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.
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.
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
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
<classname>org.springframework.oxm.Marshaller</classname>
interface, which is listed below.
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 {
@@ -78,52 +68,32 @@ public interface Marshaller {
void marshal(Object graph, Result result)
throws XmlMappingException, IOException;
}]]></programlisting>
The
<classname>Marshaller</classname>
interface has just one method, which marshals the given
object to a given
<classname>javax.xml.transform.Result</classname>
. Result is a tagging interface that
basically represents an XML output abstraction: concrete implementations wrap various XML
The <interface>Marshaller</interface> 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>
<classname>javax.xml.transform.Result</classname>
implementation
</entry>
<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>
<classname>org.w3c.dom.Node</classname>
</entry>
<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>
<classname>org.xml.sax.ContentHandler</classname>
</entry>
<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>javax.xml.transform.stream.StreamResult</classname>
</entry>
<entry>
<classname>java.io.File</classname>
,
<classname>java.io.OutputStream</classname>
,
or
<classname>java.io.File</classname>,
<classname>java.io.OutputStream</classname>, or
<classname>java.io.Writer</classname>
</entry>
</row>
@@ -132,17 +102,11 @@ public interface Marshaller {
</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.
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>
@@ -150,11 +114,8 @@ public interface Marshaller {
<section>
<title>Unmarshaller</title>
<para>
Similar to the
<classname>Marshaller</classname>
, there is the
<classname>org.springframework.oxm.Unmarshaller</classname>
interface.
Similar to the <interfacename>Marshaller</interfacename>, there is the
<interfacename>org.springframework.oxm.Unmarshaller</interfacename> interface.
<programlisting><![CDATA[
public interface Unmarshaller {
@@ -164,51 +125,35 @@ public interface Unmarshaller {
Object unmarshal(Source source)
throws XmlMappingException, IOException;
}]]></programlisting>
This interface also has one method, which reads from the given
<classname>javax.xml.transform.Source</classname>
(an XML input abstraction), and returns the
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>
<classname>javax.xml.transform.Source</classname>
implementation
</entry>
<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>javax.xml.transform.dom.DOMSource</classname>
</entry>
<entry>
<classname>org.w3c.dom.Node</classname>
<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>javax.xml.transform.sax.SAXSource</classname>
</entry>
<entry>
<classname>org.xml.sax.InputSource</classname>
and
<classname>org.xml.sax.XMLReader</classname>
</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.File</classname>,
<classname>java.io.InputStream</classname>, or
<classname>java.io.Reader</classname>
</entry>
</row>
@@ -218,29 +163,22 @@ public interface Unmarshaller {
</para>
</section>
<para>
Even though there are two separate marshalling interfaces (
<classname>Marshaller</classname>
and
<classname>Unmarshaller</classname>
), most implementations found in Spring-WS implement both in one class.
This means that you can wire up one marshaller class and refer to it as marshaller and unmarshaller in your
<filename>applicationContext.xml</filename>
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 as marshaller and
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
<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
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>
@@ -284,15 +222,9 @@ public class Settings {
</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.
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;
@@ -350,15 +282,9 @@ public class Application {
application.loadSettings();
}
}]]></programlisting>
The
<classname>Application</classname>
requires both a
<methodname>marshaller</methodname>
and
<methodname>unmarshaller</methodname>
property to be set. We can do so using the following
<filename>applicationContext.xml</filename>
:
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">
@@ -367,28 +293,16 @@ public class Application {
</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
<classname>Marshaller</classname>
and
<classname>Unmarshaller</classname>
, so we can refer to the
<varname>castorMarshaller</varname>
bean in both the
<varname>marshaller</varname>
and
<varname>unmarshaller</varname>
property of the application.
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:
This sample application produces the following <filename>settings.xml</filename> file:
<programlisting><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<settings foo-enabled="false"/>
@@ -398,49 +312,32 @@ public class Application {
<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.
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 as the JAXB 2.0 API as XML marshalling strategy, following the
<classname>Marshaller</classname>
and
<classname>Unmarshaller</classname>
interfaces described in
<xref linkend="oxm-marshaller-unmarshaller"/>
. The corresponding integration classes reside in the
<classname>org.springframework.oxm.jaxb</classname>
package.
<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
<classname>Marshaller</classname>
and
<classname>Unmarshaller</classname>
interface. It requires a
context path to operate, which you can set using the
<varname>contextPath</varname>
property. The
context path is a list of colon (:) separated Java package names that contain schema derived classes.
The marshaller has an additional
<varname>validating</varname>
property which defines whether to
validate invoming XML.
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 invoming 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>
.
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>
<programlisting><![CDATA[
<beans>
<bean id="jaxb1Marshaller" class="org.springframework.oxm.jaxb.Jaxb1Marshaller">
<property name="contextPath" value="org.springframework.ws.samples.airline.schema"/>
@@ -452,18 +349,14 @@ public class Application {
<section>
<title>Jaxb2Marshaller</title>
<para>
The
<classname>Jaxb2Marshaller</classname>
can be configured using the same
<varname>contextPath</varname>
property as the
<classname>Jaxb1Marshaller</classname>
. However, it also offers a
<varname>classesToBeBound</varname>
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:
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>
<programlisting><![CDATA[
<beans>
<bean id="jaxb2Marshaller" class="org.springframework.oxm.jaxb.Jaxb2Marshaller">
<property name="classesToBeBound">
@@ -487,25 +380,16 @@ public class Application {
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
<classname>org.springframework.oxm.castor</classname>
package.
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
<classname>Marshaller</classname>
and
<classname>Unmarshaller</classname>
interface. It can be wired up
as follows:
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>
@@ -520,14 +404,10 @@ public class Application {
<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>
.
to <ulink url="http://castor.org/xml-mapping.html">Castor XML Mapping</ulink>.
</para>
<para>
The mapping can be set using the
<methodname>mappingLocation</methodname>
resource property, indicated
The mapping can be set using the <property>mappingLocation</property> resource property, indicated
below with a classpath resource.
</para>
<programlisting><![CDATA[
@@ -545,21 +425,13 @@ public class Application {
<para>
XMLBeans is an XML binding tool that has full XML Schema support, and offers full XML Infoset fidelity. It
takes a different approach that most other O/X mapping frameworks, in that all classes that are
generated from an XML Schema are all derived from
<classname>XmlObject</classname>
, and contain XML binding
information in them.
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
<classname>org.springframework.oxm.xmlbeans</classname>
package.
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>
@@ -567,9 +439,9 @@ public class Application {
The
<classname>XmlBeansMarshaller</classname>
implements both the
<classname>Marshaller</classname>
<interfacename>Marshaller</interfacename>
and
<classname>Unmarshaller</classname>
<interfacename>Unmarshaller</interfacename>
interface. It can be wired up as follows:
</para>
<programlisting><![CDATA[
@@ -584,7 +456,7 @@ public class Application {
Note that the
<classname>XmlBeansMarshaller</classname>
can only marshal objects of type
<classname>XmlObject</classname>
<interfacename>XmlObject</interfacename>
, and not every
<classname>java.lang.Object</classname>
.
@@ -604,35 +476,19 @@ public class Application {
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
<varname>org.springframework.oxm.jibx</varname>
package.
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
<classname>Marshaller</classname>
and
<classname>Unmarshaller</classname>
interface. To operate, it requires the name of the class to
marshall in, which you can set using the
<varname>targetClass</varname>
property. Optionally, you can
set the binding name using the
<varname>bindingName</varname>
property. In the next sample, we refer to
the
<classname>flightsBindingFactory</classname>
defined in the previous bean definition.
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>
@@ -643,19 +499,11 @@ public class Application {
...
]]></programlisting>
<note>
<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
<varname>targetClass</varname>
es.
</para>
</note>
<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>
</section>
<section id="oxm-xstream">
@@ -665,25 +513,16 @@ public class Application {
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
<varname>org.springframework.oxm.xstream</varname>
package.
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:
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>