0
# XML Mapping Annotations
1

2
Jakarta XML Binding provides a comprehensive annotation system for controlling how Java classes map to XML schema elements, attributes, and types. These annotations enable fine-grained customization of XML binding behavior without requiring external mapping files.
3

4
## Capabilities
5

6
### Root Element Mapping
7

8
Annotations for mapping Java classes to XML root elements and defining top-level schema types.
9

10
```java { .api }
11
@Target(ElementType.TYPE)
12
@Retention(RetentionPolicy.RUNTIME)
13
public @interface XmlRootElement {
14
    String name() default "##default";
15
    String namespace() default "##default";
16
}
17

18
@Target(ElementType.TYPE)
19
@Retention(RetentionPolicy.RUNTIME)
20
public @interface XmlType {
21
    String name() default "##default";
22
    String[] propOrder() default {};
23
    String namespace() default "##default";
24
    Class<?> factoryClass() default DEFAULT.class;
25
    String factoryMethod() default "";
26
    
27
    public static final class DEFAULT {}
28
}
29
```
30

31
**Usage Examples:**
32

33
```java
34
// Simple root element
35
@XmlRootElement
36
public class Person {
37
    // Class becomes <person> element
38
}
39

40
// Custom element name and namespace
41
@XmlRootElement(name = "employee", namespace = "http://company.com/hr")
42
public class Person {
43
    // Class becomes <employee xmlns="http://company.com/hr"> element
44
}
45

46
// Type with property ordering
47
@XmlType(propOrder = {"name", "age", "address"})
48
public class Person {
49
    private String name;
50
    private int age; 
51
    private Address address;
52
    // Properties will appear in XML in specified order
53
}
54

55
// Type with factory method
56
@XmlType(factoryClass = PersonFactory.class, factoryMethod = "createPerson")
57
public class Person {
58
    // Objects created via PersonFactory.createPerson()
59
}
60
```
61

62
### Element and Attribute Mapping
63

64
Annotations for mapping Java properties to XML elements and attributes.
65

66
```java { .api }
67
@Target({ElementType.FIELD, ElementType.METHOD})
68
@Retention(RetentionPolicy.RUNTIME)
69
public @interface XmlElement {
70
    String name() default "##default";
71
    boolean nillable() default false;
72
    boolean required() default false;
73
    String namespace() default "##default";
74
    String defaultValue() default "\u0000";
75
    Class<?> type() default DEFAULT.class;
76
    
77
    public static final class DEFAULT {}
78
}
79

80
@Target({ElementType.FIELD, ElementType.METHOD})
81
@Retention(RetentionPolicy.RUNTIME)
82
public @interface XmlAttribute {
83
    String name() default "##default";
84
    boolean required() default false;
85
    String namespace() default "##default";
86
}
87

88
@Target({ElementType.FIELD, ElementType.METHOD})
89
@Retention(RetentionPolicy.RUNTIME)
90
public @interface XmlValue {
91
}
92
```
93

94
**Usage Examples:**
95

96
```java
97
public class Person {
98
    // Default element mapping
99
    @XmlElement
100
    private String name;
101
    
102
    // Custom element name
103
    @XmlElement(name = "fullName")
104
    private String name;
105
    
106
    // Required element with default value
107
    @XmlElement(required = true, defaultValue = "Unknown")
108
    private String name;
109
    
110
    // Nillable element (can be xsi:nil="true")
111
    @XmlElement(nillable = true)
112
    private String middleName;
113
    
114
    // Attribute mapping
115
    @XmlAttribute
116
    private int id;
117
    
118
    // Required attribute with custom name
119
    @XmlAttribute(name = "person-id", required = true)
120
    private int id;
121
    
122
    // Text content of element
123
    @XmlValue
124
    private String content;
125
}
126
```
127

128
### Collection and Choice Mapping
129

130
Annotations for handling collections, arrays, and choice groups in XML.
131

132
```java { .api }
133
@Target({ElementType.FIELD, ElementType.METHOD})
134
@Retention(RetentionPolicy.RUNTIME)
135
public @interface XmlElements {
136
    XmlElement[] value();
137
}
138

139
@Target({ElementType.FIELD, ElementType.METHOD})
140
@Retention(RetentionPolicy.RUNTIME)
141
public @interface XmlElementWrapper {
142
    String name() default "##default";
143
    String namespace() default "##default";
144
    boolean nillable() default false;
145
    boolean required() default false;
146
}
147

148
@Target({ElementType.FIELD, ElementType.METHOD})
149
@Retention(RetentionPolicy.RUNTIME)
150
public @interface XmlElementRef {
151
    Class<?> type() default DEFAULT.class;
152
    String namespace() default "##default";
153
    String name() default "##default";
154
    boolean required() default true;
155
    
156
    public static final class DEFAULT {}
157
}
158

159
@Target({ElementType.FIELD, ElementType.METHOD})
160
@Retention(RetentionPolicy.RUNTIME)
161
public @interface XmlElementRefs {
162
    XmlElementRef[] value();
163
}
164
```
165

