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

Convenience API

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

The JAXB convenience API provides static utility methods for common XML binding operations without requiring explicit JAXBContext management. These methods are designed for simple use cases and developers new to Jakarta XML Binding.

Capabilities

Static Unmarshal Methods

Convenience methods for unmarshalling XML data from various sources directly to Java objects.

public final class JAXB {
    // Unmarshal from file
    public static <T> T unmarshal(java.io.File xml, Class<T> type);
    
    // Unmarshal from URL
    public static <T> T unmarshal(java.net.URL xml, Class<T> type);
    
    // Unmarshal from URI
    public static <T> T unmarshal(java.net.URI xml, Class<T> type);
    
    // Unmarshal from string
    public static <T> T unmarshal(String xml, Class<T> type);
    
    // Unmarshal from input stream
    public static <T> T unmarshal(java.io.InputStream xml, Class<T> type);
    
    // Unmarshal from reader
    public static <T> T unmarshal(java.io.Reader xml, Class<T> type);
    
    // Unmarshal from source
    public static <T> T unmarshal(javax.xml.transform.Source xml, Class<T> type);
}

Usage Examples:

// From file
Person person = JAXB.unmarshal(new File("person.xml"), Person.class);

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

// From string XML
String xml = "<person age='30'><name>Alice</name></person>";
Person person = JAXB.unmarshal(xml, Person.class);

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

// From reader
try (FileReader reader = new FileReader("person.xml")) {
    Person person = JAXB.unmarshal(reader, Person.class);
}

// From transform source
StreamSource source = new StreamSource(new StringReader(xml));
Person person = JAXB.unmarshal(source, Person.class);

Static Marshal Methods

Convenience methods for marshalling Java objects to XML at various destinations.

public final class JAXB {
    // Marshal to file
    public static void marshal(Object jaxbObject, java.io.File xml);
    
    // Marshal to URL
    public static void marshal(Object jaxbObject, java.net.URL xml);
    
    // Marshal to URI  
    public static void marshal(Object jaxbObject, java.net.URI xml);
    
    // Marshal to string
    public static void marshal(Object jaxbObject, String xml);
    
    // Marshal to output stream
    public static void marshal(Object jaxbObject, java.io.OutputStream xml);
    
    // Marshal to writer
    public static void marshal(Object jaxbObject, java.io.Writer xml);
    
    // Marshal to result
    public static void marshal(Object jaxbObject, javax.xml.transform.Result xml);
}

Usage Examples:

Person person = new Person("Alice", 30);

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

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

// To string writer (capture XML as string)
StringWriter writer = new StringWriter();
JAXB.marshal(person, writer);
String xml = writer.toString();

// To file writer
try (FileWriter fileWriter = new FileWriter("person.xml")) {
    JAXB.marshal(person, fileWriter);
}

// To transform result
StreamResult result = new StreamResult(new FileOutputStream("person.xml"));
JAXB.marshal(person, result);

// To URL (for HTTP PUT operations)
URL uploadUrl = new URL("http://example.com/upload/person.xml");
JAXB.marshal(person, uploadUrl);

Characteristics and Limitations

Performance Considerations

The convenience methods are designed for ease of use rather than optimal performance:

Context Caching: JAXBContext instances are cached internally for better performance on repeated operations
Simple Use Cases: Best suited for straightforward scenarios without complex configuration needs
Production Code: For performance-critical applications, use the core binding framework directly

Error Handling

All convenience methods wrap checked exceptions in runtime exceptions:

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

Example Error Handling:

try {
    Person person = JAXB.unmarshal(new File("person.xml"), Person.class);
} catch (DataBindingException e) {
    // Wrapped JAXBException available as cause
    Throwable cause = e.getCause();
    if (cause instanceof JAXBException) {
        JAXBException jaxbException = (JAXBException) cause;
        // Handle JAXB-specific error
    }
}

Validation Behavior

The convenience methods have specific validation characteristics:

Unmarshalling: No schema validation is performed by default; processing continues even with XML errors where possible
Marshalling: Processing attempts to continue even if the Java object tree doesn't meet validity requirements
Failure Mode: Methods only fail as a last resort with DataBindingException

Method Requirements

All convenience methods have the following requirements:

Non-null Arguments: All parameters must be non-null
Return Values: Unmarshal methods either fail with exception or return non-null values
Type Safety: Generic type parameters ensure compile-time type safety

Usage Patterns

Simple Data Transfer Objects

@XmlRootElement
public class Config {
    @XmlElement
    private String database;
    
    @XmlElement
    private int timeout;
    
    // Constructors, getters, setters...
}

// Load configuration
Config config = JAXB.unmarshal(new File("config.xml"), Config.class);

// Save configuration
JAXB.marshal(config, new File("config.xml"));

Web Service Integration

// Unmarshal response from web service
URL serviceUrl = new URL("http://api.example.com/user/123");
User user = JAXB.unmarshal(serviceUrl, User.class);

// Marshal request data
StringWriter writer = new StringWriter();
JAXB.marshal(requestData, writer);
String requestXml = writer.toString();
// Send requestXml to web service

Rapid Prototyping

// Quick XML processing without context setup
public void processXmlFiles(File[] xmlFiles) {
    for (File file : xmlFiles) {
        try {
            Order order = JAXB.unmarshal(file, Order.class);
            processOrder(order);
            
            // Update and save back
            JAXB.marshal(order, file);
        } catch (DataBindingException e) {
            System.err.println("Failed to process: " + file.getName());
        }
    }
}

When to Use Convenience API vs Core Framework

Use Convenience API When:

Simple, straightforward XML binding operations
Minimal configuration requirements
Rapid prototyping or one-off scripts
New to Jakarta XML Binding
No specific performance requirements

Use Core Framework When:

Performance-critical applications
Complex validation requirements
Custom error handling needed
Advanced marshalling/unmarshalling options
Schema generation requirements
Custom type adapters or attachment handling

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