0
# Databinding System
1

2
XML-to-Java databinding system with comprehensive JAXB integration and support for custom databinding providers. The system provides flexible serialization/deserialization of Java objects to/from XML with support for various databinding modes and optimization strategies.
3

4
## Capabilities
5

6
### Core Databinding Interface
7

8
Central databinding abstraction providing XML-to-Java serialization services.
9

10
```java { .api }
11
/**
12
 * Core interface for XML/Java serialization and WSDL generation
13
 */
14
package com.oracle.webservices.api.databinding;
15
public interface Databinding {
16
    /** Create call bridge for server-side endpoint operations */
17
    EndpointCallBridge createCallBridge(JavaCallInfo callInfo);
18
    
19
    /** Create call bridge for client-side service calls */
20
    ClientCallBridge createCallBridge(JavaCallInfo callInfo);
21
    
22
    /** Generate WSDL from Java service interface */
23
    void generateWSDL(WSDLGenInfo wsdlGenInfo);
24
    
25
    /** Marshal Java object to XML */
26
    XMLBridge createBridge(TypeInfo typeInfo);
27
    
28
    /** Get databinding configuration */
29
    DatabindingConfig getConfig();
30
    
31
    /** Get bound context */
32
    Object getBoundContext();
33
}
34

35
/**
36
 * Factory for creating databinding instances
37
 */
38
public abstract class DatabindingFactory {
39
    /** Get default databinding factory instance */
40
    public static DatabindingFactory newInstance();
41
    
42
    /** Create databinding with configuration */
43
    public abstract Databinding createDatabinding(DatabindingConfig config);
44
    
45
    /** Create runtime databinding */
46
    public Databinding createRuntime(DatabindingConfig config);
47
}
48
```
49

50
### Databinding Configuration
51

52
Configuration system for customizing databinding behavior and selecting providers.
53

54
```java { .api }
55
/**
56
 * Configuration for databinding creation and behavior
57
 */
58
public final class DatabindingConfig {
59
    /** Set contract class (SEI) */
60
    public DatabindingConfig setContractClass(Class<?> contractClass);
61
    
62
    /** Set endpoint class (implementation) */
63
    public DatabindingConfig setEndpointClass(Class<?> endpointClass);
64
    
65
    /** Set databinding mode */
66
    public DatabindingConfig setDatabindingMode(DatabindingMode mode);
67
    
68
    /** Set properties */
69
    public DatabindingConfig setProperties(Map<String, Object> properties);
70
    
71
    /** Set class loader */
72
    public DatabindingConfig setClassLoader(ClassLoader classLoader);
73
    
74
    /** Set metadata reader */
75
    public DatabindingConfig setMetadataReader(MetadataReader metadataReader);
76
    
77
    /** Set WSDL port */
78
    public DatabindingConfig setWsdlPort(WSDLPort wsdlPort);
79
    
80
    /** Set features */
81
    public DatabindingConfig setFeatures(WebServiceFeature... features);
82
    
83
    /** Get contract class */
84
    public Class<?> getContractClass();
85
    
86
    /** Get endpoint class */
87
    public Class<?> getEndpointClass();
88
    
89
    /** Get databinding mode */
90
    public DatabindingMode getDatabindingMode();
91
    
92
    /** Get properties */
93
    public Map<String, Object> getProperties();
94
}
95

96
/**
97
 * Databinding mode enumeration
98
 */
99
public enum DatabindingMode {
100
    /** Use JAXB for databinding */
101
    glassfish_jaxb,
102
    
103
    /** Use Eclipse MOXy for databinding */
104
    eclipselink_moxy,
105
    
106
    /** Use custom databinding provider */
107
    custom;
108
    
109
    /** Get mode from string */
110
    public static DatabindingMode fromString(String mode);
111
}
112
```
113

114
### Call Bridges
115

116
Call bridges providing method invocation abstraction for client and server sides.
117