166
**Usage Examples:**
167

168
```java
169
public class Library {
170
    // Collection with wrapper element
171
    @XmlElementWrapper(name = "books")
172
    @XmlElement(name = "book")
173
    private List<Book> books;
174
    // Results in: <books><book>...</book><book>...</book></books>
175
    
176
    // Choice group - different element types in same collection
177
    @XmlElements({
178
        @XmlElement(name = "book", type = Book.class),
179
        @XmlElement(name = "magazine", type = Magazine.class),
180
        @XmlElement(name = "newspaper", type = Newspaper.class)
181
    })
182
    private List<Publication> publications;
183
    
184
    // Element references via object factory
185
    @XmlElementRef
186
    private JAXBElement<String> title;
187
    
188
    // Multiple element references
189
    @XmlElementRefs({
190
        @XmlElementRef(name = "hardcover", type = JAXBElement.class),
191
        @XmlElementRef(name = "paperback", type = JAXBElement.class)
192
    })
193
    private List<JAXBElement<BookFormat>> formats;
194
}
195
```
196

197
### List and Mixed Content
198

199
Annotations for handling space-separated lists and mixed content elements.
200

201
```java { .api }
202
@Target({ElementType.FIELD, ElementType.METHOD})
203
@Retention(RetentionPolicy.RUNTIME)
204
public @interface XmlList {
205
}
206

207
@Target({ElementType.FIELD, ElementType.METHOD})
208
@Retention(RetentionPolicy.RUNTIME)
209
public @interface XmlMixed {
210
}
211

212
@Target({ElementType.FIELD, ElementType.METHOD})
213
@Retention(RetentionPolicy.RUNTIME)
214
public @interface XmlAnyElement {
215
    boolean lax() default false;
216
    Class<? extends DomHandler> value() default W3CDomHandler.class;
217
}
218

219
@Target({ElementType.FIELD, ElementType.METHOD})
220
@Retention(RetentionPolicy.RUNTIME)
221
public @interface XmlAnyAttribute {
222
}
223
```
224

225
**Usage Examples:**
226

227
```java
228
public class Document {
229
    // Space-separated list in single element
230
    @XmlList
231
    private List<String> keywords;
232
    // Results in: <keywords>java xml binding</keywords>
233
    
234
    // Mixed content (text + elements)
235
    @XmlMixed
236
    @XmlAnyElement(lax = true)
237
    private List<Object> content;
238
    // Can contain both text and element nodes
239
    
240
    // Wildcard elements
241
    @XmlAnyElement
242
    private List<Element> anyElements;
243
    
244
    // Wildcard attributes
245
    @XmlAnyAttribute
246
    private Map<QName, Object> otherAttributes;
247
}
248
```
249

250
### Identity and Reference Mapping
251

252
Annotations for XML ID/IDREF relationships and cross-references.
253

254
```java { .api }
255
@Target({ElementType.FIELD, ElementType.METHOD})
256
@Retention(RetentionPolicy.RUNTIME)
257
public @interface XmlID {
258
}
259

260
@Target({ElementType.FIELD, ElementType.METHOD})
261
@Retention(RetentionPolicy.RUNTIME)
262
public @interface XmlIDREF {
263
}
264
```
265

266
**Usage Examples:**
267

268
```java
269
public class Employee {
270
    @XmlID
271
    @XmlAttribute
272
    private String employeeId;  // Unique identifier
273
    
274
    @XmlIDREF
275
    @XmlElement
276
    private Employee manager;   // Reference to another employee
277
    
278
    @XmlIDREF
279
    @XmlElement
280
    private List<Employee> directReports;  // References to other employees
281
}
282
```
283

284
### Access Control and Ordering
285

286
Annotations for controlling property access and ordering in XML output.
287

