0
# Jakarta XML Binding API
1

2
Jakarta XML Binding (JAXB) provides an API and tools that automate the mapping between XML documents and Java objects through data binding. It offers annotation-based configuration for XML schema mapping, runtime APIs for marshalling Java objects to XML and unmarshalling XML to Java objects, and support for XML Schema validation during binding operations.
3

4
## Package Information
5

6
- **Package Name**: jakarta.xml.bind-api
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: jakarta.xml.bind
10
- **Artifact ID**: jakarta.xml.bind-api
11
- **Installation**: Add to Maven dependencies:
12

13
```xml
14
<dependency>
15
    <groupId>jakarta.xml.bind</groupId>
16
    <artifactId>jakarta.xml.bind-api</artifactId>
17
    <version>4.0.2</version>
18
</dependency>
19
```
20

21
For Gradle:
22

23
```groovy
24
implementation 'jakarta.xml.bind:jakarta.xml.bind-api:4.0.2'
25
```
26

27
## Core Imports
28

29
```java
30
import jakarta.xml.bind.JAXBContext;
31
import jakarta.xml.bind.JAXBException;
32
import jakarta.xml.bind.Marshaller;
33
import jakarta.xml.bind.Unmarshaller;
34
```
35

36
For convenience methods:
37

38
```java
39
import jakarta.xml.bind.JAXB;
40
```
41

42
For annotations:
43

44
```java
45
import jakarta.xml.bind.annotation.XmlRootElement;
46
import jakarta.xml.bind.annotation.XmlElement;
47
import jakarta.xml.bind.annotation.XmlAttribute;
48
```
49

50
For transform integration:
51

52
```java
53
import jakarta.xml.bind.util.JAXBSource;
54
import jakarta.xml.bind.util.JAXBResult;
55
import jakarta.xml.bind.util.ValidationEventCollector;
56
```
57

58
## Basic Usage
59

60
```java
61
import jakarta.xml.bind.*;
62
import jakarta.xml.bind.annotation.*;
63
import java.io.StringWriter;
64
import java.io.StringReader;
65

66
// Define a POJO with JAXB annotations
67
@XmlRootElement
68
public class Person {
69
    @XmlElement
70
    private String name;
71
    
72
    @XmlAttribute
73
    private int age;
74
    
75
    // Constructors, getters, setters...
76
    public Person() {}
77
    
78
    public Person(String name, int age) {
79
        this.name = name;
80
        this.age = age;
81
    }
82
    
83
    // Getters and setters
84
    public String getName() { return name; }
85
    public void setName(String name) { this.name = name; }
86
    public int getAge() { return age; }
87
    public void setAge(int age) { this.age = age; }
88
}
89

90
// Using JAXB for marshalling and unmarshalling
91
public class Example {
92
    public static void main(String[] args) throws JAXBException {
93
        // Create a person object
94
        Person person = new Person("Alice", 30);
95
        
96
        // Method 1: Using convenience methods
97
        StringWriter writer = new StringWriter();
98
        JAXB.marshal(person, writer);
99
        String xml = writer.toString();
100
        System.out.println(xml);
101
        
102
        Person unmarshalled = JAXB.unmarshal(new StringReader(xml), Person.class);
103
        
104
        // Method 2: Using JAXBContext (more control)
105
        JAXBContext context = JAXBContext.newInstance(Person.class);
106
        
107
        Marshaller marshaller = context.createMarshaller();
108
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
109
        marshaller.marshal(person, System.out);
110
        
111
        Unmarshaller unmarshaller = context.createUnmarshaller();
112
        Person result = (Person) unmarshaller.unmarshal(new StringReader(xml));
113
    }
114
}
115
```
116

117
## Architecture
118

119
Jakarta XML Binding is built around several key components:
120

121
- **JAXBContext**: Entry point providing binding context and factory for marshallers/unmarshallers
122
- **Marshaller**: Serializes Java objects to XML with customizable output formatting and validation
123
- **Unmarshaller**: Deserializes XML to Java objects with validation and event handling support  
124
- **Annotations**: Rich annotation system for controlling XML mapping behavior and schema generation
125
- **Type Adapters**: Pluggable conversion system for custom data type transformations
126
- **Validation Framework**: Event-driven validation with detailed error reporting and location tracking
127