118
```java { .api }
119
/**
120
 * Server-side call bridge for endpoint method invocation
121
 */
122
public interface EndpointCallBridge {
123
    /** Invoke endpoint method with deserialized parameters */
124
    Object invoke(Object endpoint, Object... args) throws Throwable;
125
    
126
    /** Get method information */
127
    Method getMethod();
128
    
129
    /** Get parameter bridges */
130
    ParameterBridge[] getParameterBridges();
131
    
132
    /** Get return type bridge */
133
    ParameterBridge getReturnBridge();
134
    
135
    /** Check if method is one-way */
136
    boolean isOneWay();
137
    
138
    /** Get exception bridges */
139
    ExceptionBridge[] getExceptionBridges();
140
}
141

142
/**
143
 * Client-side call bridge for service method invocation
144
 */
145
public interface ClientCallBridge {
146
    /** Create request packet from method parameters */
147
    Packet createRequestPacket(JavaCallInfo callInfo);
148
    
149
    /** Extract return value from response packet */
150
    JavaCallInfo readResponse(Packet response, JavaCallInfo callInfo) throws Throwable;
151
    
152
    /** Get method information */
153
    Method getMethod();
154
    
155
    /** Get operation name */
156
    QName getOperationName();
157
    
158
    /** Check if operation is one-way */
159
    boolean isOneWay();
160
}
161
```
162

163
### Java Call Information
164

165
Method call information container for databinding operations.
166

167
```java { .api }
168
/**
169
 * Container for Java method call information and parameters
170
 */
171
public final class JavaCallInfo {
172
    /** Create call info for method */
173
    public static JavaCallInfo create(Method method, Object[] parameters);
174
    
175
    /** Get method being called */
176
    public Method getMethod();
177
    
178
    /** Get method parameters */
179
    public Object[] getParameters();
180
    
181
    /** Set method parameters */
182
    public void setParameters(Object[] parameters);
183
    
184
    /** Get return value */
185
    public Object getReturnValue();
186
    
187
    /** Set return value */
188
    public void setReturnValue(Object returnValue);
189
    
190
    /** Get exception thrown */
191
    public Throwable getException();
192
    
193
    /** Set exception */
194
    public void setException(Throwable exception);
195
    
196
    /** Get parameter at index */
197
    public Object getParameter(int index);
198
    
199
    /** Set parameter at index */
200
    public void setParameter(int index, Object value);
201
}
202
```
203

204
### XML Bridge System
205

206
Low-level XML serialization bridges for individual type marshalling.
207

208
```java { .api }
209
/**
210
 * Bridge for marshalling/unmarshalling individual types
211
 */
212
package com.sun.xml.ws.spi.db;
213
public interface XMLBridge<T> {
214
    /** Marshal object to XMLStreamWriter */
215
    void marshal(T object, XMLStreamWriter output) throws XMLStreamException;
216
    
217
    /** Marshal object to Result */
218
    void marshal(T object, Result result) throws JAXBException;
219
    
220
    /** Marshal object to ContentHandler */
221
    void marshal(T object, ContentHandler contentHandler) throws JAXBException;
222
    
223
    /** Unmarshal from XMLStreamReader */
224
    T unmarshal(XMLStreamReader input) throws JAXBException;
225
    
226
    /** Unmarshal from Source */
227
    T unmarshal(Source source) throws JAXBException;
228
    
229
    /** Get type information */
230
    TypeInfo getTypeInfo();
231
    
232
    /** Check if type supports marshalling to Element */
233
    boolean supportElementProperty();
234
}
235

236
/**
237
 * Bridge for repeated elements (arrays, lists)
238
 */
239
public interface RepeatedElementBridge<T> extends XMLBridge<T> {
240
    /** Marshal collection of items */
241
    void marshal(Iterable<T> collection, XMLStreamWriter output) throws XMLStreamException;
242
    
243
    /** Unmarshal to collection */
244
    Collection<T> unmarshal(XMLStreamReader input, Collection<T> collection) throws JAXBException;
245
}
246
```
247

248
### Binding Context and Providers
249

250
Binding context management and provider SPI for pluggable databinding implementations.
251

