0
# Core Binding Framework
1

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

4
## Capabilities
5

6
### JAXBContext Creation
7

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

10
```java { .api }
11
public abstract class JAXBContext {
12
    // Create context from package paths
13
    public static JAXBContext newInstance(String contextPath) throws JAXBException;
14
    public static JAXBContext newInstance(String contextPath, ClassLoader classLoader) throws JAXBException;
15
    public static JAXBContext newInstance(String contextPath, ClassLoader classLoader, Map<String,?> properties) throws JAXBException;
16
    
17
    // Create context from classes
18
    public static JAXBContext newInstance(Class<?>... classesToBeBound) throws JAXBException;
19
    public static JAXBContext newInstance(Class<?>[] classesToBeBound, Map<String,?> properties) throws JAXBException;
20
    
21
    // Create runtime instances
22
    public abstract Marshaller createMarshaller() throws JAXBException;
23
    public abstract Unmarshaller createUnmarshaller() throws JAXBException;
24
    
25
    // Additional functionality
26
    public <T> Binder<T> createBinder(Class<T> domType);
27
    public Binder<org.w3c.dom.Node> createBinder();
28
    public JAXBIntrospector createJAXBIntrospector();
29
    public void generateSchema(SchemaOutputResolver outputResolver) throws IOException;
30
}
31
```
32

33
**Usage Examples:**
34

35
```java
36
// Create context from class
37
JAXBContext context = JAXBContext.newInstance(MyClass.class);
38

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

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

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

51
### Marshalling Operations
52

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

55
```java { .api }
56
public interface Marshaller {
57
    // Core marshal methods
58
    void marshal(Object jaxbElement, javax.xml.transform.Result result) throws JAXBException;
59
    void marshal(Object jaxbElement, java.io.OutputStream os) throws JAXBException;
60
    void marshal(Object jaxbElement, java.io.File output) throws JAXBException;
61
    void marshal(Object jaxbElement, java.io.Writer writer) throws JAXBException;
62
    void marshal(Object jaxbElement, org.xml.sax.ContentHandler handler) throws JAXBException;
63
    void marshal(Object jaxbElement, org.w3c.dom.Node node) throws JAXBException;
64
    void marshal(Object jaxbElement, javax.xml.stream.XMLStreamWriter writer) throws JAXBException;
65
    void marshal(Object jaxbElement, javax.xml.stream.XMLEventWriter writer) throws JAXBException;
66
    
67
    // DOM view
68
    org.w3c.dom.Node getNode(Object contentTree) throws JAXBException;
69
    
70
    // Property management
71
    void setProperty(String name, Object value) throws PropertyException;
72
    Object getProperty(String name) throws PropertyException;
73
    
74
    // Event handling
75
    void setEventHandler(ValidationEventHandler handler) throws JAXBException;
76
    ValidationEventHandler getEventHandler() throws JAXBException;
77
    
78
    // Type adapters
79
    <A extends XmlAdapter> void setAdapter(Class<A> type, A adapter);
80
    <A extends XmlAdapter> A getAdapter(Class<A> type);
81
    void setAdapter(XmlAdapter adapter);
82
    
83
    // Attachment support
84
    void setAttachmentMarshaller(jakarta.xml.bind.attachment.AttachmentMarshaller am);
85
    jakarta.xml.bind.attachment.AttachmentMarshaller getAttachmentMarshaller();
86
    
87
    // Schema validation
88
    void setSchema(javax.xml.validation.Schema schema);
89
    javax.xml.validation.Schema getSchema();
90
    
91
    // Event listener
92
    void setListener(Marshaller.Listener listener);
93
    Marshaller.Listener getListener();
94
    
95
    // Nested listener class
96
    public static abstract class Listener {
97
        public void beforeMarshal(Object source) {}
98
        public void afterMarshal(Object source) {}
99
    }
100
}
101
```
102

103
**Standard Properties:**
104

105
```java { .api }
106
public interface Marshaller {
107
    String JAXB_ENCODING = "jaxb.encoding";
108
    String JAXB_FORMATTED_OUTPUT = "jaxb.formatted.output";
109
    String JAXB_SCHEMA_LOCATION = "jaxb.schemaLocation";
110
    String JAXB_NO_NAMESPACE_SCHEMA_LOCATION = "jaxb.noNamespaceSchemaLocation";
111
    String JAXB_FRAGMENT = "jaxb.fragment";
112
}
113
```
114

115
**Usage Examples:**
116

117
```java
118
JAXBContext context = JAXBContext.newInstance(Person.class);
119
Marshaller marshaller = context.createMarshaller();
120

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

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

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

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

134
// To string writer
135
StringWriter writer = new StringWriter();
136
marshaller.marshal(person, writer);
137
String xml = writer.toString();
138

139
// With schema validation
140
Schema schema = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI)
141
    .newSchema(new File("person.xsd"));