128
This design enables type-safe XML data binding with compile-time code generation from XML schemas, runtime marshalling/unmarshalling with customizable formatting options, and seamless integration with Jakarta EE specifications for enterprise applications, web services, and data interchange scenarios.
129

130
## Capabilities
131

132
### Core Binding Framework
133

134
Essential JAXB operations including context creation, marshalling Java objects to XML, and unmarshalling XML to Java objects. These form the foundation of all XML binding operations.
135

136
```java { .api }
137
public abstract class JAXBContext {
138
    public static JAXBContext newInstance(String contextPath) throws JAXBException;
139
    public static JAXBContext newInstance(Class<?>... classesToBeBound) throws JAXBException;
140
    public abstract Marshaller createMarshaller() throws JAXBException;
141
    public abstract Unmarshaller createUnmarshaller() throws JAXBException;
142
}
143

144
public interface Marshaller {
145
    void marshal(Object jaxbElement, java.io.OutputStream os) throws JAXBException;
146
    void marshal(Object jaxbElement, java.io.Writer writer) throws JAXBException;
147
    void marshal(Object jaxbElement, javax.xml.transform.Result result) throws JAXBException;
148
}
149

150
public interface Unmarshaller {
151
    Object unmarshal(java.io.File f) throws JAXBException;
152
    Object unmarshal(java.io.InputStream is) throws JAXBException;
153
    Object unmarshal(javax.xml.transform.Source source) throws JAXBException;
154
}
155
```
156

157
[Core Binding](./core-binding.md)
158

159
### Convenience API
160

161
Static utility methods for simple XML binding operations without explicit context management. Ideal for straightforward use cases with minimal configuration.
162

163
```java { .api }
164
public final class JAXB {
165
    public static <T> T unmarshal(java.io.File xml, Class<T> type);
166
    public static <T> T unmarshal(java.net.URL xml, Class<T> type);
167
    public static <T> T unmarshal(String xml, Class<T> type);
168
    public static void marshal(Object jaxbObject, java.io.File xml);
169
    public static void marshal(Object jaxbObject, java.net.URL xml);
170
    public static void marshal(Object jaxbObject, java.io.OutputStream xml);
171
}
172
```
173

174
[Convenience API](./convenience-api.md)
175

176
### XML Mapping Annotations
177

178
Comprehensive annotation system for controlling how Java classes map to XML schema elements, attributes, and types. Essential for customizing XML binding behavior.
179

180
```java { .api }
181
@Target({ElementType.TYPE})
182
@Retention(RetentionPolicy.RUNTIME)
183
public @interface XmlRootElement {
184
    String name() default "##default";
185
    String namespace() default "##default";
186
}
187

188
@Target({ElementType.FIELD, ElementType.METHOD})
189
@Retention(RetentionPolicy.RUNTIME)
190
public @interface XmlElement {
191
    String name() default "##default";
192
    boolean nillable() default false;
193
    boolean required() default false;
194
    String namespace() default "##default";
195
    String defaultValue() default "\u0000";
196
    Class<?> type() default DEFAULT.class;
197
}
198

199
@Target({ElementType.FIELD, ElementType.METHOD})
200
@Retention(RetentionPolicy.RUNTIME)
201
public @interface XmlAttribute {
202
    String name() default "##default";
203
    boolean required() default false;
204
    String namespace() default "##default";
205
}
206
```
207

208
[XML Mapping Annotations](./xml-mapping-annotations.md)
209

210
### Type Adapters
211

212
Framework for custom type conversions during XML binding operations. Enables transformation of complex Java types to XML-compatible representations.
213

214
```java { .api }
215
public abstract class XmlAdapter<ValueType, BoundType> {
216
    protected XmlAdapter() {}
217
    
218
    public abstract BoundType unmarshal(ValueType v) throws Exception;
219
    public abstract ValueType marshal(BoundType v) throws Exception;
220
}
221

222
@Target({ElementType.PACKAGE, ElementType.FIELD, ElementType.METHOD, ElementType.TYPE, ElementType.PARAMETER})
223
@Retention(RetentionPolicy.RUNTIME)
224
public @interface XmlJavaTypeAdapter {
225
    Class<? extends XmlAdapter> value();
226
    Class<?> type() default DEFAULT.class;
227
}
228
```
229