288
```java { .api }
289
@Target({ElementType.PACKAGE, ElementType.TYPE})
290
@Retention(RetentionPolicy.RUNTIME)
291
public @interface XmlAccessorType {
292
    XmlAccessType value();
293
}
294

295
@Target({ElementType.PACKAGE, ElementType.TYPE})
296
@Retention(RetentionPolicy.RUNTIME)
297
public @interface XmlAccessorOrder {
298
    XmlAccessOrder value();
299
}
300

301
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.TYPE})
302
@Retention(RetentionPolicy.RUNTIME)  
303
public @interface XmlTransient {
304
}
305

306
public enum XmlAccessType {
307
    PROPERTY,      // Use getter/setter methods
308
    FIELD,         // Use fields directly
309
    PUBLIC_MEMBER, // Use public fields and properties
310
    NONE          // No automatic mapping
311
}
312

313
public enum XmlAccessOrder {
314
    UNDEFINED,     // Implementation-dependent order
315
    ALPHABETICAL   // Alphabetical order by property name
316
}
317
```
318

319
**Usage Examples:**
320

321
```java
322
// Control access strategy
323
@XmlAccessorType(XmlAccessType.FIELD)
324
public class Person {
325
    private String name;  // Accessed directly via field
326
    private int age;
327
    
328
    // Getters/setters not required for XML binding
329
}
330

331
@XmlAccessorType(XmlAccessType.PROPERTY)
332
public class Person {
333
    private String name;
334
    private int age;
335
    
336
    // XML binding uses getters/setters
337
    public String getName() { return name; }
338
    public void setName(String name) { this.name = name; }
339
    // ...
340
}
341

342
// Control property ordering
343
@XmlAccessorOrder(XmlAccessOrder.ALPHABETICAL)
344
public class Person {
345
    private String name;
346
    private int age;
347
    private String address;
348
    // Properties appear in XML alphabetically: address, age, name
349
}
350

351
// Exclude from XML binding
352
public class Person {
353
    @XmlElement
354
    private String name;
355
    
356
    @XmlTransient
357
    private String internalId;  // Not included in XML
358
}
359
```
360

361
### Enumeration Mapping
362

363
Annotations for controlling how Java enums map to XML enumeration values.
364

365
```java { .api }
366
@Target({ElementType.TYPE})
367
@Retention(RetentionPolicy.RUNTIME)
368
public @interface XmlEnum {
369
    Class<?> value() default String.class;
370
}
371

372
@Target({ElementType.FIELD})
373
@Retention(RetentionPolicy.RUNTIME)
374
public @interface XmlEnumValue {
375
    String value();
376
}
377
```
378

379
**Usage Examples:**
380

381
```java
382
// String-based enum
383
@XmlEnum
384
public enum Status {
385
    @XmlEnumValue("active")
386
    ACTIVE,
387
    
388
    @XmlEnumValue("inactive") 
389
    INACTIVE,
390
    
391
    @XmlEnumValue("pending")
392
    PENDING
393
}
394

395
// Integer-based enum
396
@XmlEnum(Integer.class)
397
public enum Priority {
398
    @XmlEnumValue("1")
399
    LOW,
400
    
401
    @XmlEnumValue("2")
402
    MEDIUM,
403
    
404
    @XmlEnumValue("3")
405
    HIGH
406
}
407
```
408

409
### Binary Data and MIME Types
410

411
Annotations for optimizing binary data handling and specifying MIME types.
412

413
```java { .api }
414
@Target({ElementType.FIELD, ElementType.METHOD})
415
@Retention(RetentionPolicy.RUNTIME)
416
public @interface XmlAttachmentRef {
417
}
418

419
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PACKAGE})
420
@Retention(RetentionPolicy.RUNTIME)
421
public @interface XmlInlineBinaryData {
422
}
423

424
@Target({ElementType.FIELD, ElementType.METHOD})
425
@Retention(RetentionPolicy.RUNTIME)
426
public @interface XmlMimeType {
427
    String value();
428
}
429
```
430

431
**Usage Examples:**
432

433
```java
434
public class Attachment {
435
    // Binary data as attachment reference
436
    @XmlAttachmentRef
437
    private DataHandler document;
438
    
439
    // Force inline binary data (disable XOP)
440
    @XmlInlineBinaryData
441
    private byte[] smallImage;
442
    
443
    // Specify MIME type
444
    @XmlMimeType("image/jpeg")
445
    private byte[] photo;
446
}
447
```
448

449
### Schema and Metadata Annotations
450

451
Annotations for schema generation and providing additional metadata.
452

