oxm.xml

<?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>