CtrlK
BlogDocsLog inGet started
Tessl Logo

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

core-binding.mddocs/

Core Binding Framework

The core binding framework provides the fundamental JAXB operations for creating binding contexts and performing marshalling and unmarshalling operations. These classes form the foundation of all XML binding functionality in Jakarta XML Binding.

Capabilities

JAXBContext Creation

JAXBContext serves as the entry point to the Jakarta XML Binding API, providing the binding context necessary for marshalling and unmarshalling operations.

public abstract class JAXBContext {
    // Create context from package paths
    public static JAXBContext newInstance(String contextPath) throws JAXBException;
    public static JAXBContext newInstance(String contextPath, ClassLoader classLoader) throws JAXBException;
    public static JAXBContext newInstance(String contextPath, ClassLoader classLoader, Map<String,?> properties) throws JAXBException;
    
    // Create context from classes
    public static JAXBContext newInstance(Class<?>... classesToBeBound) throws JAXBException;
    public static JAXBContext newInstance(Class<?>[] classesToBeBound, Map<String,?> properties) throws JAXBException;
    
    // Create runtime instances
    public abstract Marshaller createMarshaller() throws JAXBException;
    public abstract Unmarshaller createUnmarshaller() throws JAXBException;
    
    // Additional functionality
    public <T> Binder<T> createBinder(Class<T> domType);
    public Binder<org.w3c.dom.Node> createBinder();
    public JAXBIntrospector createJAXBIntrospector();
    public void generateSchema(SchemaOutputResolver outputResolver) throws IOException;
}

Usage Examples:

// Create context from class
JAXBContext context = JAXBContext.newInstance(MyClass.class);

// Create context from multiple classes
JAXBContext context = JAXBContext.newInstance(Person.class, Address.class);

// Create context from package path
JAXBContext context = JAXBContext.newInstance("com.example.model");

// Create context with properties
Map<String, Object> properties = new HashMap<>();
properties.put("jaxb.formatted.output", true);
JAXBContext context = JAXBContext.newInstance(MyClass.class, properties);

Marshalling Operations

Marshaller serializes Java content trees to XML data with extensive customization options for output formatting and validation.

public interface Marshaller {
    // Core marshal methods
    void marshal(Object jaxbElement, javax.xml.transform.Result result) throws JAXBException;
    void marshal(Object jaxbElement, java.io.OutputStream os) throws JAXBException;
    void marshal(Object jaxbElement, java.io.File output) throws JAXBException;
    void marshal(Object jaxbElement, java.io.Writer writer) throws JAXBException;
    void marshal(Object jaxbElement, org.xml.sax.ContentHandler handler) throws JAXBException;
    void marshal(Object jaxbElement, org.w3c.dom.Node node) throws JAXBException;
    void marshal(Object jaxbElement, javax.xml.stream.XMLStreamWriter writer) throws JAXBException;
    void marshal(Object jaxbElement, javax.xml.stream.XMLEventWriter writer) throws JAXBException;
    
    // DOM view
    org.w3c.dom.Node getNode(Object contentTree) throws JAXBException;
    
    // Property management
    void setProperty(String name, Object value) throws PropertyException;
    Object getProperty(String name) throws PropertyException;
    
    // Event handling
    void setEventHandler(ValidationEventHandler handler) throws JAXBException;
    ValidationEventHandler getEventHandler() throws JAXBException;
    
    // Type adapters
    <A extends XmlAdapter> void setAdapter(Class<A> type, A adapter);
    <A extends XmlAdapter> A getAdapter(Class<A> type);
    void setAdapter(XmlAdapter adapter);
    
    // Attachment support
    void setAttachmentMarshaller(jakarta.xml.bind.attachment.AttachmentMarshaller am);
    jakarta.xml.bind.attachment.AttachmentMarshaller getAttachmentMarshaller();
    
    // Schema validation
    void setSchema(javax.xml.validation.Schema schema);
    javax.xml.validation.Schema getSchema();
    
    // Event listener
    void setListener(Marshaller.Listener listener);
    Marshaller.Listener getListener();
    
    // Nested listener class
    public static abstract class Listener {
        public void beforeMarshal(Object source) {}
        public void afterMarshal(Object source) {}
    }
}

Standard Properties:

public interface Marshaller {
    String JAXB_ENCODING = "jaxb.encoding";
    String JAXB_FORMATTED_OUTPUT = "jaxb.formatted.output";
    String JAXB_SCHEMA_LOCATION = "jaxb.schemaLocation";
    String JAXB_NO_NAMESPACE_SCHEMA_LOCATION = "jaxb.noNamespaceSchemaLocation";
    String JAXB_FRAGMENT = "jaxb.fragment";
}

Usage Examples:

JAXBContext context = JAXBContext.newInstance(Person.class);
Marshaller marshaller = context.createMarshaller();

// Set formatting properties
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");

// Marshal to different destinations
Person person = new Person("Alice", 30);

// To file
marshaller.marshal(person, new File("person.xml"));

// To output stream
marshaller.marshal(person, System.out);

// To string writer
StringWriter writer = new StringWriter();
marshaller.marshal(person, writer);
String xml = writer.toString();

// With schema validation
Schema schema = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI)
    .newSchema(new File("person.xsd"));
marshaller.setSchema(schema);
marshaller.marshal(person, System.out);

Unmarshalling Operations

Unmarshaller deserializes XML data to Java content trees with support for validation, event handling, and various input sources.

