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.
779 lines
40 KiB
779 lines
40 KiB
<?xml version="1.0" encoding="UTF-8"?> |
|
<chapter xml:id="oxm" |
|
xmlns="http://docbook.org/ns/docbook" version="5.0" |
|
xmlns:xl="http://www.w3.org/1999/xlink" |
|
xmlns:xi="http://www.w3.org/2001/XInclude" |
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
|
xsi:schemaLocation=" |
|
http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd |
|
http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"> |
|
<title>Marshalling XML using O/X Mappers</title> |
|
|
|
<section xml: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 xml: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 xml:id="oxm-marshaller"> |
|
<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 language="java"><![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>Result</interfacename> implementation</entry> |
|
<entry>Wraps XML representation</entry> |
|
</row> |
|
</thead> |
|
<tbody> |
|
<row> |
|
<entry><classname>DOMResult</classname></entry> |
|
<entry><interfacename>org.w3c.dom.Node</interfacename></entry> |
|
</row> |
|
<row> |
|
<entry><classname>SAXResult</classname></entry> |
|
<entry><interfacename>org.xml.sax.ContentHandler</interfacename></entry> |
|
</row> |
|
<row> |
|
<entry><interfacename>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, marked with an annotation, |
|
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 xml:id="oxm-unmarshaller"> |
|
<title>Unmarshaller</title> |
|
<para> |
|
Similar to the <interfacename>Marshaller</interfacename>, there is the |
|
<interfacename>org.springframework.oxm.Unmarshaller</interfacename> interface. |
|
<programlisting language="java"><![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>Source</interfacename> implementation</entry> |
|
<entry>Wraps XML representation</entry> |
|
</row> |
|
</thead> |
|
<tbody> |
|
<row> |
|
<entry><classname>DOMSource</classname></entry> |
|
<entry><interfacename>org.w3c.dom.Node</interfacename></entry> |
|
</row> |
|
<row> |
|
<entry><classname>SAXSource</classname></entry> |
|
<entry> |
|
<classname>org.xml.sax.InputSource</classname>, and |
|
<interfacename>org.xml.sax.XMLReader</interfacename> |
|
</entry> |
|
</row> |
|
<row> |
|
<entry><classname>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> |
|
<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> |
|
<section xml:id="oxm-xmlmappingexception"> |
|
<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> |
|
<imagedata align="center" fileref="images/oxm-exceptions.png" |
|
format="PNG" width="400"/> |
|
</imageobject> |
|
<caption>O/X Mapping exception hierarchy</caption> |
|
</mediaobject> |
|
</para> |
|
</section> |
|
</section> |
|
<section xml: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 language="java"><![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 language="java"><![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 language="xml"><![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 language="xml"><![CDATA[ |
|
<?xml version="1.0" encoding="UTF-8"?> |
|
<settings foo-enabled="false"/> |
|
]]></programlisting> |
|
</para> |
|
</section> |
|
<section xml:id="oxm-schema-based-config"> |
|
<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. |
|
Note the 'oxm' related text below: |
|
</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"><![CDATA[xmlns:oxm="http://www.springframework.org/schema/oxm"]]></emphasis> |
|
<![CDATA[xsi:schemaLocation="http://www.springframework.org/schema/beans |
|
]]><![CDATA[http://www.springframework.org/schema/beans/spring-beans.xsd |
|
]]><emphasis role="bold"><![CDATA[http://www.springframework.org/schema/oxm |
|
]]><![CDATA[http://www.springframework.org/schema/oxm/spring-oxm.xsd"]]></emphasis><![CDATA[> |
|
]]></programlisting> |
|
<para> |
|
Currently, the following tags are available: |
|
<itemizedlist> |
|
<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-castor-xsd"><literal>castor-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 language="xml"><![CDATA[<oxm:jaxb2-marshaller id="marshaller" contextPath="org.springframework.ws.samples.airline.schema"/>]]></programlisting> |
|
</section> |
|
<section xml: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 some resource files. JAXB also offers a |
|
way to generate a schema from annotated Java classes. |
|
</para> |
|
<para> |
|
Spring supports 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 xml:id="oxm-jaxb2"> |
|
<title>Jaxb2Marshaller</title> |
|
<para> |
|
The <classname>Jaxb2Marshaller</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. 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 language="xml"><![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 xml: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 language="xml"><![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 language="xml"><![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 xml: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 <link xl:href="http://castor.codehaus.org/xml-framework.html"> |
|
<citetitle>Castor web site</citetitle></link>. The Spring integration classes reside in the |
|
<package>org.springframework.oxm.castor</package> package. |
|
</para> |
|
<section xml:id="oxm-castor-marshaller"> |
|
<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 language="xml"><![CDATA[ |
|
<beans> |
|
|
|
<bean id="castorMarshaller" class="org.springframework.oxm.castor.CastorMarshaller" /> |
|
... |
|
|
|
</beans>]]></programlisting> |
|
</section> |
|
<section xml:id="oxm-castor-mapping"> |
|
<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 <link xl:href="http://castor.codehaus.org/xml-mapping.html">Castor XML Mapping</link>. |
|
</para> |
|
<para> |
|
The mapping can be set using the <property>mappingLocation</property> resource property, indicated |
|
below with a classpath resource. |
|
</para> |
|
<programlisting language="xml"><![CDATA[ |
|
<beans> |
|
<bean id="castorMarshaller" class="org.springframework.oxm.castor.CastorMarshaller" > |
|
<property name="mappingLocation" value="classpath:mapping.xml" /> |
|
</bean> |
|
</beans> |
|
]]></programlisting> |
|
<section xml:id="oxm-castor-xsd"> |
|
<title>XML Schema-based Configuration</title> |
|
<para> |
|
The <literal>castor-marshaller</literal> tag configures a |
|
<classname>org.springframework.oxm.castor.CastorMarshaller</classname>. |
|
Here is an example: |
|
</para> |
|
|
|
<programlisting language="xml"> |
|
<![CDATA[<oxm:castor-marshaller id="marshaller" mapping-location="classpath:org/springframework/oxm/castor/mapping.xml"/>]]></programlisting> |
|
|
|
<para> |
|
The marshaller instance can be configured in two ways, by specifying either the location of |
|
a mapping file (through the <property>mapping-location</property> property), or by |
|
identifying Java POJOs (through the <property>target-class</property> or |
|
<property>target-package</property> properties) for which there exist corresponding |
|
XML descriptor classes. The latter way is usually used in conjunction with XML code generation |
|
from XML schemas. |
|
</para> |
|
|
|
<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>encoding</literal> |
|
</entry> |
|
<entry>the encoding to use for unmarshalling from XML</entry> |
|
<entry>no</entry> |
|
</row> |
|
<row> |
|
<entry> |
|
<literal>target-class</literal> |
|
</entry> |
|
<entry>a Java class name for a POJO for which an XML class descriptor is available (as |
|
generated through code generation) |
|
</entry> |
|
<entry>no</entry> |
|
</row> |
|
<row> |
|
<entry> |
|
<literal>target-package</literal> |
|
</entry> |
|
<entry>a Java package name that identifies a package that contains POJOs and their |
|
corresponding Castor |
|
XML descriptor classes (as generated through code generation from XML schemas) |
|
</entry> |
|
<entry>no</entry> |
|
</row> |
|
<row> |
|
<entry> |
|
<literal>mapping-location</literal> |
|
</entry> |
|
<entry>location of a Castor XML mapping file</entry> |
|
<entry>no</entry> |
|
</row> |
|
</tbody> |
|
</tgroup> |
|
</informaltable> |
|
</para> |
|
</section> |
|
</section> |
|
</section> |
|
|
|
<section xml: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 <link xl:href="http://xmlbeans.apache.org/"> |
|
<citetitle>XMLBeans web site </citetitle></link>. The Spring-WS integration classes reside |
|
in the <package>org.springframework.oxm.xmlbeans</package> package. |
|
</para> |
|
<section xml:id="oxm-xmlbeans-marshaller"> |
|
<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 language="xml"><![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 xml: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 language="xml"><![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 xml: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 <link xl:href="http://jibx.sourceforge.net/"> |
|
<citetitle>JiBX web site</citetitle></link>. The Spring integration classes reside in the |
|
<package>org.springframework.oxm.jibx</package> package. |
|
</para> |
|
<section xml:id="oxm-jibx-marshaller"> |
|
<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 marshal 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 language="xml"><![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 xml: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 language="xml"><![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 xml: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 <link xl:href="http://xstream.codehaus.org/"> |
|
<citetitle>XStream web site</citetitle></link>. The Spring integration classes reside in the |
|
<package>org.springframework.oxm.xstream</package> package. |
|
</para> |
|
<section xml:id="oxm-xstream-marshaller"> |
|
<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 language="xml"><![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> |
|
<warning> |
|
<para> |
|
By default, XStream allows for arbitrary classes to be unmarshalled, which can result in security |
|
vulnerabilities. |
|
As such, it is recommended to set the <property>supportedClasses</property> property on the |
|
<classname>XStreamMarshaller</classname>, like so: |
|
<programlisting language="xml"><![CDATA[<bean id="xstreamMarshaller" class="org.springframework.oxm.xstream.XStreamMarshaller"> |
|
<property name="supportedClasses" value="org.springframework.oxm.xstream.Flight"/> |
|
... |
|
</bean>]]></programlisting> |
|
This will make sure that only the registered classes are eligible for unmarshalling. |
|
</para> |
|
<para> |
|
Additionally, you can register <link xl:href="http://static.springsource.org/spring/docs/current/api/org/springframework/oxm/xstream/XStreamMarshaller.html#setConverters(com.thoughtworks.xstream.converters.ConverterMatcher[])"> |
|
custom converters</link> to make sure that only your supported classes can be unmarshalled. |
|
</para> |
|
</warning> |
|
<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>
|
|
|