diff --git a/spring-framework-reference/src/oxm.xml b/spring-framework-reference/src/oxm.xml
new file mode 100644
index 00000000000..7be0e401be5
--- /dev/null
+++ b/spring-framework-reference/src/oxm.xml
@@ -0,0 +1,680 @@
+
+
+ Marshalling XML using O/X Mappers
+
+
+ Introduction
+
+ 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.
+
+
+ Within the field of O/X mapping, a marshaller is responsible for serializing an
+ object (graph) to XML. In similar fashion, an unmarshaller 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.
+
+ Some of the benefits of using Spring for your O/X mapping needs are:
+
+ Ease of configuration
+
+ 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.
+
+
+
+ Consistent Interfaces
+
+ Spring's O/X mapping operates through two global interfaces: the
+ Marshaller and Unmarshaller 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.
+
+
+
+ Consistent Exception Hierarchy
+
+ Spring provides a conversion from exceptions from the underlying O/X mapping tool to its own exception
+ hierarchy with the XmlMappingException as the root exception. As can be expected,
+ these runtime exceptions wrap the original exception so no information is lost.
+
+
+
+
+ Marshaller and Unmarshaller
+
+ As stated in the introduction, a marshaller serializes an object to XML, and an
+ unmarshaller deserializes XML stream to an object. In this section, we will describe
+ the two Spring interfaces used for this purpose.
+
+
+ Marshaller
+
+ Spring abstracts all marshalling operations behind the
+ org.springframework.oxm.Marshaller interface, the main methods of which
+ is listed below.
+
+ The Marshaller interface has one main method, which marshals the given
+ object to a given javax.xml.transform.Result. Result is a tagging
+ interface that basically represents an XML output abstraction: concrete implementations wrap various XML
+ representations, as indicated in the table below.
+
+
+
+
+ javax.xml.transform.Result implementation
+ Wraps XML representation
+
+
+
+
+ javax.xml.transform.dom.DOMResult
+ org.w3c.dom.Node
+
+
+ javax.xml.transform.sax.SAXResult
+ org.xml.sax.ContentHandler
+
+
+ javax.xml.transform.stream.StreamResult
+
+ java.io.File,
+ java.io.OutputStream, or
+ java.io.Writer
+
+
+
+
+
+
+
+ Although the marshal method accepts a plain object as its first
+ parameter, most Marshaller 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.
+
+
+
+
+
+ Unmarshaller
+
+ Similar to the Marshaller, there is the
+ org.springframework.oxm.Unmarshaller interface.
+
+ This interface also has one method, which reads from the given
+ javax.xml.transform.Source (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.
+
+
+
+
+ javax.xml.transform.Source implementation
+ Wraps XML representation
+
+
+
+
+ javax.xml.transform.dom.DOMSource
+ org.w3c.dom.Node
+
+
+ javax.xml.transform.sax.SAXSource
+
+ org.xml.sax.InputSource, and
+ org.xml.sax.XMLReader
+
+
+
+ javax.xml.transform.stream.StreamSource
+
+ java.io.File,
+ java.io.InputStream, or
+ java.io.Reader
+
+
+
+
+
+
+
+
+ Even though there are two separate marshalling interfaces (Marshaller
+ and Unmarshaller), 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 applicationContext.xml.
+
+
+ XmlMappingException
+
+ Spring converts exceptions from the underlying O/X mapping tool to its own exception hierarchy with the
+ XmlMappingException as the root exception. As can be expected, these runtime
+ exceptions wrap the original exception so no information will be lost.
+
+
+ Additionally, the MarshallingFailureException and
+ UnmarshallingFailureException provide a distinction between marshalling and
+ unmarshalling operations, even though the underlying O/X mapping tool does not do so.
+
+
+ The O/X Mapping exception hierarchy is shown in the following figure:
+
+
+
+
+
+
+
+
+
+ O/X Mapping exception hierarchy
+
+
+
+
+
+
+
+ Using Marshaller and Unmarshaller
+
+ 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:
+
+
+
+ The application class uses this bean to store its settings. Besides a main method, the class has two
+ methods: saveSettings saves the settings bean to a file named
+ settings.xml, and loadSettings loads these settings again. A
+ main method constructs a Spring application context, and calls these two methods.
+
+ The Application requires both a marshaller
+ and unmarshaller property to be set. We can do so using the following
+ applicationContext.xml:
+
+
+
+
+
+
+
+]]>
+ 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 CastorMarshaller implements both
+ Marshaller and Unmarshaller, so we can refer
+ to the castorMarshaller bean in both the marshaller and
+ unmarshaller property of the application.
+
+
+ This sample application produces the following settings.xml file:
+
+
+]]>
+
+
+
+ XML Schema-based Configuration
+
+ Marshallers could be configured more concisely using tags from the OXM namespace.
+ To make these tags available, the appropriate schema has to be referenced first in the preamble of the XML configuration file.
+ The emboldened text in the below snippet references the OXM schema:
+
+
+
+
+]]>
+
+ Currently, the following tags are available:
+
+
+ jaxb2-marshaller
+
+
+ xmlbeans-marshaller
+
+
+ jibx-marshaller
+
+
+
+
+ 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:
+
+ ]]>
+
+
+ JAXB
+
+ The JAXB binding compiler translates a W3C XML Schema into one or more Java classes, a
+ jaxb.properties file, and possibly some resource files. JAXB also offers a
+ way to generate a schema from annotated Java classes.
+
+
+ Spring supports the JAXB 2.0 API as XML marshalling strategies, following the
+ Marshaller and Unmarshaller
+ interfaces described in . The corresponding integration
+ classes reside in the org.springframework.oxm.jaxb package.
+
+
+ Jaxb2Marshaller
+
+ The Jaxb2Marshaller class implements both the Spring
+ Marshaller and Unmarshallerinterface. It
+ requires a context path to operate, which you can set using the contextPath
+ property. The context path is a list of colon (:) separated Java package names that contain schema
+ derived classes. It also offers a classesToBeBound 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:
+
+
+
+
+
+
+ org.springframework.oxm.jaxb.Flight
+ org.springframework.oxm.jaxb.Flights
+
+
+
+
+ ...
+
+]]>
+
+ XML Schema-based Configuration
+
+ The jaxb2-marshaller tag configures a org.springframework.oxm.jaxb.Jaxb2Marshaller.
+ Here is an example:
+
+ ]]>
+
+ Alternatively, the list of classes to bind can be provided to the marshaller via the class-to-be-bound child tag:
+
+
+
+
+ ...
+
+ ]]>
+
+ Available attributes are:
+
+
+
+
+
+
+
+ Attribute
+ Description
+ Required
+
+
+
+
+ id
+ the id of the marshaller
+ no
+
+
+ contextPath
+ the JAXB Context path
+ no
+
+
+
+
+
+
+
+
+
+ Castor
+
+ 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.
+
+
+ For more information on Castor, refer to the
+ Castor web site. The Spring integration classes reside in the
+ org.springframework.oxm.castor package.
+
+
+ CastorMarshaller
+
+ As with JAXB, the CastorMarshaller implements both the
+ Marshaller and Unmarshaller interface.
+ It can be wired up as follows:
+
+
+
+
+ ...
+
+]]>
+
+
+ Mapping
+
+ 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 Castor XML Mapping.
+
+
+ The mapping can be set using the mappingLocation resource property, indicated
+ below with a classpath resource.
+
+
+
+
+
+
+]]>
+
+
+
+
+ XMLBeans
+
+ 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
+ XmlObject, and contain XML binding information in them.
+
+
+ For more information on XMLBeans, refer to the
+ XMLBeans web site . The Spring-WS integration classes reside
+ in the org.springframework.oxm.xmlbeans package.
+
+
+ XmlBeansMarshaller
+
+ The XmlBeansMarshaller
+ implements both the Marshaller
+ and Unmarshaller
+ interfaces. It can be configured as follows:
+
+
+
+
+ ...
+
+]]>
+
+
+ Note that the XmlBeansMarshaller
+ can only marshal objects of type XmlObject,
+ and not every java.lang.Object.
+
+
+
+ XML Schema-based Configuration
+
+ The xmlbeans-marshaller tag configures a org.springframework.oxm.xmlbeans.XmlBeansMarshaller.
+ Here is an example:
+
+ ]]>
+
+ Available attributes are:
+
+
+
+
+
+
+
+ Attribute
+ Description
+ Required
+
+
+
+
+ id
+ the id of the marshaller
+ no
+
+
+ options
+ the bean name of the XmlOptions that is to be used for this marshaller. Typically a
+ XmlOptionsFactoryBean definition
+ no
+
+
+
+
+
+
+
+
+
+
+
+
+ JiBX
+
+ 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.
+
+
+ For more information on JiBX, refer to the
+ JiBX web site. The Spring integration classes reside in the
+ org.springframework.oxm.jibx package.
+
+
+ JibxMarshaller
+
+ The JibxMarshaller class implements both the
+ Marshaller and Unmarshaller interface.
+ To operate, it requires the name of the class to marshall in, which you can set using the
+ targetClass property. Optionally, you can set the binding name using the
+ bindingName property. In the next sample, we bind the
+ Flights class:
+
+
+
+
+ org.springframework.oxm.jibx.Flights
+
+
+ ...
+]]>
+
+ A JibxMarshaller is configured for a single class. If you want to marshal
+ multiple classes, you have to configure multiple JibxMarshallers with
+ different targetClass property values.
+
+
+ XML Schema-based Configuration
+
+ The jibx-marshaller tag configures a org.springframework.oxm.jibx.JibxMarshaller.
+ Here is an example:
+
+ ]]>
+
+ Available attributes are:
+
+
+
+
+
+
+
+ Attribute
+ Description
+ Required
+
+
+
+
+ id
+ the id of the marshaller
+ no
+
+
+ target-class
+ the target class for this marshaller
+ yes
+
+
+ bindingName
+ the binding name used by this marshaller
+ no
+
+
+
+
+
+
+
+
+
+ XStream
+
+ XStream is a simple library to serialize objects to XML and back again. It does not require any mapping, and
+ generates clean XML.
+
+
+ For more information on XStream, refer to the
+ XStream web site. The Spring integration classes reside in the
+ org.springframework.oxm.xstream package.
+
+
+ XStreamMarshaller
+
+ The XStreamMarshaller does not require any configuration, and can be configured
+ in an application context directly. To further customize the XML, you can set an
+ alias map, which consists of string aliases mapped to classes:
+
+
+
+
+
+
+ org.springframework.oxm.xstream.Flight
+
+
+
+ ...
+
+]]>
+
+
+ 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.
+
+
+
+
+
diff --git a/spring-framework-reference/src/spring-framework-reference.xml b/spring-framework-reference/src/spring-framework-reference.xml
index b99f72b647d..8daf6c5b967 100644
--- a/spring-framework-reference/src/spring-framework-reference.xml
+++ b/spring-framework-reference/src/spring-framework-reference.xml
@@ -16,6 +16,7 @@
+
@@ -221,18 +222,18 @@
&aop-api;
&testing;
-
- Middle Tier Data Access
-
+
+ Data Access
+
This part of the reference documentation is concerned
- with the middle tier, and specifically the data access
- responsibilities of said tier.
+ with data access and the interaction between the data access
+ layer and the business or service layer.
Spring's comprehensive transaction management support is
covered in some detail, followed by thorough coverage of
- the various middle tier data access frameworks and
+ the various data access frameworks and
technologies that the Spring Framework integrates with.
@@ -248,12 +249,16 @@
+
+
+
&transaction;
&dao;
&jdbc;
&orm;
+ &oxm;
The Web