0
# XML Binding
1

2
JAXB API for binding Java objects to XML representations with annotation-driven marshalling and unmarshalling support.
3

4
## Core JAXB Context and Operations
5

6
### JAXBContext
7

8
```java { .api }
9
public abstract class JAXBContext {
10
    public static JAXBContext newInstance(String contextPath) throws JAXBException;
11
    public static JAXBContext newInstance(String contextPath, ClassLoader classLoader) throws JAXBException;
12
    public static JAXBContext newInstance(Class... classesToBeBound) throws JAXBException;
13
    public static JAXBContext newInstance(Class[] classesToBeBound, Map<String, ?> properties) throws JAXBException;
14
    
15
    public abstract Marshaller createMarshaller() throws JAXBException;
16
    public abstract Unmarshaller createUnmarshaller() throws JAXBException;
17
    public abstract Validator createValidator() throws JAXBException;
18
    public <T> Binder<T> createBinder(Class<T> domType);
19
    public JAXBIntrospector createJAXBIntrospector();
20
    public void generateSchema(SchemaOutputResolver outputResolver) throws IOException;
21
}
22
```
23

24
### Marshaller Interface
25

26
```java { .api }
27
public interface Marshaller {
28
    void marshal(Object jaxbElement, Result result) throws JAXBException;
29
    void marshal(Object jaxbElement, OutputStream os) throws JAXBException;
30
    void marshal(Object jaxbElement, File output) throws JAXBException;
31
    void marshal(Object jaxbElement, Writer writer) throws JAXBException;
32
    void marshal(Object jaxbElement, ContentHandler handler) throws JAXBException;
33
    void marshal(Object jaxbElement, Node node) throws JAXBException;
34
    void marshal(Object jaxbElement, XMLStreamWriter writer) throws JAXBException;
35
    void marshal(Object jaxbElement, XMLEventWriter writer) throws JAXBException;
36
    
37
    Node getNode(Object contentTree) throws JAXBException;
38
    
39
    void setProperty(String name, Object value) throws PropertyException;
40
    Object getProperty(String name) throws PropertyException;
41
    
42
    void setEventHandler(ValidationEventHandler handler) throws JAXBException;
43
    ValidationEventHandler getEventHandler() throws JAXBException;
44
    
45
    void setAdapter(XmlAdapter adapter);
46
    void setAdapter(Class<A> type, A adapter);
47
    <A extends XmlAdapter> A getAdapter(Class<A> type);
48
    
49
    void setAttachmentMarshaller(AttachmentMarshaller am);
50
    AttachmentMarshaller getAttachmentMarshaller();
51
    
52
    void setSchema(Schema schema);
53
    Schema getSchema();
54
    
55
    void setListener(Marshaller.Listener listener);
56
    Marshaller.Listener getListener();
57
    
58
    String JAXB_ENCODING = "jaxb.encoding";
59
    String JAXB_FORMATTED_OUTPUT = "jaxb.formatted.output";
60
    String JAXB_SCHEMA_LOCATION = "jaxb.schemaLocation";
61
    String JAXB_NO_NAMESPACE_SCHEMA_LOCATION = "jaxb.noNamespaceSchemaLocation";
62
    String JAXB_FRAGMENT = "jaxb.fragment";
63
}
64
```
65

66
### Unmarshaller Interface
67

