tessl/maven-jakarta-xml-bind--jakarta-xml-bind-api

Jakarta XML Binding API that automates the mapping between XML documents and Java objects through data binding

—

Pending

Overview

Eval results

Files

XML Mapping Annotations

Name: tessl/maven-jakarta-xml-bind--jakarta-xml-bind-api
Author: tessl

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.

Capabilities

Root Element Mapping

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

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlRootElement {
    String name() default "##default";
    String namespace() default "##default";
}

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlType {
    String name() default "##default";
    String[] propOrder() default {};
    String namespace() default "##default";
    Class<?> factoryClass() default DEFAULT.class;
    String factoryMethod() default "";
    
    public static final class DEFAULT {}
}

Usage Examples:

// Simple root element
@XmlRootElement
public class Person {
    // Class becomes <person> element
}

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

// Type with property ordering
@XmlType(propOrder = {"name", "age", "address"})
public class Person {
    private String name;
    private int age; 
    private Address address;
    // Properties will appear in XML in specified order
}

// Type with factory method
@XmlType(factoryClass = PersonFactory.class, factoryMethod = "createPerson")
public class Person {
    // Objects created via PersonFactory.createPerson()
}

Element and Attribute Mapping

Annotations for mapping Java properties to XML elements and attributes.

@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlElement {
    String name() default "##default";
    boolean nillable() default false;
    boolean required() default false;
    String namespace() default "##default";
    String defaultValue() default "\u0000";
    Class<?> type() default DEFAULT.class;
    
    public static final class DEFAULT {}
}

@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlAttribute {
    String name() default "##default";
    boolean required() default false;
    String namespace() default "##default";
}

@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlValue {
}

Usage Examples:

public class Person {
    // Default element mapping
    @XmlElement
    private String name;
    
    // Custom element name
    @XmlElement(name = "fullName")
    private String name;
    
    // Required element with default value
    @XmlElement(required = true, defaultValue = "Unknown")
    private String name;
    
    // Nillable element (can be xsi:nil="true")
    @XmlElement(nillable = true)
    private String middleName;
    
    // Attribute mapping
    @XmlAttribute
    private int id;
    
    // Required attribute with custom name
    @XmlAttribute(name = "person-id", required = true)
    private int id;
    
    // Text content of element
    @XmlValue
    private String content;
}

Collection and Choice Mapping

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

@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlElements {
    XmlElement[] value();
}

@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlElementWrapper {
    String name() default "##default";
    String namespace() default "##default";
    boolean nillable() default false;
    boolean required() default false;
}

@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlElementRef {
    Class<?> type() default DEFAULT.class;
    String namespace() default "##default";
    String name() default "##default";
    boolean required() default true;
    
    public static final class DEFAULT {}
}

@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlElementRefs {
    XmlElementRef[] value();
}

Usage Examples:

public class Library {
    // Collection with wrapper element
    @XmlElementWrapper(name = "books")
    @XmlElement(name = "book")
    private List<Book> books;
    // Results in: <books><book>...</book><book>...</book></books>
    
    // Choice group - different element types in same collection
    @XmlElements({
        @XmlElement(name = "book", type = Book.class),
        @XmlElement(name = "magazine", type = Magazine.class),
        @XmlElement(name = "newspaper", type = Newspaper.class)
    })
    private List<Publication> publications;
    
    // Element references via object factory
    @XmlElementRef
    private JAXBElement<String> title;
    
    // Multiple element references
    @XmlElementRefs({
        @XmlElementRef(name = "hardcover", type = JAXBElement.class),
        @XmlElementRef(name = "paperback", type = JAXBElement.class)
    })
    private List<JAXBElement<BookFormat>> formats;
}

List and Mixed Content

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

@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlList {
}

@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlMixed {
}

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

@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlAnyAttribute {
}

Usage Examples:

public class Document {
    // Space-separated list in single element
    @XmlList
    private List<String> keywords;
    // Results in: <keywords>java xml binding</keywords>
    
    // Mixed content (text + elements)
    @XmlMixed
    @XmlAnyElement(lax = true)
    private List<Object> content;
    // Can contain both text and element nodes
    
    // Wildcard elements
    @XmlAnyElement
    private List<Element> anyElements;
    
    // Wildcard attributes
    @XmlAnyAttribute
    private Map<QName, Object> otherAttributes;
}

Identity and Reference Mapping

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

@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlID {
}

@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlIDREF {
}

Usage Examples:

public class Employee {
    @XmlID
    @XmlAttribute
    private String employeeId;  // Unique identifier
    
    @XmlIDREF
    @XmlElement
    private Employee manager;   // Reference to another employee
    
    @XmlIDREF
    @XmlElement
    private List<Employee> directReports;  // References to other employees
}

Access Control and Ordering

Annotations for controlling property access and ordering in XML output.

