0
# Convenience API
1

2
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.
3

4
## Capabilities
5

6
### Static Unmarshal Methods
7

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

10
```java { .api }
11
public final class JAXB {
12
    // Unmarshal from file
13
    public static <T> T unmarshal(java.io.File xml, Class<T> type);
14
    
15
    // Unmarshal from URL
16
    public static <T> T unmarshal(java.net.URL xml, Class<T> type);
17
    
18
    // Unmarshal from URI
19
    public static <T> T unmarshal(java.net.URI xml, Class<T> type);
20
    
21
    // Unmarshal from string
22
    public static <T> T unmarshal(String xml, Class<T> type);
23
    
24
    // Unmarshal from input stream
25
    public static <T> T unmarshal(java.io.InputStream xml, Class<T> type);
26
    
27
    // Unmarshal from reader
28
    public static <T> T unmarshal(java.io.Reader xml, Class<T> type);
29
    
30
    // Unmarshal from source
31
    public static <T> T unmarshal(javax.xml.transform.Source xml, Class<T> type);
32
}
33
```
34

35
**Usage Examples:**
36

37
```java
38
// From file
39
Person person = JAXB.unmarshal(new File("person.xml"), Person.class);
40

41
// From URL
42
Person person = JAXB.unmarshal(
43
    new URL("http://example.com/person.xml"), 
44
    Person.class
45
);
46

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

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

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

61
// From transform source
62
StreamSource source = new StreamSource(new StringReader(xml));
63
Person person = JAXB.unmarshal(source, Person.class);
64
```
65

66
### Static Marshal Methods
67

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

70
```java { .api }
71
public final class JAXB {
72
    // Marshal to file
73
    public static void marshal(Object jaxbObject, java.io.File xml);
74
    
75
    // Marshal to URL
76
    public static void marshal(Object jaxbObject, java.net.URL xml);
77
    
78
    // Marshal to URI  
79
    public static void marshal(Object jaxbObject, java.net.URI xml);
80
    
81
    // Marshal to string
82
    public static void marshal(Object jaxbObject, String xml);
83
    
84
    // Marshal to output stream
85
    public static void marshal(Object jaxbObject, java.io.OutputStream xml);
86
    
87
    // Marshal to writer
88
    public static void marshal(Object jaxbObject, java.io.Writer xml);
89
    
90
    // Marshal to result
91
    public static void marshal(Object jaxbObject, javax.xml.transform.Result xml);
92
}
93
```
94

95
**Usage Examples:**
96

97
```java
98
Person person = new Person("Alice", 30);
99

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

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

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

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

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

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

125
## Characteristics and Limitations
126

127
### Performance Considerations
128

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

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

135
### Error Handling
136

137
All convenience methods wrap checked exceptions in runtime exceptions:
138

139
```java { .api }
140
public class DataBindingException extends RuntimeException {
141
    public DataBindingException(String message, Throwable cause);
142
    public DataBindingException(Throwable cause);
143
}
144
```
145

146
**Example Error Handling:**
147

148
```java
149
try {
150
    Person person = JAXB.unmarshal(new File("person.xml"), Person.class);
151
} catch (DataBindingException e) {
152
    // Wrapped JAXBException available as cause
153
    Throwable cause = e.getCause();
154
    if (cause instanceof JAXBException) {
155
        JAXBException jaxbException = (JAXBException) cause;
156
        // Handle JAXB-specific error
157
    }
158
}
159
```
160

161
### Validation Behavior
162

163
The convenience methods have specific validation characteristics:
164

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

169
### Method Requirements
170

171
All convenience methods have the following requirements:
172

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

177
## Usage Patterns
178

179
### Simple Data Transfer Objects
180

181
```java
182
@XmlRootElement
183
public class Config {
184
    @XmlElement
185
    private String database;
186
    
187
    @XmlElement
188
    private int timeout;
189
    
190
    // Constructors, getters, setters...
191
}
192

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

196
// Save configuration
197
JAXB.marshal(config, new File("config.xml"));
198
```
199

200
### Web Service Integration
201

202
```java
203
// Unmarshal response from web service
204
URL serviceUrl = new URL("http://api.example.com/user/123");
205
User user = JAXB.unmarshal(serviceUrl, User.class);
206

207
// Marshal request data
208
StringWriter writer = new StringWriter();
209
JAXB.marshal(requestData, writer);
210
String requestXml = writer.toString();
211
// Send requestXml to web service
212
```
213

214
### Rapid Prototyping
215

216
```java
217
// Quick XML processing without context setup
218
public void processXmlFiles(File[] xmlFiles) {
219
    for (File file : xmlFiles) {
220
        try {
221
            Order order = JAXB.unmarshal(file, Order.class);
222
            processOrder(order);
223
            
224
            // Update and save back
225
            JAXB.marshal(order, file);
226
        } catch (DataBindingException e) {
227
            System.err.println("Failed to process: " + file.getName());
228
        }
229
    }
230
}
231
```
232

233
## When to Use Convenience API vs Core Framework
234

235
### Use Convenience API When:
236
- Simple, straightforward XML binding operations
237
- Minimal configuration requirements
238
- Rapid prototyping or one-off scripts
239
- New to Jakarta XML Binding
240
- No specific performance requirements
241

242
### Use Core Framework When:
243
- Performance-critical applications
244
- Complex validation requirements
245
- Custom error handling needed
246
- Advanced marshalling/unmarshalling options
247
- Schema generation requirements
248
- Custom type adapters or attachment handling