252
```java { .api }
253
/**
254
 * Binding context providing access to databinding services
255
 */
256
public interface BindingContext {
257
    /** Create bridge for type */
258
    XMLBridge createBridge(TypeInfo typeInfo);
259
    
260
    /** Create fragment bridge for inner types */
261
    XMLBridge createFragmentBridge();
262
    
263
    /** Get JAXB context if available */
264
    JAXBContext getJAXBContext();
265
    
266
    /** Get known types */
267
    QName[] getKnownTypes();
268
    
269
    /** Create marshaller */
270
    Marshaller createMarshaller() throws JAXBException;
271
    
272
    /** Create unmarshaller */
273
    Unmarshaller createUnmarshaller() throws JAXBException;
274
    
275
    /** Create schema generator */
276
    void generateSchema(SchemaOutputResolver resolver) throws IOException;
277
    
278
    /** Get type information for class */
279
    TypeInfo getTypeInfo(Class<?> type);
280
}
281

282
/**
283
 * SPI for custom databinding providers
284
 */
285
public interface DatabindingProvider {
286
    /** Check if provider supports the databinding mode */
287
    boolean isFor(String databindingMode);
288
    
289
    /** Initialize provider with properties */
290
    void init(Map<String, Object> properties);
291
    
292
    /** Create databinding instance */
293
    Databinding create(DatabindingConfig config);
294
}
295

296
/**
297
 * Factory SPI for binding contexts
298
 */
299
public interface BindingContextFactory {
300
    /** Create binding context */
301
    BindingContext newContext(JAXBContext jaxbContext);
302
    
303
    /** Create binding context with type information */
304
    BindingContext newContext(BindingInfo bindingInfo);
305
    
306
    /** Create binding context for known types */
307
    BindingContext newContext(Class<?>... knownTypes) throws JAXBException;
308
}
309
```
310

311
### Property Access System
312

313
Property accessor system for efficient field/property access during databinding.
314

315
```java { .api }
316
/**
317
 * Efficient property access interface
318
 */
319
public interface PropertyAccessor {
320
    /** Get property value from object */
321
    Object get(Object bean) throws AccessorException;
322
    
323
    /** Set property value on object */
324
    void set(Object bean, Object value) throws AccessorException;
325
    
326
    /** Get property type */
327
    Class<?> getType();
328
    
329
    /** Get property name */
330
    String getName();
331
    
332
    /** Check if property is readable */
333
    boolean isReadable();
334
    
335
    /** Check if property is writable */
336
    boolean isWritable();
337
}
338

339
/**
340
 * Factory for creating property accessors
341
 */
342
public abstract class PropertyAccessorFactory {
343
    /** Create accessor for field */
344
    public abstract PropertyAccessor createFieldAccessor(Class<?> beanClass, Field field);
345
    
346
    /** Create accessor for property (getter/setter) */
347
    public abstract PropertyAccessor createPropertyAccessor(Class<?> beanClass, Method getter, Method setter);
348
    
349
    /** Get default factory instance */
350
    public static PropertyAccessorFactory getDefault();
351
}
352
```
353

354
### Standard Implementations
355

356
Default implementations provided by JAX-WS RI.
357

358
```java { .api }
359
/**
360
 * Default JAXB databinding provider implementation
361
 */
362
package com.sun.xml.ws.db;
363
public final class DatabindingProviderImpl implements DatabindingProvider {
364
    /** Check if provider handles mode */
365
    public boolean isFor(String databindingMode);
366
    
367
    /** Initialize with properties */
368
    public void init(Map<String, Object> properties);
369
    
370
    /** Create databinding instance */
371
    public Databinding create(DatabindingConfig config);
372
}
373

374
/**
375
 * JAXB RI binding context factory
376
 */
377
package com.sun.xml.ws.db.glassfish;
378
public final class JAXBRIContextFactory implements BindingContextFactory {
379
    /** Create new binding context from JAXB context */
380
    public BindingContext newContext(JAXBContext jaxbContext);
381
    
382
    /** Create binding context with binding info */
383
    public BindingContext newContext(BindingInfo bindingInfo);
384
}
385
```
386

387
**Usage Examples:**
388