public interface Unmarshaller {
    // Core unmarshal methods
    Object unmarshal(java.io.File f) throws JAXBException;
    Object unmarshal(java.io.InputStream is) throws JAXBException;
    Object unmarshal(java.io.Reader reader) throws JAXBException;
    Object unmarshal(java.net.URL url) throws JAXBException;
    Object unmarshal(org.xml.sax.InputSource source) throws JAXBException;
    Object unmarshal(org.w3c.dom.Node node) throws JAXBException;
    Object unmarshal(javax.xml.transform.Source source) throws JAXBException;
    Object unmarshal(javax.xml.stream.XMLStreamReader reader) throws JAXBException;
    Object unmarshal(javax.xml.stream.XMLEventReader reader) throws JAXBException;
    
    // Type-safe unmarshal methods
    <T> JAXBElement<T> unmarshal(org.w3c.dom.Node node, Class<T> declaredType) throws JAXBException;
    <T> JAXBElement<T> unmarshal(javax.xml.transform.Source source, Class<T> declaredType) throws JAXBException;
    <T> JAXBElement<T> unmarshal(javax.xml.stream.XMLStreamReader reader, Class<T> declaredType) throws JAXBException;
    <T> JAXBElement<T> unmarshal(javax.xml.stream.XMLEventReader reader, Class<T> declaredType) throws JAXBException;
    
    // SAX handler support
    UnmarshallerHandler getUnmarshallerHandler();
    
    // Property management
    void setProperty(String name, Object value) throws PropertyException;
    Object getProperty(String name) throws PropertyException;
    
    // Event handling
    void setEventHandler(ValidationEventHandler handler) throws JAXBException;
    ValidationEventHandler getEventHandler() throws JAXBException;
    
    // Type adapters
    <A extends XmlAdapter> void setAdapter(Class<A> type, A adapter);
    <A extends XmlAdapter> A getAdapter(Class<A> type);
    void setAdapter(XmlAdapter adapter);
    
    // Attachment support
    void setAttachmentUnmarshaller(jakarta.xml.bind.attachment.AttachmentUnmarshaller au);
    jakarta.xml.bind.attachment.AttachmentUnmarshaller getAttachmentUnmarshaller();
    
    // Schema validation
    void setSchema(javax.xml.validation.Schema schema);
    javax.xml.validation.Schema getSchema();
    
    // Event listener
    void setListener(Unmarshaller.Listener listener);
    Unmarshaller.Listener getListener();
    
    // Nested listener class
    public static abstract class Listener {
        public void beforeUnmarshal(Object target, Object parent) {}
        public void afterUnmarshal(Object target, Object parent) {}
    }
}

Usage Examples:

JAXBContext context = JAXBContext.newInstance(Person.class);
Unmarshaller unmarshaller = context.createUnmarshaller();

// Unmarshal from different sources
Person person;

// From file
person = (Person) unmarshaller.unmarshal(new File("person.xml"));

// From input stream
try (InputStream is = new FileInputStream("person.xml")) {
    person = (Person) unmarshaller.unmarshal(is);
}

// From URL
person = (Person) unmarshaller.unmarshal(new URL("http://example.com/person.xml"));

// From string
String xml = "<person age='30'><name>Alice</name></person>";
person = (Person) unmarshaller.unmarshal(new StringReader(xml));

// Type-safe unmarshalling
JAXBElement<Person> element = unmarshaller.unmarshal(
    new StreamSource(new StringReader(xml)), 
    Person.class
);
person = element.getValue();

// With validation
Schema schema = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI)
    .newSchema(new File("person.xsd"));
unmarshaller.setSchema(schema);
person = (Person) unmarshaller.unmarshal(new File("person.xml"));

JAXBElement Wrapper

JAXBElement provides a wrapper for XML elements with type information and metadata.

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;
    
    // Constructors
    public JAXBElement(javax.xml.namespace.QName name, Class<T> declaredType, Class scope, T value);
    public JAXBElement(javax.xml.namespace.QName name, Class<T> declaredType, T value);
    
    // Property access
    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 boolean isGlobalScope();
    public boolean isTypeSubstituted();
    
    // Global scope marker
    public static final class GlobalScope {}
}

Usage Examples:

import javax.xml.namespace.QName;

// Create JAXBElement for global element
QName qname = new QName("http://example.com", "person");
JAXBElement<Person> element = new JAXBElement<>(
    qname, 
    Person.class, 
    person
);

// Create with explicit scope
JAXBElement<String> nameElement = new JAXBElement<>(
    new QName("name"), 
    String.class, 
    Person.class,  // scope
    "Alice"
);

// Access properties
String elementName = element.getName().getLocalPart();
Person personValue = element.getValue();
boolean isGlobal = element.isGlobalScope();

// Handle nil values
element.setNil(true);
if (element.isNil()) {
    // Handle nil case
}

Types

Context Factory Interface

public interface JAXBContextFactory {
    JAXBContext createContext(Class<?>[] classesToBeBound, Map<String, ?> properties) throws JAXBException;
    JAXBContext createContext(String contextPath, ClassLoader classLoader, Map<String, ?> properties) throws JAXBException;
}

Handler Interfaces

public interface UnmarshallerHandler extends org.xml.sax.ContentHandler {
    Object getResult() throws JAXBException, IllegalStateException;
}

public abstract class SchemaOutputResolver {
    public abstract javax.xml.transform.Result createOutput(String namespaceUri, String suggestedFileName) throws IOException;
}

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