230
[Type Adapters](./type-adapters.md)
231

232
### Data Type Conversion
233

234
Static utility methods for converting between Java types and XML Schema data types. Handles all standard XML Schema primitive and derived types.
235

236
```java { .api }
237
public final class DatatypeConverter {
238
    public static String parseString(String lexicalXSDString);
239
    public static java.math.BigInteger parseInteger(String lexicalXSDInteger);
240
    public static int parseInt(String lexicalXSDInt);
241
    public static long parseLong(String lexicalXSDLong);
242
    public static boolean parseBoolean(String lexicalXSDBoolean);
243
    public static java.util.Calendar parseDateTime(String lexicalXSDDateTime);
244
    public static byte[] parseBase64Binary(String lexicalXSDBase64Binary);
245
    public static byte[] parseHexBinary(String lexicalXSDHexBinary);
246
    
247
    public static String printString(String val);
248
    public static String printInteger(java.math.BigInteger val);
249
    public static String printInt(int val);
250
    public static String printLong(long val);
251
    public static String printBoolean(boolean val);
252
    public static String printDateTime(java.util.Calendar val);
253
    public static String printBase64Binary(byte[] val);
254
    public static String printHexBinary(byte[] val);
255
}
256
```
257

258
[Data Type Conversion](./data-type-conversion.md)
259

260
### Validation and Error Handling
261

262
Event-driven validation framework with detailed error reporting, location tracking, and customizable event handling for XML binding operations.
263

264
```java { .api }
265
public interface ValidationEvent {
266
    int WARNING = 0;
267
    int ERROR = 1;
268
    int FATAL_ERROR = 2;
269
    
270
    int getSeverity();
271
    String getMessage();
272
    Throwable getLinkedException();
273
    ValidationEventLocator getLocator();
274
}
275

276
public interface ValidationEventHandler {
277
    boolean handleEvent(ValidationEvent event);
278
}
279

280
public interface ValidationEventLocator {
281
    java.net.URL getURL();
282
    int getOffset();
283
    int getLineNumber();
284
    int getColumnNumber();
285
    Object getObject();
286
    org.w3c.dom.Node getNode();
287
}
288
```
289

290
[Validation and Error Handling](./validation-error-handling.md)
291

292
### Binary Attachments
293

294
Support for optimized binary data handling through MTOM (Message Transmission Optimization Mechanism) and SwA (SOAP with Attachments) for efficient large binary data processing.
295

296
```java { .api }
297
public abstract class AttachmentMarshaller {
298
    public abstract String addMtomAttachment(
299
        javax.activation.DataHandler data, 
300
        String elementNamespace, 
301
        String elementLocalName
302
    );
303
    
304
    public abstract String addMtomAttachment(
305
        byte[] data, 
306
        int offset, 
307
        int length, 
308
        String mimeType, 
309
        String elementNamespace, 
310
        String elementLocalName
311
    );
312
    
313
    public abstract String addSwaRefAttachment(javax.activation.DataHandler data);
314
    public boolean isXOPPackage();
315
}
316

317
public abstract class AttachmentUnmarshaller {
318
    public abstract javax.activation.DataHandler getAttachmentAsDataHandler(String cid);
319
    public abstract byte[] getAttachmentAsByteArray(String cid);
320
    public boolean isXOPPackage();
321
}
322
```
323

324
[Binary Attachments](./binary-attachments.md)
325

326
### Transform Integration
327

328
Utilities for seamless integration with JAXP Transform API, enabling JAXB objects to be used as Sources and Results in XSLT transformations and XML processing pipelines.
329

