0
# Transform Integration
1

2
Jakarta XML Binding provides utilities for seamless integration with JAXP Transform API, enabling JAXB objects to be used as Sources and Results in XSLT transformations and other XML processing pipelines.
3

4
## Capabilities
5

6
### JAXBSource - JAXB as Transform Source
7

8
JAXBSource allows JAXB objects to be used as `javax.xml.transform.Source` instances, enabling them to be input into XSLT transformations and other XML processing operations.
9

10
```java { .api }
11
public class JAXBSource extends javax.xml.transform.sax.SAXSource {
12
    /**
13
     * Creates a new Source for the given content object using JAXBContext.
14
     * 
15
     * @param context JAXBContext that was used to create contentObject
16
     * @param contentObject An instance of a JAXB-generated class to be marshalled
17
     * @throws JAXBException if an error is encountered while creating the JAXBSource
18
     */
19
    public JAXBSource(JAXBContext context, Object contentObject) throws JAXBException;
20
    
21
    /**
22
     * Creates a new Source for the given content object using Marshaller.
23
     * 
24
     * @param marshaller A marshaller instance to marshal contentObject
25
     * @param contentObject An instance of a JAXB-generated class to be marshalled
26
     * @throws JAXBException if an error is encountered while creating the JAXBSource
27
     */
28
    public JAXBSource(Marshaller marshaller, Object contentObject) throws JAXBException;
29
}
30
```
31

32
**Usage Examples:**
33

34
```java
35
import jakarta.xml.bind.*;
36
import jakarta.xml.bind.util.JAXBSource;
37
import javax.xml.transform.*;
38
import javax.xml.transform.stream.*;
39

40
// Create JAXB object to transform
41
Person person = new Person("Alice", 30);
42
JAXBContext context = JAXBContext.newInstance(Person.class);
43

44
// Create JAXBSource for XSLT transformation
45
JAXBSource source = new JAXBSource(context, person);
46

47
// Set up XSLT transformation
48
TransformerFactory tf = TransformerFactory.newInstance();
49
Transformer transformer = tf.newTransformer(new StreamSource("person-to-html.xsl"));
50

51
// Transform JAXB object to HTML
52
transformer.transform(source, new StreamResult(System.out));
53

54
// Using with custom Marshaller
55
Marshaller marshaller = context.createMarshaller();
56
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
57
JAXBSource customSource = new JAXBSource(marshaller, person);
58
transformer.transform(customSource, new StreamResult("output.html"));
59
```
60

61
### JAXBResult - Transform Result to JAXB
62

63
JAXBResult allows transformation results to be unmarshalled directly into JAXB objects, enabling XSLT transformations to produce Java objects.
64

65
```java { .api }
66
public class JAXBResult extends javax.xml.transform.sax.SAXResult {
67
    /**
68
     * Creates a new instance that uses the specified JAXBContext to unmarshal.
69
     * 
70
     * @param context The JAXBContext used to create the necessary Unmarshaller
71
     * @throws JAXBException if an error is encountered while creating the JAXBResult
72
     */
73
    public JAXBResult(JAXBContext context) throws JAXBException;
74
    
75
    /**
76
     * Creates a new instance that uses the specified Unmarshaller.
77
     * 
78
     * @param unmarshaller The unmarshaller to use for unmarshalling
79
     * @throws JAXBException if an error is encountered while creating the JAXBResult
80
     */
81
    public JAXBResult(Unmarshaller unmarshaller) throws JAXBException;
82
    
83
    /**
84
     * Gets the unmarshalled object created by the transformation.
85
     * 
86
     * @return Always returns a non-null object
87
     * @throws IllegalStateException if called before an object is unmarshalled
88
     * @throws JAXBException if there is any unmarshalling error
89
     */
90
    public Object getResult() throws JAXBException;
91
}
92
```
93

94
**Usage Examples:**
95

96
```java
97
import jakarta.xml.bind.*;
98
import jakarta.xml.bind.util.JAXBResult;
99
import javax.xml.transform.*;
100
import javax.xml.transform.stream.*;
101

102
// Create JAXBResult for transformation output
103
JAXBContext context = JAXBContext.newInstance(Person.class);
104
JAXBResult result = new JAXBResult(context);
105

106
// Set up XSLT transformation 
107
TransformerFactory tf = TransformerFactory.newInstance();
108
Transformer transformer = tf.newTransformer(new StreamSource("xml-to-person.xsl"));
109

110
// Transform XML document to JAXB object
111
transformer.transform(new StreamSource("input.xml"), result);
112

113
// Get the unmarshalled result
114
Person person = (Person) result.getResult();
115
System.out.println("Transformed person: " + person.getName());
116

117
// Using with custom Unmarshaller
118
Unmarshaller unmarshaller = context.createUnmarshaller();
119
unmarshaller.setSchema(mySchema); // Add validation
120
JAXBResult validatedResult = new JAXBResult(unmarshaller);
121
transformer.transform(new StreamSource("input.xml"), validatedResult);
122
Person validatedPerson = (Person) validatedResult.getResult();
123
```
124

125
### XML Processing Pipeline Integration
126

127
Transform integration utilities enable sophisticated XML processing workflows combining JAXB with other XML technologies.
128

129
**Pipeline Example:**
130

131
```java
132
// Multi-step transformation pipeline
133
JAXBContext context = JAXBContext.newInstance(Order.class, Invoice.class);
134

135
// Step 1: Start with JAXB object
136
Order order = new Order(/* order data */);
137
JAXBSource orderSource = new JAXBSource(context, order);
138

139
// Step 2: Transform order to invoice XML
140
JAXBResult invoiceResult = new JAXBResult(context);
141
Transformer orderToInvoice = TransformerFactory.newInstance()
142
    .newTransformer(new StreamSource("order-to-invoice.xsl"));
143
orderToInvoice.transform(orderSource, invoiceResult);
144

145
// Step 3: Get invoice object
146
Invoice invoice = (Invoice) invoiceResult.getResult();
147

148
// Step 4: Transform invoice to PDF format
149
JAXBSource invoiceSource = new JAXBSource(context, invoice);
150
Transformer invoiceToPdf = TransformerFactory.newInstance()
151
    .newTransformer(new StreamSource("invoice-to-fo.xsl"));
152
invoiceToPdf.transform(invoiceSource, new StreamResult("invoice.fo"));
153
```
154

155
## Types
156

157
### Transform Source and Result Types
158

159
```java { .api }
160
// JAXBSource extends SAXSource but applications should not access SAXSource methods
161
import javax.xml.transform.sax.SAXSource;
162
import javax.xml.transform.sax.SAXResult;
163
import javax.xml.transform.Source;
164
import javax.xml.transform.Result;
165

166
// Core transform interfaces
167
interface Source {
168
    String getSystemId();
169
    void setSystemId(String systemId);
170
}
171

172
interface Result {
173
    String getSystemId();
174
    void setSystemId(String systemId);
175
}
176
```
177

178
**Important Notes:**
179

180
- JAXBSource and JAXBResult extend SAX-based classes as implementation details
181
- Applications should not call methods inherited from SAXSource or SAXResult
182
- Always use the public constructor and getResult() methods provided by these classes
183
- These classes integrate seamlessly with any JAXP-compliant transformation engine