@Target({ElementType.PACKAGE, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlAccessorType {
    XmlAccessType value();
}

@Target({ElementType.PACKAGE, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlAccessorOrder {
    XmlAccessOrder value();
}

@Target({ElementType.FIELD, ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)  
public @interface XmlTransient {
}

public enum XmlAccessType {
    PROPERTY,      // Use getter/setter methods
    FIELD,         // Use fields directly
    PUBLIC_MEMBER, // Use public fields and properties
    NONE          // No automatic mapping
}

public enum XmlAccessOrder {
    UNDEFINED,     // Implementation-dependent order
    ALPHABETICAL   // Alphabetical order by property name
}

Usage Examples:

// Control access strategy
@XmlAccessorType(XmlAccessType.FIELD)
public class Person {
    private String name;  // Accessed directly via field
    private int age;
    
    // Getters/setters not required for XML binding
}

@XmlAccessorType(XmlAccessType.PROPERTY)
public class Person {
    private String name;
    private int age;
    
    // XML binding uses getters/setters
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    // ...
}

// Control property ordering
@XmlAccessorOrder(XmlAccessOrder.ALPHABETICAL)
public class Person {
    private String name;
    private int age;
    private String address;
    // Properties appear in XML alphabetically: address, age, name
}

// Exclude from XML binding
public class Person {
    @XmlElement
    private String name;
    
    @XmlTransient
    private String internalId;  // Not included in XML
}

Enumeration Mapping

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

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlEnum {
    Class<?> value() default String.class;
}

@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlEnumValue {
    String value();
}

Usage Examples:

// String-based enum
@XmlEnum
public enum Status {
    @XmlEnumValue("active")
    ACTIVE,
    
    @XmlEnumValue("inactive") 
    INACTIVE,
    
    @XmlEnumValue("pending")
    PENDING
}

// Integer-based enum
@XmlEnum(Integer.class)
public enum Priority {
    @XmlEnumValue("1")
    LOW,
    
    @XmlEnumValue("2")
    MEDIUM,
    
    @XmlEnumValue("3")
    HIGH
}

Binary Data and MIME Types

Annotations for optimizing binary data handling and specifying MIME types.

@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlAttachmentRef {
}

@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PACKAGE})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlInlineBinaryData {
}

@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlMimeType {
    String value();
}

Usage Examples:

public class Attachment {
    // Binary data as attachment reference
    @XmlAttachmentRef
    private DataHandler document;
    
    // Force inline binary data (disable XOP)
    @XmlInlineBinaryData
    private byte[] smallImage;
    
    // Specify MIME type
    @XmlMimeType("image/jpeg")
    private byte[] photo;
}

Schema and Metadata Annotations

Annotations for schema generation and providing additional metadata.

@Target({ElementType.PACKAGE})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlSchema {
    XmlNs[] xmlns() default {};
    String namespace() default "";
    XmlNsForm elementFormDefault() default XmlNsForm.UNSET;
    XmlNsForm attributeFormDefault() default XmlNsForm.UNSET;
    String location() default "";
}

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

@Target({ElementType.PACKAGE})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlSchemaTypes {
    XmlSchemaType[] value();
}

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlSeeAlso {
    Class<?>[] value();
}

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface XmlRegistry {
}

public @interface XmlNs {
    String prefix();
    String namespaceURI();
}

public enum XmlNsForm {
    UNQUALIFIED,
    QUALIFIED,
    UNSET
}

Usage Examples:

// Package-level schema configuration
@XmlSchema(
    namespace = "http://company.com/hr",
    elementFormDefault = XmlNsForm.QUALIFIED,
    xmlns = {
        @XmlNs(prefix = "hr", namespaceURI = "http://company.com/hr"),
        @XmlNs(prefix = "common", namespaceURI = "http://company.com/common")
    }
)
package com.company.hr.model;

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

// Include related classes in context
@XmlSeeAlso({Manager.class, Contractor.class})
@XmlRootElement
public class Employee {
    // ...
}

// Object factory class
@XmlRegistry
public class ObjectFactory {
    @XmlElementDecl(namespace = "http://company.com/hr", name = "employee")
    public JAXBElement<Employee> createEmployee(Employee value) {
        return new JAXBElement<>(_Employee_QNAME, Employee.class, null, value);
    }
}

Complete Example

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

@XmlRootElement(name = "company", namespace = "http://company.com/hr")
@XmlType(propOrder = {"name", "employees", "departments"})
@XmlAccessorType(XmlAccessType.FIELD)
public class Company {
    @XmlAttribute(required = true)
    private String id;
    
    @XmlElement(required = true)
    private String name;
    
    @XmlElementWrapper(name = "employees")
    @XmlElement(name = "employee")
    private List<Employee> employees;
    
    @XmlElements({
        @XmlElement(name = "engineering", type = EngineeringDept.class),
        @XmlElement(name = "sales", type = SalesDept.class),
        @XmlElement(name = "hr", type = HRDept.class)
    })
    private List<Department> departments;
    
    @XmlTransient
    private String internalCode;
    
    // Constructors, getters, setters...
}

@XmlType(propOrder = {"firstName", "lastName", "manager"})
public class Employee {
    @XmlID
    @XmlAttribute
    private String employeeId;
    
    @XmlElement(required = true)
    private String firstName;
    
    @XmlElement(required = true)  
    private String lastName;
    
    @XmlIDREF
    @XmlElement
    private Employee manager;
    
    @XmlElement
    private Status status;
    
    @XmlMimeType("image/jpeg")
    private byte[] photo;
}

@XmlEnum
public enum Status {
    @XmlEnumValue("active")
    ACTIVE,
    
    @XmlEnumValue("inactive")
    INACTIVE,
    
    @XmlEnumValue("on-leave")
    ON_LEAVE
}

Install with Tessl CLI

npx tessl i tessl/maven-jakarta-xml-bind--jakarta-xml-bind-api

docs

binary-attachments.md

convenience-api.md

core-binding.md

data-type-conversion.md

index.md

transform-integration.md

type-adapters.md

validation-error-handling.md

xml-mapping-annotations.md

tile.json

tessl/maven-jakarta-xml-bind--jakarta-xml-bind-api