389
```java
390
import com.oracle.webservices.api.databinding.*;
391
import com.sun.xml.ws.spi.db.*;
392

393
// Basic databinding configuration
394
DatabindingConfig config = new DatabindingConfig()
395
    .setContractClass(MyServiceInterface.class)
396
    .setEndpointClass(MyServiceImpl.class)
397
    .setDatabindingMode(DatabindingMode.glassfish_jaxb);
398

399
// Create databinding instance
400
DatabindingFactory factory = DatabindingFactory.newInstance();
401
Databinding databinding = factory.createDatabinding(config);
402

403
// Server-side call bridge usage
404
Method serviceMethod = MyServiceInterface.class.getMethod("processData", DataRequest.class);
405
JavaCallInfo callInfo = JavaCallInfo.create(serviceMethod, new Object[0]);
406
EndpointCallBridge bridge = databinding.createCallBridge(callInfo);
407

408
// Invoke service method
409
Object serviceInstance = new MyServiceImpl();
410
DataRequest request = new DataRequest();
411
Object result = bridge.invoke(serviceInstance, request);
412

413
// Client-side call bridge usage
414
ClientCallBridge clientBridge = databinding.createCallBridge(callInfo);
415
JavaCallInfo clientCallInfo = JavaCallInfo.create(serviceMethod, new Object[]{ request });
416

417
// Create request packet
418
Packet requestPacket = clientBridge.createRequestPacket(clientCallInfo);
419

420
// Process response (after receiving response packet)
421
JavaCallInfo responseInfo = clientBridge.readResponse(responsePacket, clientCallInfo);
422
Object returnValue = responseInfo.getReturnValue();
423

424
// Custom databinding provider
425
public class MyDatabindingProvider implements DatabindingProvider {
426
    public boolean isFor(String databindingMode) {
427
        return "custom".equals(databindingMode);
428
    }
429
    
430
    public void init(Map<String, Object> properties) {
431
        // Initialize provider
432
    }
433
    
434
    public Databinding create(DatabindingConfig config) {
435
        return new MyCustomDatabinding(config);
436
    }
437
}
438

439
// XML Bridge usage for individual types
440
TypeInfo typeInfo = new TypeInfo(DataRequest.class);
441
XMLBridge<DataRequest> bridge = databinding.createBridge(typeInfo);
442

443
// Marshal to XML
444
StringWriter writer = new StringWriter();
445
XMLStreamWriter xmlWriter = XMLOutputFactory.newInstance().createXMLStreamWriter(writer);
446
bridge.marshal(request, xmlWriter);
447
String xml = writer.toString();
448

449
// Unmarshal from XML
450
StringReader reader = new StringReader(xml);
451
XMLStreamReader xmlReader = XMLInputFactory.newInstance().createXMLStreamReader(reader);
452
DataRequest unmarshalled = bridge.unmarshal(xmlReader);
453

454
// Advanced databinding configuration with features
455
DatabindingConfig advancedConfig = new DatabindingConfig()
456
    .setContractClass(MyServiceInterface.class)
457
    .setDatabindingMode(DatabindingMode.glassfish_jaxb)
458
    .setFeatures(new UsesJAXBContextFeature(createCustomJAXBContext()))
459
    .setMetadataReader(new ExternalMetadataReader());
460

461
// Property accessor usage
462
PropertyAccessorFactory accessorFactory = PropertyAccessorFactory.getDefault();
463
Field nameField = DataRequest.class.getDeclaredField("name");
464
PropertyAccessor nameAccessor = accessorFactory.createFieldAccessor(DataRequest.class, nameField);
465

466
// Use accessor
467
DataRequest obj = new DataRequest();
468
nameAccessor.set(obj, "value");
469
String name = (String) nameAccessor.get(obj);
470

471
// Binding context for low-level operations
472
BindingContextFactory contextFactory = new JAXBRIContextFactory();
473
BindingContext bindingContext = contextFactory.newContext(DataRequest.class, DataResponse.class);
474

475
// Create bridge from binding context
476
XMLBridge<DataRequest> contextBridge = bindingContext.createBridge(new TypeInfo(DataRequest.class));
477
```