142
marshaller.setSchema(schema);
143
marshaller.marshal(person, System.out);
144
```
145

146
### Unmarshalling Operations
147

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

150
```java { .api }
151
public interface Unmarshaller {
152
    // Core unmarshal methods
153
    Object unmarshal(java.io.File f) throws JAXBException;
154
    Object unmarshal(java.io.InputStream is) throws JAXBException;
155
    Object unmarshal(java.io.Reader reader) throws JAXBException;
156
    Object unmarshal(java.net.URL url) throws JAXBException;
157
    Object unmarshal(org.xml.sax.InputSource source) throws JAXBException;
158
    Object unmarshal(org.w3c.dom.Node node) throws JAXBException;
159
    Object unmarshal(javax.xml.transform.Source source) throws JAXBException;
160
    Object unmarshal(javax.xml.stream.XMLStreamReader reader) throws JAXBException;
161
    Object unmarshal(javax.xml.stream.XMLEventReader reader) throws JAXBException;
162
    
163
    // Type-safe unmarshal methods
164
    <T> JAXBElement<T> unmarshal(org.w3c.dom.Node node, Class<T> declaredType) throws JAXBException;
165
    <T> JAXBElement<T> unmarshal(javax.xml.transform.Source source, Class<T> declaredType) throws JAXBException;
166
    <T> JAXBElement<T> unmarshal(javax.xml.stream.XMLStreamReader reader, Class<T> declaredType) throws JAXBException;
167
    <T> JAXBElement<T> unmarshal(javax.xml.stream.XMLEventReader reader, Class<T> declaredType) throws JAXBException;
168
    
169
    // SAX handler support
170
    UnmarshallerHandler getUnmarshallerHandler();
171
    
172
    // Property management
173
    void setProperty(String name, Object value) throws PropertyException;
174
    Object getProperty(String name) throws PropertyException;
175
    
176
    // Event handling
177
    void setEventHandler(ValidationEventHandler handler) throws JAXBException;
178
    ValidationEventHandler getEventHandler() throws JAXBException;
179
    
180
    // Type adapters
181
    <A extends XmlAdapter> void setAdapter(Class<A> type, A adapter);
182
    <A extends XmlAdapter> A getAdapter(Class<A> type);
183
    void setAdapter(XmlAdapter adapter);
184
    
185
    // Attachment support
186
    void setAttachmentUnmarshaller(jakarta.xml.bind.attachment.AttachmentUnmarshaller au);
187
    jakarta.xml.bind.attachment.AttachmentUnmarshaller getAttachmentUnmarshaller();
188
    
189
    // Schema validation
190
    void setSchema(javax.xml.validation.Schema schema);
191
    javax.xml.validation.Schema getSchema();
192
    
193
    // Event listener
194
    void setListener(Unmarshaller.Listener listener);
195
    Unmarshaller.Listener getListener();
196
    
197
    // Nested listener class
198
    public static abstract class Listener {
199
        public void beforeUnmarshal(Object target, Object parent) {}
200
        public void afterUnmarshal(Object target, Object parent) {}
201
    }
202
}
203
```
204

205
**Usage Examples:**
206

207
```java
208
JAXBContext context = JAXBContext.newInstance(Person.class);
209
Unmarshaller unmarshaller = context.createUnmarshaller();
210

211
// Unmarshal from different sources
212
Person person;
213

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

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

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

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

229
// Type-safe unmarshalling
230
JAXBElement<Person> element = unmarshaller.unmarshal(
231
    new StreamSource(new StringReader(xml)), 
232
    Person.class
233
);
234
person = element.getValue();
235

236
// With validation
237
Schema schema = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI)
238
    .newSchema(new File("person.xsd"));
239
unmarshaller.setSchema(schema);
240
person = (Person) unmarshaller.unmarshal(new File("person.xml"));
241
```
242

243
### JAXBElement Wrapper
244

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

247
```java { .api }
248
public class JAXBElement<T> {
249
    protected final javax.xml.namespace.QName name;
250
    protected final Class<T> declaredType;
251
    protected final Class scope;
252
    protected T value;
253
    protected boolean nil = false;
254
    
255
    // Constructors
256
    public JAXBElement(javax.xml.namespace.QName name, Class<T> declaredType, Class scope, T value);
257
    public JAXBElement(javax.xml.namespace.QName name, Class<T> declaredType, T value);
258
    
259
    // Property access
260
    public Class<T> getDeclaredType();
261
    public javax.xml.namespace.QName getName();
262
    public T getValue();
263
    public void setValue(T t);
264
    public Class getScope();
265
    public boolean isNil();
266
    public void setNil(boolean value);
267
    public boolean isGlobalScope();
268
    public boolean isTypeSubstituted();
269
    
270
    // Global scope marker
271
    public static final class GlobalScope {}
272
}
273
```
274

275
**Usage Examples:**
276

277
```java
278
import javax.xml.namespace.QName;
279

280
// Create JAXBElement for global element
281
QName qname = new QName("http://example.com", "person");
282
JAXBElement<Person> element = new JAXBElement<>(
283
    qname, 
284
    Person.class, 
285
    person
286
);
287

288
// Create with explicit scope
289
JAXBElement<String> nameElement = new JAXBElement<>(
290
    new QName("name"), 
291
    String.class, 
292
    Person.class,  // scope
293
    "Alice"
294
);
295

296
// Access properties
297
String elementName = element.getName().getLocalPart();
298
Person personValue = element.getValue();
299
boolean isGlobal = element.isGlobalScope();
300

301
// Handle nil values
302
element.setNil(true);
303
if (element.isNil()) {
304
    // Handle nil case
305
}
306
```
307

308
## Types
309

310
### Context Factory Interface
311

312
```java { .api }
313
public interface JAXBContextFactory {
314
    JAXBContext createContext(Class<?>[] classesToBeBound, Map<String, ?> properties) throws JAXBException;
315
    JAXBContext createContext(String contextPath, ClassLoader classLoader, Map<String, ?> properties) throws JAXBException;
316
}
317
```
318

319
### Handler Interfaces
320

321
```java { .api }
322
public interface UnmarshallerHandler extends org.xml.sax.ContentHandler {
323
    Object getResult() throws JAXBException, IllegalStateException;
324
}
325

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