diff --git a/src/docbkx/oxm.xml b/src/docbkx/oxm.xml index 941e8bf9..9b7e1503 100644 --- a/src/docbkx/oxm.xml +++ b/src/docbkx/oxm.xml @@ -12,12 +12,9 @@ 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. + 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: @@ -31,44 +28,37 @@ 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. + 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. + 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 + 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, which is listed below. + Spring abstracts all marshalling operations behind the + org.springframework.oxm.Marshaller interface, the main methods of which + is listed below. - The - Marshaller - interface has just one 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 + 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 - + javax.xml.transform.Result implementation Wraps XML representation - - javax.xml.transform.dom.DOMResult - - - org.w3c.dom.Node - + javax.xml.transform.dom.DOMResult + org.w3c.dom.Node - - javax.xml.transform.sax.SAXResult - - - org.xml.sax.ContentHandler - + javax.xml.transform.sax.SAXResult + org.xml.sax.ContentHandler + javax.xml.transform.stream.StreamResult - javax.xml.transform.stream.StreamResult - - - java.io.File - , - java.io.OutputStream - , - or + java.io.File, + java.io.OutputStream, or java.io.Writer @@ -132,17 +102,11 @@ public interface Marshaller { - 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. + 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. @@ -150,11 +114,8 @@ public interface Marshaller {
Unmarshaller - Similar to the - Marshaller - , there is the - org.springframework.oxm.Unmarshaller - interface. + 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 + 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 - + javax.xml.transform.Source implementation Wraps XML representation + javax.xml.transform.dom.DOMSource + org.w3c.dom.Node + + + javax.xml.transform.sax.SAXSource - javax.xml.transform.dom.DOMSource - - - org.w3c.dom.Node + org.xml.sax.InputSource, and + org.xml.sax.XMLReader + javax.xml.transform.stream.StreamSource - 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.File, + java.io.InputStream, or java.io.Reader @@ -218,29 +163,22 @@ public interface Unmarshaller {
- Even though there are two separate marshalling interfaces ( - Marshaller - and - Unmarshaller - ), 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 - applicationContext.xml + 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 as marshaller and + 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 + 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 + 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. @@ -284,15 +222,9 @@ public class 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. + 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 - : + The Application requires both a marshaller + and unmarshaller property to be set. We can do so using the following + applicationContext.xml: @@ -367,28 +293,16 @@ public class Application { - ]]> 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. + 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: + This sample application produces the following settings.xml file: @@ -398,49 +312,32 @@ public class Application {
JAXB - The JAXB binding compiler translates a W3C XML Schema into one or more Java classes, a - jaxb.properties - 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 + jaxb.properties 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. Spring supports both the JAXB 1.0 as the JAXB 2.0 API as XML marshalling strategy, following the - Marshaller - and - Unmarshaller - interfaces described in - - . The corresponding integration classes reside in the - org.springframework.oxm.jaxb - package. + Marshaller and Unmarshaller + interfaces described in . The corresponding integration + classes reside in the org.springframework.oxm.jaxb package.
Jaxb1Marshaller - The - Jaxb1Marshaller - class implements both the Spring - Marshaller - and - Unmarshaller - interface. 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. - The marshaller has an additional - validating - property which defines whether to - validate invoming XML. + The Jaxb1Marshaller 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. The marshaller has an additional validating property which + defines whether to validate invoming XML. - The next sample bean configuration shows how to configure a - JaxbMarshaller - using the classes generated to - org.springframework.ws.samples.airline.schema - . + The next sample bean configuration shows how to configure a JaxbMarshaller + using the classes generated to org.springframework.ws.samples.airline.schema. - + @@ -452,18 +349,14 @@ public class Application {
Jaxb2Marshaller - The - Jaxb2Marshaller - can be configured using the same - contextPath - property as the - Jaxb1Marshaller - . However, 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: + The Jaxb2Marshaller can be configured using the same + contextPath property as the Jaxb1Marshaller. However, 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: - + @@ -487,25 +380,16 @@ public class Application { 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. + 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: + As with JAXB, the CastorMarshaller implements both the + Marshaller and Unmarshaller interface. + It can be wired up as follows: @@ -520,14 +404,10 @@ public class Application { 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 - . + to Castor XML Mapping. - The mapping can be set using the - mappingLocation - resource property, indicated + The mapping can be set using the mappingLocation resource property, indicated below with a classpath resource. 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 - XmlObject - , and contain XML binding - information in them. + 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. + 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 @@ -567,9 +439,9 @@ public class Application { The XmlBeansMarshaller implements both the - Marshaller + Marshaller and - Unmarshaller + Unmarshaller interface. It can be wired up as follows: XmlBeansMarshaller can only marshal objects of type - XmlObject + XmlObject , and not every java.lang.Object . @@ -604,35 +476,19 @@ public class Application { 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. + 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 refer to - the - flightsBindingFactory - defined in the previous bean definition. + 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: @@ -643,19 +499,11 @@ public class Application { ... ]]> - - - A - JibxMarshaller - is configured for a single class. If you want to marshal - multiple classes, you have to configure multiple - JibxMarshaller - s with - different - targetClass - es. - - + + 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. +
@@ -665,25 +513,16 @@ public class Application { 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. + 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: + 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: