0
# Spring OXM (Object/XML Mapping)
1

2
Spring OXM provides a comprehensive abstraction layer for XML marshalling and unmarshalling operations in Java applications. It offers generic Marshaller and Unmarshaller interfaces that enable developers to convert Java objects to XML and vice versa using various underlying technologies such as JAXB, XStream, and other XML binding frameworks.
3

4
## Package Information
5

6
- **Package Name**: org.springframework:spring-oxm
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to Maven dependencies:
10

11
```xml
12
<dependency>
13
    <groupId>org.springframework</groupId>
14
    <artifactId>spring-oxm</artifactId>
15
    <version>6.2.8</version>
16
</dependency>
17
```
18

19
Or Gradle:
20

21
```gradle
22
implementation 'org.springframework:spring-oxm:6.2.8'
23
```
24

25
## Core Imports
26

27
```java
28
import org.springframework.oxm.Marshaller;
29
import org.springframework.oxm.Unmarshaller;
30
import org.springframework.oxm.jaxb.Jaxb2Marshaller;
31
import org.springframework.oxm.xstream.XStreamMarshaller;
32
import org.springframework.oxm.mime.MimeMarshaller;
33
import org.springframework.oxm.mime.MimeUnmarshaller;
34
import org.springframework.oxm.mime.MimeContainer;
35
```
36

37
## Basic Usage
38

39
```java
40
import org.springframework.oxm.jaxb.Jaxb2Marshaller;
41
import javax.xml.transform.stream.StreamResult;
42
import javax.xml.transform.stream.StreamSource;
43
import java.io.StringWriter;
44
import java.io.StringReader;
45

46
// Configure JAXB marshaller
47
Jaxb2Marshaller marshaller = new Jaxb2Marshaller();
48
marshaller.setClassesToBeBound(MyClass.class);
49
marshaller.afterPropertiesSet();
50

51
// Marshal object to XML
52
MyClass object = new MyClass();
53
StringWriter writer = new StringWriter();
54
marshaller.marshal(object, new StreamResult(writer));
55
String xml = writer.toString();
56

57
// Unmarshal XML to object
58
StringReader reader = new StringReader(xml);
59
MyClass unmarshalled = (MyClass) marshaller.unmarshal(new StreamSource(reader));
60
```
61

62
## Architecture
63

64
Spring OXM follows an abstraction pattern with:
65

66
- **Core Interfaces**: Generic Marshaller/Unmarshaller contracts
67
- **Technology Implementations**: JAXB, XStream concrete implementations
68
- **MIME Support**: Extensions for binary data handling via MTOM/XOP/SwA
69
- **Support Classes**: Base classes and utilities for common operations
70
- **Configuration**: Spring XML namespace support for declarative setup
71

72
## Capabilities
73

74
### Core Marshalling/Unmarshalling
75

76
Primary interfaces for XML marshalling and unmarshalling operations with support for type checking and generic types.
77

78
```java { .api }
79
public interface Marshaller {
80
    boolean supports(Class<?> clazz);
81
    void marshal(Object graph, Result result) throws IOException, XmlMappingException;
82
}
83

84
public interface Unmarshaller {
85
    boolean supports(Class<?> clazz);
86
    Object unmarshal(Source source) throws IOException, XmlMappingException;
87
}
88

89
public interface GenericMarshaller extends Marshaller {
90
    boolean supports(Type genericType);
91
}
92

93
public interface GenericUnmarshaller extends Unmarshaller {
94
    boolean supports(Type genericType);
95
}
96
```
97

98
[Core Marshalling Interfaces](./core-marshalling.md)
99

100
### JAXB Implementation
101

102
Complete JAXB 2.x implementation with full marshalling/unmarshalling capabilities, validation, schema support, and security features.
103