453
```java { .api }
454
@Target({ElementType.PACKAGE})
455
@Retention(RetentionPolicy.RUNTIME)
456
public @interface XmlSchema {
457
    XmlNs[] xmlns() default {};
458
    String namespace() default "";
459
    XmlNsForm elementFormDefault() default XmlNsForm.UNSET;
460
    XmlNsForm attributeFormDefault() default XmlNsForm.UNSET;
461
    String location() default "";
462
}
463

464
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PACKAGE})
465
@Retention(RetentionPolicy.RUNTIME)
466
public @interface XmlSchemaType {
467
    String name();
468
    String namespace() default "http://www.w3.org/2001/XMLSchema";
469
    Class<?> type() default DEFAULT.class;
470
    
471
    public static final class DEFAULT {}
472
}
473

474
@Target({ElementType.PACKAGE})
475
@Retention(RetentionPolicy.RUNTIME)
476
public @interface XmlSchemaTypes {
477
    XmlSchemaType[] value();
478
}
479

480
@Target({ElementType.TYPE})
481
@Retention(RetentionPolicy.RUNTIME)
482
public @interface XmlSeeAlso {
483
    Class<?>[] value();
484
}
485

486
@Target({ElementType.TYPE})
487
@Retention(RetentionPolicy.RUNTIME)
488
public @interface XmlRegistry {
489
}
490

491
public @interface XmlNs {
492
    String prefix();
493
    String namespaceURI();
494
}
495

496
public enum XmlNsForm {
497
    UNQUALIFIED,
498
    QUALIFIED,
499
    UNSET
500
}
501
```
502

503
**Usage Examples:**
504

505
```java
506
// Package-level schema configuration
507
@XmlSchema(
508
    namespace = "http://company.com/hr",
509
    elementFormDefault = XmlNsForm.QUALIFIED,
510
    xmlns = {
511
        @XmlNs(prefix = "hr", namespaceURI = "http://company.com/hr"),
512
        @XmlNs(prefix = "common", namespaceURI = "http://company.com/common")
513
    }
514
)
515
package com.company.hr.model;
516

517
// Custom schema type mapping
518
@XmlSchemaType(name = "date", type = XMLGregorianCalendar.class)
519
private Date birthDate;
520

521
// Include related classes in context
522
@XmlSeeAlso({Manager.class, Contractor.class})
523
@XmlRootElement
524
public class Employee {
525
    // ...
526
}
527

528
// Object factory class
529
@XmlRegistry
530
public class ObjectFactory {
531
    @XmlElementDecl(namespace = "http://company.com/hr", name = "employee")
532
    public JAXBElement<Employee> createEmployee(Employee value) {
533
        return new JAXBElement<>(_Employee_QNAME, Employee.class, null, value);
534
    }
535
}
536
```
537

538
## Complete Example
539

540
Here's a comprehensive example showing multiple annotation types working together:
541

542
```java
543
@XmlRootElement(name = "company", namespace = "http://company.com/hr")
544
@XmlType(propOrder = {"name", "employees", "departments"})
545
@XmlAccessorType(XmlAccessType.FIELD)
546
public class Company {
547
    @XmlAttribute(required = true)
548
    private String id;
549
    
550
    @XmlElement(required = true)
551
    private String name;
552
    
553
    @XmlElementWrapper(name = "employees")
554
    @XmlElement(name = "employee")
555
    private List<Employee> employees;
556
    
557
    @XmlElements({
558
        @XmlElement(name = "engineering", type = EngineeringDept.class),
559
        @XmlElement(name = "sales", type = SalesDept.class),
560
        @XmlElement(name = "hr", type = HRDept.class)
561
    })
562
    private List<Department> departments;
563
    
564
    @XmlTransient
565
    private String internalCode;
566
    
567
    // Constructors, getters, setters...
568
}
569

570
@XmlType(propOrder = {"firstName", "lastName", "manager"})
571
public class Employee {
572
    @XmlID
573
    @XmlAttribute
574
    private String employeeId;
575
    
576
    @XmlElement(required = true)
577
    private String firstName;
578
    
579
    @XmlElement(required = true)  
580
    private String lastName;
581
    
582
    @XmlIDREF
583
    @XmlElement
584
    private Employee manager;
585
    
586
    @XmlElement
587
    private Status status;
588
    
589
    @XmlMimeType("image/jpeg")
590
    private byte[] photo;
591
}
592

593
@XmlEnum
594
public enum Status {
595
    @XmlEnumValue("active")
596
    ACTIVE,
597
    
598
    @XmlEnumValue("inactive")
599
    INACTIVE,
600
    
601
    @XmlEnumValue("on-leave")
602
    ON_LEAVE
603
}
604
```