68
```java { .api }
69
public interface Unmarshaller {
70
    Object unmarshal(File f) throws JAXBException;
71
    Object unmarshal(InputStream is) throws JAXBException;
72
    Object unmarshal(Reader reader) throws JAXBException;
73
    Object unmarshal(URL url) throws JAXBException;
74
    Object unmarshal(InputSource source) throws JAXBException;
75
    Object unmarshal(Node node) throws JAXBException;
76
    <T> JAXBElement<T> unmarshal(Node node, Class<T> expectedType) throws JAXBException;
77
    Object unmarshal(Source source) throws JAXBException;
78
    <T> JAXBElement<T> unmarshal(Source source, Class<T> expectedType) throws JAXBException;
79
    Object unmarshal(XMLStreamReader reader) throws JAXBException;
80
    <T> JAXBElement<T> unmarshal(XMLStreamReader reader, Class<T> expectedType) throws JAXBException;
81
    Object unmarshal(XMLEventReader reader) throws JAXBException;
82
    <T> JAXBElement<T> unmarshal(XMLEventReader reader, Class<T> expectedType) throws JAXBException;
83
    
84
    UnmarshallerHandler getUnmarshallerHandler();
85
    
86
    void setValidating(boolean validating) throws JAXBException;
87
    boolean isValidating() throws JAXBException;
88
    
89
    void setEventHandler(ValidationEventHandler handler) throws JAXBException;
90
    ValidationEventHandler getEventHandler() throws JAXBException;
91
    
92
    void setProperty(String name, Object value) throws PropertyException;
93
    Object getProperty(String name) throws PropertyException;
94
    
95
    void setSchema(Schema schema);
96
    Schema getSchema();
97
    
98
    void setAdapter(XmlAdapter adapter);
99
    void setAdapter(Class<A> type, A adapter);
100
    <A extends XmlAdapter> A getAdapter(Class<A> type);
101
    
102
    void setAttachmentUnmarshaller(AttachmentUnmarshaller au);
103
    AttachmentUnmarshaller getAttachmentUnmarshaller();
104
    
105
    void setListener(Unmarshaller.Listener listener);
106
    Unmarshaller.Listener getListener();
107
}
108
```
109

110
## JAXB Annotations
111

112
### Class-Level Annotations
113

114
```java { .api }
115
@Target({ElementType.TYPE, ElementType.PACKAGE})
116
@Retention(RetentionPolicy.RUNTIME)
117
public @interface XmlRootElement {
118
    String name() default "##default";
119
    String namespace() default "##default";
120
}
121

122
@Target({ElementType.TYPE})
123
@Retention(RetentionPolicy.RUNTIME)
124
public @interface XmlType {
125
    String name() default "##default";
126
    String[] propOrder() default {""};
127
    String namespace() default "##default";
128
    Class factoryClass() default DEFAULT.class;
129
    String factoryMethod() default "";
130
}
131

132
@Target({ElementType.TYPE})
133
@Retention(RetentionPolicy.RUNTIME)
134
public @interface XmlAccessorType {
135
    XmlAccessType value() default XmlAccessType.PUBLIC_MEMBER;
136
}
137

138
public enum XmlAccessType {
139
    PROPERTY, FIELD, PUBLIC_MEMBER, NONE
140
}
141
```
142

143
### Field and Property Annotations
144

145
```java { .api }
146
@Target({ElementType.FIELD, ElementType.METHOD})
147
@Retention(RetentionPolicy.RUNTIME)
148
public @interface XmlElement {
149
    String name() default "##default";
150
    boolean nillable() default false;
151
    boolean required() default false;
152
    String namespace() default "##default";
153
    String defaultValue() default "\u0000";
154
    Class type() default DEFAULT.class;
155
}
156

157
@Target({ElementType.FIELD, ElementType.METHOD})
158
@Retention(RetentionPolicy.RUNTIME)
159
public @interface XmlAttribute {
160
    String name() default "##default";
161
    boolean required() default false;
162
    String namespace() default "##default";
163
}
164

165
@Target({ElementType.FIELD, ElementType.METHOD})
166
@Retention(RetentionPolicy.RUNTIME)
167
public @interface XmlElementRef {
168
    String name() default "##default";
169
    String namespace() default "##default";
170
    Class type() default DEFAULT.class;
171
    boolean required() default true;
172
}
173

174
@Target({ElementType.FIELD, ElementType.METHOD})
175
@Retention(RetentionPolicy.RUNTIME)
176
public @interface XmlElementRefs {
177
    XmlElementRef[] value();
178
}
179

180
@Target({ElementType.FIELD, ElementType.METHOD})
181
@Retention(RetentionPolicy.RUNTIME)
182
public @interface XmlElementWrapper {
183
    String name() default "##default";
184
    String namespace() default "##default";
185
    boolean nillable() default false;
186
    boolean required() default false;
187
}
188
```
189

190
### Value and Content Annotations
191

