or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

binary-attachments.mdconvenience-api.mdcore-binding.mddata-type-conversion.mdindex.mdtransform-integration.mdtype-adapters.mdvalidation-error-handling.mdxml-mapping-annotations.md
tile.json

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/jakarta.xml.bind/jakarta.xml.bind-api@4.0.x

To install, run

npx @tessl/cli install tessl/maven-jakarta-xml-bind--jakarta-xml-bind-api@4.0.0

index.mddocs/

Jakarta XML Binding API

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.

Package Information

  • Package Name: jakarta.xml.bind-api
  • Package Type: maven
  • Language: Java
  • Group ID: jakarta.xml.bind
  • Artifact ID: jakarta.xml.bind-api
  • Installation: Add to Maven dependencies:
<dependency>
    <groupId>jakarta.xml.bind</groupId>
    <artifactId>jakarta.xml.bind-api</artifactId>
    <version>4.0.2</version>
</dependency>

For Gradle:

implementation 'jakarta.xml.bind:jakarta.xml.bind-api:4.0.2'

Core Imports

import jakarta.xml.bind.JAXBContext;
import jakarta.xml.bind.JAXBException;
import jakarta.xml.bind.Marshaller;
import jakarta.xml.bind.Unmarshaller;

For convenience methods:

import jakarta.xml.bind.JAXB;

For annotations:

import jakarta.xml.bind.annotation.XmlRootElement;
import jakarta.xml.bind.annotation.XmlElement;
import jakarta.xml.bind.annotation.XmlAttribute;

For transform integration:

import jakarta.xml.bind.util.JAXBSource;
import jakarta.xml.bind.util.JAXBResult;
import jakarta.xml.bind.util.ValidationEventCollector;

Basic Usage

import jakarta.xml.bind.*;
import jakarta.xml.bind.annotation.*;
import java.io.StringWriter;
import java.io.StringReader;

// Define a POJO with JAXB annotations
@XmlRootElement
public class Person {
    @XmlElement
    private String name;
    
    @XmlAttribute
    private int age;
    
    // Constructors, getters, setters...
    public Person() {}
    
    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }
    
    // Getters and setters
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public int getAge() { return age; }
    public void setAge(int age) { this.age = age; }
}

// Using JAXB for marshalling and unmarshalling
public class Example {
    public static void main(String[] args) throws JAXBException {
        // Create a person object
        Person person = new Person("Alice", 30);
        
        // Method 1: Using convenience methods
        StringWriter writer = new StringWriter();
        JAXB.marshal(person, writer);
        String xml = writer.toString();
        System.out.println(xml);
        
        Person unmarshalled = JAXB.unmarshal(new StringReader(xml), Person.class);
        
        // Method 2: Using JAXBContext (more control)
        JAXBContext context = JAXBContext.newInstance(Person.class);
        
        Marshaller marshaller = context.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
        marshaller.marshal(person, System.out);
        
        Unmarshaller unmarshaller = context.createUnmarshaller();
        Person result = (Person) unmarshaller.unmarshal(new StringReader(xml));
    }
}

Architecture

Jakarta XML Binding is built around several key components:

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

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.

Capabilities

Core Binding Framework

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.

public abstract class JAXBContext {
    public static JAXBContext newInstance(String contextPath) throws JAXBException;
    public static JAXBContext newInstance(Class<?>... classesToBeBound) throws JAXBException;
    public abstract Marshaller createMarshaller() throws JAXBException;
    public abstract Unmarshaller createUnmarshaller() throws JAXBException;
}

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

public interface Unmarshaller {
    Object unmarshal(java.io.File f) throws JAXBException;
    Object unmarshal(java.io.InputStream is) throws JAXBException;
    Object unmarshal(javax.xml.transform.Source source) throws JAXBException;
}

Core Binding

Convenience API

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

public final class JAXB {
    public static <T> T unmarshal(java.io.File xml, Class<T> type);
    public static <T> T unmarshal(java.net.URL xml, Class<T> type);
    public static <T> T unmarshal(String xml, Class<T> type);
    public static void marshal(Object jaxbObject, java.io.File xml);
    public static void marshal(Object jaxbObject, java.net.URL xml);
    public static void marshal(Object jaxbObject, java.io.OutputStream xml);
}

Convenience API

XML Mapping Annotations

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

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

@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;
}

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

XML Mapping Annotations

Type Adapters

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

public abstract class XmlAdapter<ValueType, BoundType> {
    protected XmlAdapter() {}
    
    public abstract BoundType unmarshal(ValueType v) throws Exception;
    public abstract ValueType marshal(BoundType v) throws Exception;
}

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

Type Adapters

Data Type Conversion

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

public final class DatatypeConverter {
    public static String parseString(String lexicalXSDString);
    public static java.math.BigInteger parseInteger(String lexicalXSDInteger);
    public static int parseInt(String lexicalXSDInt);
    public static long parseLong(String lexicalXSDLong);
    public static boolean parseBoolean(String lexicalXSDBoolean);
    public static java.util.Calendar parseDateTime(String lexicalXSDDateTime);
    public static byte[] parseBase64Binary(String lexicalXSDBase64Binary);
    public static byte[] parseHexBinary(String lexicalXSDHexBinary);
    