104
```java { .api }
105
public class Jaxb2Marshaller implements GenericMarshaller, GenericUnmarshaller, 
106
                                       MimeMarshaller, MimeUnmarshaller, 
107
                                       BeanClassLoaderAware, InitializingBean {
108
    public void setClassesToBeBound(Class<?>... classesToBeBound);
109
    public void setContextPaths(String... contextPaths);
110
    public void setSchema(Resource schemaResource);
111
    public void setValidationEventHandler(ValidationEventHandler validationEventHandler);
112
    // Additional configuration methods...
113
}
114
```
115

116
[JAXB Implementation](./jaxb-implementation.md)
117

118
### XStream Implementation
119

120
XStream-based marshaller implementation with security controls and converter configuration for alternative XML processing.
121

122
```java { .api }
123
public class XStreamMarshaller extends AbstractMarshaller implements BeanClassLoaderAware, InitializingBean {
124
    public void setSupportedClasses(Class<?>... supportedClasses);
125
    public void setTypePermissions(TypePermission... typePermissions);
126
    public void setConverters(ConverterMatcher... converters);
127
    public void setMarshallingStrategy(MarshallingStrategy marshallingStrategy);
128
    // Additional configuration methods...
129
}
130
```
131

132
[XStream Implementation](./xstream-implementation.md)
133

134
### MIME Attachment Support
135

136
Extensions for handling binary data through MIME attachments using MTOM, XOP, or SwA protocols.
137

138
```java { .api }
139
public interface MimeMarshaller extends Marshaller {
140
    void marshal(Object graph, Result result, MimeContainer mimeContainer) 
141
        throws XmlMappingException, IOException;
142
}
143

144
public interface MimeUnmarshaller extends Unmarshaller {
145
    Object unmarshal(Source source, MimeContainer mimeContainer) 
146
        throws XmlMappingException, IOException;
147
}
148

149
public interface MimeContainer {
150
    boolean isXopPackage();
151
    boolean convertToXopPackage();
152
    void addAttachment(String contentId, DataHandler dataHandler);
153
    DataHandler getAttachment(String contentId);
154
}
155
```
156

157
[MIME Attachment Support](./mime-support.md)
158

159
### Support Utilities
160

161
Base classes and utility functions for common marshalling operations and Spring integration.
162

163
```java { .api }
164
public abstract class AbstractMarshaller implements Marshaller, Unmarshaller {
165
    // Base implementation with format-specific abstract methods
166
}
167

168
public class MarshallingSource extends SAXSource {
169
    public MarshallingSource(Marshaller marshaller, Object content);
170
    public Marshaller getMarshaller();
171
    public Object getContent();
172
}
173

174
public abstract class SaxResourceUtils {
175
    public static InputSource createInputSource(Resource resource) throws IOException;
176
    public static String getSystemId(Resource resource);
177
}
178
```
179

180
[Support Utilities](./support-utilities.md)
181

182
## Exception Hierarchy
183

184
```java { .api }
185
public abstract class XmlMappingException extends NestedRuntimeException {
186
    public XmlMappingException(String msg);
187
    public XmlMappingException(String msg, Throwable cause);
188
}
189

190
public abstract class MarshallingException extends XmlMappingException {
191
    // Base for marshalling-related exceptions
192
    protected MarshallingException(String msg);
193
    protected MarshallingException(String msg, Throwable cause);
194
}
195

196
public class MarshallingFailureException extends MarshallingException {
197
    public MarshallingFailureException(String msg);
198
    public MarshallingFailureException(String msg, Throwable cause);
199
}
200

201
public class UnmarshallingFailureException extends MarshallingException {
202
    public UnmarshallingFailureException(String msg);
203
    public UnmarshallingFailureException(String msg, Throwable cause);
204
}
205

206
public class ValidationFailureException extends XmlMappingException {
207
    public ValidationFailureException(String msg);
208
    public ValidationFailureException(String msg, Throwable cause);
209
}
210

211
public class UncategorizedMappingException extends XmlMappingException {
212
    public UncategorizedMappingException(String msg, Throwable cause);
213
}
214
```