0
# Core Marshalling Interfaces
1

2
The core marshalling interfaces provide the foundation for all XML marshalling and unmarshalling operations in Spring OXM. These interfaces define generic contracts that can be implemented by various XML processing technologies.
3

4
## Core Interfaces
5

6
### Marshaller
7

8
The primary interface for converting Java objects to XML.
9

10
```java { .api }
11
public interface Marshaller {
12
    /**
13
     * Indicate whether this marshaller can marshal instances of the supplied type.
14
     * @param clazz the class that this marshaller is being asked if it can marshal
15
     * @return true if this marshaller can indeed marshal instances of the supplied class; false otherwise
16
     */
17
    boolean supports(Class<?> clazz);
18

19
    /**
20
     * Marshal the object graph with the given root into the provided Result.
21
     * @param graph the root of the object graph to marshal
22
     * @param result the result to marshal to
23
     * @throws IOException if an I/O error occurs
24
     * @throws XmlMappingException if the given object cannot be marshalled to the result
25
     */
26
    void marshal(Object graph, Result result) throws IOException, XmlMappingException;
27
}
28
```
29

30
### Unmarshaller
31

32
The primary interface for converting XML to Java objects.
33

34
```java { .api }
35
public interface Unmarshaller {
36
    /**
37
     * Indicate whether this unmarshaller can unmarshal instances of the supplied type.
38
     * @param clazz the class that this unmarshaller is being asked if it can marshal
39
     * @return true if this unmarshaller can indeed unmarshal to the supplied class; false otherwise
40
     */
41
    boolean supports(Class<?> clazz);
42

43
    /**
44
     * Unmarshal the given Source into an object graph.
45
     * @param source the source to marshal from
46
     * @return the object graph
47
     * @throws IOException if an I/O error occurs
48
     * @throws XmlMappingException if the given source cannot be mapped to an object
49
     */
50
    Object unmarshal(Source source) throws IOException, XmlMappingException;
51
}
52
```
53

54
### Generic Type Support
55

56
Extended interfaces that provide support for generic types and parameterized types.
57

58
```java { .api }
59
public interface GenericMarshaller extends Marshaller {
60
    /**
61
     * Indicates whether this marshaller can marshal instances of the supplied generic type.
62
     * @param genericType the type that this marshaller is being asked if it can marshal
63
     * @return true if this marshaller can indeed marshal instances of the supplied type; false otherwise
64
     */
65
    boolean supports(Type genericType);
66
}
67

68
public interface GenericUnmarshaller extends Unmarshaller {
69
    /**
70
     * Indicates whether this unmarshaller can unmarshal instances of the supplied generic type.
71
     * @param genericType the type that this unmarshaller is being asked if it can unmarshal
72
     * @return true if this unmarshaller can indeed unmarshal instances of the supplied type; false otherwise
73
     */
74
    boolean supports(Type genericType);
75
}
76
```
77

78
## Usage Examples
79

80
### Basic Marshalling
81

82
```java
83
import org.springframework.oxm.Marshaller;
84
import javax.xml.transform.stream.StreamResult;
85
import java.io.StringWriter;
86

87
// Assuming marshaller is configured
88
Marshaller marshaller = // ... get marshaller instance
89

90
// Check if marshaller supports the type
91
if (marshaller.supports(MyClass.class)) {
92
    MyClass object = new MyClass();
93
    StringWriter writer = new StringWriter();
94
    
95
    // Marshal to XML
96
    marshaller.marshal(object, new StreamResult(writer));
97
    String xmlResult = writer.toString();
98
}
99
```
100

101
### Basic Unmarshalling
102

103
```java
104
import org.springframework.oxm.Unmarshaller;
105
import javax.xml.transform.stream.StreamSource;
106
import java.io.StringReader;
107

108
// Assuming unmarshaller is configured
109
Unmarshaller unmarshaller = // ... get unmarshaller instance
110

111
String xmlData = "<myClass>...</myClass>";
112

113
// Check if unmarshaller supports the type
114
if (unmarshaller.supports(MyClass.class)) {
115
    StringReader reader = new StringReader(xmlData);
116
    
117
    // Unmarshal from XML
118
    MyClass result = (MyClass) unmarshaller.unmarshal(new StreamSource(reader));
119
}
120
```
121

122
### Generic Type Support
123

124
```java
125
import org.springframework.oxm.GenericMarshaller;
126
import java.lang.reflect.ParameterizedType;
127
import java.lang.reflect.Type;
128
import java.util.List;
129

130
GenericMarshaller genericMarshaller = // ... get generic marshaller
131

132
// Create a parameterized type for List<MyClass>
133
ParameterizedType listType = new ParameterizedType() {
134
    public Type[] getActualTypeArguments() { return new Type[]{MyClass.class}; }
135
    public Type getRawType() { return List.class; }
136
    public Type getOwnerType() { return null; }
137
};
138

139
// Check generic type support
140
if (genericMarshaller.supports(listType)) {
141
    List<MyClass> objectList = Arrays.asList(new MyClass(), new MyClass());
142
    // Marshal the generic collection...
143
}
144
```
145

146
## Required Imports
147

148
```java
149
import org.springframework.oxm.Marshaller;
150
import org.springframework.oxm.Unmarshaller;
151
import org.springframework.oxm.GenericMarshaller;
152
import org.springframework.oxm.GenericUnmarshaller;
153
import org.springframework.oxm.XmlMappingException;
154

155
import javax.xml.transform.Result;
156
import javax.xml.transform.Source;
157
import javax.xml.transform.stream.StreamResult;
158
import javax.xml.transform.stream.StreamSource;
159

160
import java.io.IOException;
161
import java.lang.reflect.Type;
162
```
163

164
## Error Handling
165

166
All marshalling operations can throw `XmlMappingException` or its subclasses. Common scenarios include:
167

168
- **MarshallingFailureException**: When object cannot be converted to XML
169
- **UnmarshallingFailureException**: When XML cannot be converted to object
170
- **ValidationFailureException**: When validation fails during marshalling
171
- **UncategorizedMappingException**: For other mapping-related errors
172

173
Always handle these exceptions appropriately in your application code.