    public static String printString(String val);
    public static String printInteger(java.math.BigInteger val);
    public static String printInt(int val);
    public static String printLong(long val);
    public static String printBoolean(boolean val);
    public static String printDateTime(java.util.Calendar val);
    public static String printBase64Binary(byte[] val);
    public static String printHexBinary(byte[] val);
}

Data Type Conversion

Validation and Error Handling

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

public interface ValidationEvent {
    int WARNING = 0;
    int ERROR = 1;
    int FATAL_ERROR = 2;
    
    int getSeverity();
    String getMessage();
    Throwable getLinkedException();
    ValidationEventLocator getLocator();
}

public interface ValidationEventHandler {
    boolean handleEvent(ValidationEvent event);
}

public interface ValidationEventLocator {
    java.net.URL getURL();
    int getOffset();
    int getLineNumber();
    int getColumnNumber();
    Object getObject();
    org.w3c.dom.Node getNode();
}

Validation and Error Handling

Binary Attachments

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

public abstract class AttachmentMarshaller {
    public abstract String addMtomAttachment(
        javax.activation.DataHandler data, 
        String elementNamespace, 
        String elementLocalName
    );
    
    public abstract String addMtomAttachment(
        byte[] data, 
        int offset, 
        int length, 
        String mimeType, 
        String elementNamespace, 
        String elementLocalName
    );
    
    public abstract String addSwaRefAttachment(javax.activation.DataHandler data);
    public boolean isXOPPackage();
}

public abstract class AttachmentUnmarshaller {
    public abstract javax.activation.DataHandler getAttachmentAsDataHandler(String cid);
    public abstract byte[] getAttachmentAsByteArray(String cid);
    public boolean isXOPPackage();
}

Binary Attachments

Transform Integration

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.

public class JAXBSource extends javax.xml.transform.sax.SAXSource {
    public JAXBSource(JAXBContext context, Object contentObject) throws JAXBException;
    public JAXBSource(Marshaller marshaller, Object contentObject) throws JAXBException;
}

public class JAXBResult extends javax.xml.transform.sax.SAXResult {
    public JAXBResult(JAXBContext context) throws JAXBException;
    public JAXBResult(Unmarshaller unmarshaller) throws JAXBException;
    public Object getResult() throws JAXBException;
}

Transform Integration

Types

Core Types

public class JAXBElement<T> {
    protected final javax.xml.namespace.QName name;
    protected final Class<T> declaredType;
    protected final Class scope;
    protected T value;
    protected boolean nil = false;
    
    public JAXBElement(javax.xml.namespace.QName name, 
                      Class<T> declaredType, 
                      Class scope, 
                      T value);
    
    public Class<T> getDeclaredType();
    public javax.xml.namespace.QName getName();
    public T getValue();
    public void setValue(T t);
    public Class getScope();
    public boolean isNil();
    public void setNil(boolean value);
}

public abstract class Binder<XmlNode> {
    public abstract Object unmarshal(XmlNode xmlNode) throws JAXBException;
    public abstract <T> JAXBElement<T> unmarshal(XmlNode xmlNode, Class<T> declaredType) 
        throws JAXBException;
    public abstract void marshal(Object jaxbObject, XmlNode xmlNode) throws JAXBException;
    public abstract XmlNode getXMLNode(Object jaxbObject);
    public abstract Object getJAXBNode(XmlNode xmlNode);
}

public abstract class JAXBIntrospector {
    public abstract boolean isElement(Object object);
    public abstract javax.xml.namespace.QName getElementName(Object jaxbElement);
    public static Object getValue(Object jaxbElement);
}

Exception Hierarchy

public class JAXBException extends Exception {
    public JAXBException(String message);
    public JAXBException(String message, String errorCode);
    public JAXBException(Throwable exception);
    public JAXBException(String message, Throwable exception);
    public JAXBException(String message, String errorCode, Throwable exception);
    
    public String getErrorCode();
    public Throwable getLinkedException();
    public void setLinkedException(Throwable exception);
}

public class MarshalException extends JAXBException {
    public MarshalException(String message);
    public MarshalException(String message, String errorCode);
    public MarshalException(Throwable exception);
    public MarshalException(String message, Throwable exception);
    public MarshalException(String message, String errorCode, Throwable exception);
}

public class UnmarshalException extends JAXBException {
    public UnmarshalException(String message);
    public UnmarshalException(String message, String errorCode);
    public UnmarshalException(Throwable exception);
    public UnmarshalException(String message, Throwable exception);
    public UnmarshalException(String message, String errorCode, Throwable exception);
}

public class ValidationException extends JAXBException {
    public ValidationException(String message);
    public ValidationException(String message, String errorCode);
    public ValidationException(Throwable exception);
    public ValidationException(String message, Throwable exception);
    public ValidationException(String message, String errorCode, Throwable exception);
}

public class PropertyException extends JAXBException {
    public PropertyException(String message);
    public PropertyException(String message, String errorCode);
    public PropertyException(Throwable exception);
    public PropertyException(String message, Throwable exception);
    public PropertyException(String message, String errorCode, Throwable exception);
}

public class DataBindingException extends RuntimeException {
    public DataBindingException(String message, Throwable cause);
    public DataBindingException(Throwable cause);
}

public class TypeConstraintException extends RuntimeException {
    public TypeConstraintException(String message);
    public TypeConstraintException(String message, Throwable cause);
    public TypeConstraintException(Throwable cause);
}