330
```java { .api }
331
public class JAXBSource extends javax.xml.transform.sax.SAXSource {
332
    public JAXBSource(JAXBContext context, Object contentObject) throws JAXBException;
333
    public JAXBSource(Marshaller marshaller, Object contentObject) throws JAXBException;
334
}
335

336
public class JAXBResult extends javax.xml.transform.sax.SAXResult {
337
    public JAXBResult(JAXBContext context) throws JAXBException;
338
    public JAXBResult(Unmarshaller unmarshaller) throws JAXBException;
339
    public Object getResult() throws JAXBException;
340
}
341
```
342

343
[Transform Integration](./transform-integration.md)
344

345
## Types
346

347
### Core Types
348

349
```java { .api }
350
public class JAXBElement<T> {
351
    protected final javax.xml.namespace.QName name;
352
    protected final Class<T> declaredType;
353
    protected final Class scope;
354
    protected T value;
355
    protected boolean nil = false;
356
    
357
    public JAXBElement(javax.xml.namespace.QName name, 
358
                      Class<T> declaredType, 
359
                      Class scope, 
360
                      T value);
361
    
362
    public Class<T> getDeclaredType();
363
    public javax.xml.namespace.QName getName();
364
    public T getValue();
365
    public void setValue(T t);
366
    public Class getScope();
367
    public boolean isNil();
368
    public void setNil(boolean value);
369
}
370

371
public abstract class Binder<XmlNode> {
372
    public abstract Object unmarshal(XmlNode xmlNode) throws JAXBException;
373
    public abstract <T> JAXBElement<T> unmarshal(XmlNode xmlNode, Class<T> declaredType) 
374
        throws JAXBException;
375
    public abstract void marshal(Object jaxbObject, XmlNode xmlNode) throws JAXBException;
376
    public abstract XmlNode getXMLNode(Object jaxbObject);
377
    public abstract Object getJAXBNode(XmlNode xmlNode);
378
}
379

380
public abstract class JAXBIntrospector {
381
    public abstract boolean isElement(Object object);
382
    public abstract javax.xml.namespace.QName getElementName(Object jaxbElement);
383
    public static Object getValue(Object jaxbElement);
384
}
385
```
386

387
### Exception Hierarchy
388

389
```java { .api }
390
public class JAXBException extends Exception {
391
    public JAXBException(String message);
392
    public JAXBException(String message, String errorCode);
393
    public JAXBException(Throwable exception);
394
    public JAXBException(String message, Throwable exception);
395
    public JAXBException(String message, String errorCode, Throwable exception);
396
    
397
    public String getErrorCode();
398
    public Throwable getLinkedException();
399
    public void setLinkedException(Throwable exception);
400
}
401

402
public class MarshalException extends JAXBException {
403
    public MarshalException(String message);
404
    public MarshalException(String message, String errorCode);
405
    public MarshalException(Throwable exception);
406
    public MarshalException(String message, Throwable exception);
407
    public MarshalException(String message, String errorCode, Throwable exception);
408
}
409

410
public class UnmarshalException extends JAXBException {
411
    public UnmarshalException(String message);
412
    public UnmarshalException(String message, String errorCode);
413
    public UnmarshalException(Throwable exception);
414
    public UnmarshalException(String message, Throwable exception);
415
    public UnmarshalException(String message, String errorCode, Throwable exception);
416
}
417

418
public class ValidationException extends JAXBException {
419
    public ValidationException(String message);
420
    public ValidationException(String message, String errorCode);
421
    public ValidationException(Throwable exception);
422
    public ValidationException(String message, Throwable exception);
423
    public ValidationException(String message, String errorCode, Throwable exception);
424
}
425

426
public class PropertyException extends JAXBException {
427
    public PropertyException(String message);
428
    public PropertyException(String message, String errorCode);
429
    public PropertyException(Throwable exception);
430
    public PropertyException(String message, Throwable exception);
431
    public PropertyException(String message, String errorCode, Throwable exception);
432
}
433

434
public class DataBindingException extends RuntimeException {
435
    public DataBindingException(String message, Throwable cause);
436
    public DataBindingException(Throwable cause);
437
}
438

439
public class TypeConstraintException extends RuntimeException {
440
    public TypeConstraintException(String message);
441
    public TypeConstraintException(String message, Throwable cause);
442
    public TypeConstraintException(Throwable cause);
443
}
444
```