192
```java { .api }
193
@Target({ElementType.FIELD, ElementType.METHOD})
194
@Retention(RetentionPolicy.RUNTIME)
195
public @interface XmlValue {
196
}
197

198
@Target({ElementType.FIELD, ElementType.METHOD})
199
@Retention(RetentionPolicy.RUNTIME)
200
public @interface XmlTransient {
201
}
202

203
@Target({ElementType.FIELD, ElementType.METHOD})
204
@Retention(RetentionPolicy.RUNTIME)
205
public @interface XmlAnyElement {
206
    boolean lax() default false;
207
    Class<? extends DomHandler> value() default W3CDomHandler.class;
208
}
209

210
@Target({ElementType.FIELD, ElementType.METHOD})
211
@Retention(RetentionPolicy.RUNTIME)
212
public @interface XmlAnyAttribute {
213
}
214
```
215

216
## Schema Generation and Validation
217

218
### Schema Generation
219

220
```java { .api }
221
public abstract class SchemaOutputResolver {
222
    public abstract Result createOutput(String namespaceUri, String suggestedFileName) throws IOException;
223
}
224

225
public interface SchemaGenerator {
226
    void generateSchema() throws IOException;
227
}
228
```
229

230
### Validation Events
231

232
```java { .api }
233
public interface ValidationEventHandler {
234
    boolean handleEvent(ValidationEvent event);
235
}
236

237
public interface ValidationEvent {
238
    int getSeverity();
239
    String getMessage();
240
    ValidationEventLocator getLocator();
241
    Throwable getLinkedException();
242
    
243
    int WARNING = 0;
244
    int ERROR = 1;
245
    int FATAL_ERROR = 2;
246
}
247

248
public interface ValidationEventLocator {
249
    URL getURL();
250
    int getOffset();
251
    int getLineNumber();
252
    int getColumnNumber();
253
    Object getObject();
254
    Node getNode();
255
}
256
```
257

258
## XML Adapters
259

260
### XmlAdapter
261

262
```java { .api }
263
public abstract class XmlAdapter<ValueType, BoundType> {
264
    protected XmlAdapter();
265
    public abstract BoundType unmarshal(ValueType v) throws Exception;
266
    public abstract ValueType marshal(BoundType v) throws Exception;
267
}
268

269
@Target({ElementType.PACKAGE, ElementType.FIELD, ElementType.METHOD, ElementType.TYPE, ElementType.PARAMETER})
270
@Retention(RetentionPolicy.RUNTIME)
271
public @interface XmlJavaTypeAdapter {
272
    Class<? extends XmlAdapter> value();
273
    Class type() default DEFAULT.class;
274
}
275

276
@Target({ElementType.PACKAGE})
277
@Retention(RetentionPolicy.RUNTIME)
278
public @interface XmlJavaTypeAdapters {
279
    XmlJavaTypeAdapter[] value();
280
}
281
```
282

283
## Usage Examples
284

285
### Basic Object Binding
286

287
```java
288
@XmlRootElement
289
@XmlType(propOrder = {"id", "name", "email"})
290
public class Person {
291
    @XmlElement(required = true)
292
    private Long id;
293
    
294
    @XmlElement
295
    private String name;
296
    
297
    @XmlAttribute
298
    private String email;
299
    
300
    // getters and setters
301
}
302

303
// Marshal to XML
304
JAXBContext context = JAXBContext.newInstance(Person.class);
305
Marshaller marshaller = context.createMarshaller();
306
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
307

308
Person person = new Person();
309
person.setId(1L);
310
person.setName("John Doe");
311
person.setEmail("john@example.com");
312

313
marshaller.marshal(person, System.out);
314

315
// Unmarshal from XML
316
Unmarshaller unmarshaller = context.createUnmarshaller();
317
Person person = (Person) unmarshaller.unmarshal(new File("person.xml"));
318
```
319

320
### Custom Adapter Example
321

322
```java
323
public class DateAdapter extends XmlAdapter<String, Date> {
324
    
325
    private static final String PATTERN = "yyyy-MM-dd";
326
    
327
    @Override
328
    public Date unmarshal(String dateString) throws Exception {
329
        return new SimpleDateFormat(PATTERN).parse(dateString);
330
    }
331
    
332
    @Override
333
    public String marshal(Date date) throws Exception {
334
        return new SimpleDateFormat(PATTERN).format(date);
335
    }
336
}
337

338
// Usage in class
339
@XmlJavaTypeAdapter(DateAdapter.class)
340
private Date birthDate;
341
```