0
# Programmatic API
1

2
The JAXB XJC programmatic API provides type-safe Java interfaces for embedding schema compilation in applications, build tools, and IDEs with full control over the compilation process.
3

4
## Capabilities
5

6
### Main API Entry Point
7

8
Central factory class for creating schema compilers and utility functions.
9

10
```java { .api }
11
/**
12
 * Entry point to the programmatic API for schema compiler (XJC)
13
 */
14
public final class XJC {
15
    /**
16
     * Gets a fresh SchemaCompiler instance
17
     * @return always return non-null SchemaCompiler object
18
     */
19
    public static SchemaCompiler createSchemaCompiler();
20
    
21
    /**
22
     * Computes namespace URI to package name conversion per JAXB spec
23
     * @param namespaceUri Namespace URI. Can be empty but must not be null
24
     * @return Java package name or null if conversion fails
25
     */
26
    public static String getDefaultPackageName(String namespaceUri);
27
}
28
```
29

30
**Usage Example:**
31

32
```java
33
import com.sun.tools.xjc.api.XJC;
34
import com.sun.tools.xjc.api.SchemaCompiler;
35

36
// Create new compiler instance
37
SchemaCompiler compiler = XJC.createSchemaCompiler();
38

39
// Convert namespace to package name
40
String packageName = XJC.getDefaultPackageName("http://example.com/schema");
41
// Returns: "com.example.schema"
42
```
43

44
### Schema Compilation Interface
45

46
Core interface for parsing schemas and controlling compilation process.
47

48
```java { .api }
49
/**
50
 * Schema-to-Java compilation interface with full configuration options
51
 */
52
public interface SchemaCompiler {
53
    /**
54
     * Get SAX ContentHandler for parsing schemas
55
     * @param systemId System identifier for the schema
56
     * @return ContentHandler for SAX parsing
57
     */
58
    ContentHandler getParserHandler(String systemId);
59
    
60
    /**
61
     * Parse schema from InputSource
62
     * @param source InputSource containing schema content
63
     */
64
    void parseSchema(InputSource source);
65
    
66
    /**
67
     * Parse schema from DOM Element
68
     * @param systemId System identifier for the schema
69
     * @param element DOM element containing schema
70
     */
71
    void parseSchema(String systemId, Element element);
72
    
73
    /**
74
     * Parse schema from XMLStreamReader
75
     * @param systemId System identifier for the schema  
76
     * @param reader StAX XMLStreamReader positioned at schema
77
     */
78
    void parseSchema(String systemId, XMLStreamReader reader);
79
    
80
    /**
81
     * Set target JAXB specification version
82
     * @param version Target specification version
83
     */
84
    void setTargetVersion(SpecVersion version);
85
    
86
    /**
87
     * Set error listener for compilation messages
88
     * @param errorListener Listener for errors, warnings, and info messages
89
     */
90
    void setErrorListener(ErrorListener errorListener);
91
    
92
    /**
93
     * Set entity resolver for schema imports/includes
94
     * @param entityResolver Resolver for external entities
95
     */
96
    void setEntityResolver(EntityResolver entityResolver);
97
    
98
    /**
99
     * Set default package name for generated classes
100
     * @param packageName Package name for classes without explicit namespace mapping
101
     */
102
    void setDefaultPackageName(String packageName);
103
    
104
    /**
105
     * Force all generated classes into specified package
106
     * @param packageName Package name to use for all generated classes
107
     */
108
    void forcePackageName(String packageName);
109
    
110
    /**
111
     * Set custom class name allocation strategy
112
     * @param allocator Custom allocator for resolving class name conflicts
113
     */
114
    void setClassNameAllocator(ClassNameAllocator allocator);
115
    
116
    /**
117
     * Clear all parsed schemas and reset compiler state
118
     */
119
    void resetSchema();
120
    
121
    /**
122
     * Compile parsed schemas and create binding model
123
     * @return S2JJAXBModel containing compilation results, or null if compilation failed
124
     */
125
    S2JJAXBModel bind();
126
    
127
    /**
128
     * Get compilation options (deprecated - for compatibility)
129
     * @return Options object
130
     * @deprecated Use specific setter methods instead
131
     */
132
    @Deprecated
133
    Options getOptions();
134
}
135
```
136

137
**Usage Example:**
138

139
```java
140
import com.sun.tools.xjc.api.*;
141
import javax.xml.transform.stream.StreamSource;
142
import org.xml.sax.InputSource;
143
import java.io.FileInputStream;
144

145
// Create and configure compiler
146
SchemaCompiler compiler = XJC.createSchemaCompiler();
147
compiler.setDefaultPackageName("com.example.generated");
148
compiler.setErrorListener(new MyErrorListener());
149

150
// Parse schema from file
151
InputSource source = new InputSource(new FileInputStream("schema.xsd"));
152
source.setSystemId("schema.xsd");
153
compiler.parseSchema(source);
154

155
// Parse additional schema from URL
156
compiler.parseSchema(new InputSource("http://example.com/common.xsd"));
157

158
// Compile schemas
159
S2JJAXBModel model = compiler.bind();
160
if (model != null) {
161
    // Generate code
162
    JCodeModel codeModel = model.generateCode(null, errorListener);
163
    codeModel.build(new FileCodeWriter(outputDir));
164
}
165
```
166

167
### Compilation Result Model
168

169
Interface representing the result of schema-to-Java compilation.
170

171
```java { .api }
172
/**
173
 * Schema-to-Java compilation result with code generation capabilities
174
 */
175
public interface S2JJAXBModel extends JAXBModel {
176
    /**
177
     * Get mapping information for a specific XML element
178
     * @param elementName QName of the XML element
179
     * @return Mapping information or null if not found
180
     */
181
    Mapping get(QName elementName);
182
    
183
    /**
184
     * Get all generated ObjectFactory classes
185
     * @return List of JClass representing ObjectFactory classes
186
     */
187
    List<JClass> getAllObjectFactories();
188
    
189
    /**
190
     * Get all XML-to-Java mappings
191
     * @return Collection of all mapping information
192
     */
193
    Collection<? extends Mapping> getMappings();
194
    
195
    /**
196
     * Get Java type information for XML type
197
     * @param xmlTypeName QName of the XML type
198
     * @return TypeAndAnnotation containing Java type info, or null if not found
199
     */
200
    TypeAndAnnotation getJavaType(QName xmlTypeName);
201
    
202
    /**
203
     * Generate Java source code with optional plugins
204
     * @param extensions Array of plugins to apply during generation
205
     * @param errorListener Listener for generation errors
206
     * @return JCodeModel containing generated classes
207
     * @throws IOException if code generation fails
208
     */
209
    JCodeModel generateCode(Plugin[] extensions, ErrorListener errorListener) throws IOException;
210
}
211

212
/**
213
 * Base interface for JAXB compilation models
214
 */
215
public interface JAXBModel {
216
    /**
217
     * Get list of generated class names
218
     * @return List of fully qualified class names
219
     * @deprecated Use S2JJAXBModel methods instead
220
     */
221
    @Deprecated
222
    List<String> getClassList();
223
}
224
```
225

226
### Error Handling Interface
227

228
Interface for handling compilation errors, warnings, and informational messages.
229

230
```java { .api }
231
/**
232
 * Error handling interface for programmatic API usage
233
 */
234
public interface ErrorListener {
235
    /**
236
     * Handle compilation errors
237
     * @param exception SAXParseException containing error details
238
     */
239
    void error(SAXParseException exception);
240
    
241
    /**
242
     * Handle compilation warnings
243
     * @param exception SAXParseException containing warning details
244
     */
245
    void warning(SAXParseException exception);
246
    
247
    /**
248
     * Handle informational messages
249
     * @param exception SAXParseException containing info details
250
     */
251
    void info(SAXParseException exception);
252
}
253
```
254

255
**Usage Example:**
256

257
```java
258
import com.sun.tools.xjc.api.ErrorListener;
259
import org.xml.sax.SAXParseException;
260

261
ErrorListener errorListener = new ErrorListener() {
262
    @Override
263
    public void error(SAXParseException exception) {
264
        System.err.printf("Error at %s:%d:%d - %s%n",
265
            exception.getSystemId(),
266
            exception.getLineNumber(),
267
            exception.getColumnNumber(),
268
            exception.getMessage());
269
    }
270
    
271
    @Override
272
    public void warning(SAXParseException exception) {
273
        System.err.printf("Warning at %s:%d:%d - %s%n",
274
            exception.getSystemId(),
275
            exception.getLineNumber(),
276
            exception.getColumnNumber(),
277
            exception.getMessage());
278
    }
279
    
280
    @Override
281
    public void info(SAXParseException exception) {
282
        System.out.printf("Info: %s%n", exception.getMessage());
283
    }
284
};
285
```
286

287
### API Utility Interfaces
288

289
Supporting interfaces for customizing compilation behavior.
290

291
```java { .api }
292
/**
293
 * Custom class name allocation strategy for resolving conflicts
294
 */
295
public interface ClassNameAllocator {
296
    /**
297
     * Assign class name for given package and suggested name
298
     * @param packageName Package name for the class
299
     * @param className Suggested class name
300
     * @return Final class name to use (may be modified to avoid conflicts)
301
     */
302
    String assignClassName(String packageName, String className);
303
}
304

305
/**
306
 * Information about generated properties
307
 */
308
public interface Property {
309
    /**
310
     * Get property name
311
     * @return Property name in Java
312
     */
313
    String name();
314
    
315
    /**
316
     * Get Java type for the property
317
     * @return JType representing the Java type
318
     */
319
    JType type();
320
    
321
    /**
322
     * Get XML element name for the property
323
     * @return QName of the XML element
324
     */
325
    QName elementName();
326
    
327
    /**
328
     * Get raw XML name
329
     * @return QName of the raw XML name
330
     */
331
    QName rawName();
332
}
333

334
/**
335
 * Type information with annotations
336
 */
337
public interface TypeAndAnnotation {
338
    // Type and annotation information for generated classes
339
}
340

341
/**
342
 * XML to Java mapping information
343
 */
344
public interface Mapping {
345
    // Mapping details between XML schema and Java classes
346
}
347

348
/**
349
 * JAXB specification version enumeration
350
 */
351
public enum SpecVersion {
352
    V2_3("2.3"),
353
    V3_0("3.0");
354
    
355
    public final String version;
356
    
357
    SpecVersion(String version);
358
    public static SpecVersion parse(String token);
359
    public boolean isLaterThan(SpecVersion other);
360
}
361
```
362

363
### Complete Integration Example
364

365
```java
366
import com.sun.tools.xjc.api.*;
367
import com.sun.codemodel.*;
368
import com.sun.codemodel.writer.FileCodeWriter;
369
import org.xml.sax.InputSource;
370
import org.xml.sax.SAXParseException;
371
import javax.xml.namespace.QName;
372
import java.io.*;
373
import java.util.Collection;
374

375
public class XJCIntegration {
376
    
377
    public static void compileSchema(File schemaFile, File outputDir, String packageName) 
378
            throws IOException {
379
        
380
        // Create compiler with error handling
381
        SchemaCompiler compiler = XJC.createSchemaCompiler();
382
        ErrorCollector errorListener = new ErrorCollector();
383
        
384
        // Configure compiler
385
        compiler.setDefaultPackageName(packageName);
386
        compiler.setErrorListener(errorListener);
387
        
388
        // Custom class name allocator
389
        compiler.setClassNameAllocator(new ClassNameAllocator() {
390
            @Override
391
            public String assignClassName(String packageName, String className) {
392
                // Add "Generated" suffix to avoid conflicts
393
                return className + "Generated";
394
            }
395
        });
396
        
397
        // Parse schema
398
        InputSource source = new InputSource(new FileInputStream(schemaFile));
399
        source.setSystemId(schemaFile.toURI().toString());
400
        compiler.parseSchema(source);
401
        
402
        // Check for parsing errors
403
        if (errorListener.hasErrors()) {
404
            throw new IOException("Schema parsing failed with errors");
405
        }
406
        
407
        // Compile schema
408
        S2JJAXBModel model = compiler.bind();
409
        if (model == null) {
410
            throw new IOException("Schema compilation failed");
411
        }
412
        
413
        // Examine generated mappings
414
        Collection<? extends Mapping> mappings = model.getMappings();
415
        System.out.printf("Generated %d mappings%n", mappings.size());
416
        
417
        // Generate code
418
        JCodeModel codeModel = model.generateCode(null, errorListener);
419
        
420
        // Write to filesystem
421
        codeModel.build(new FileCodeWriter(outputDir));
422
        
423
        System.out.printf("Generated code in %s%n", outputDir.getAbsolutePath());
424
    }
425
    
426
    private static class ErrorCollector implements ErrorListener {
427
        private boolean hasErrors = false;
428
        
429
        @Override
430
        public void error(SAXParseException exception) {
431
            hasErrors = true;
432
            System.err.println("Error: " + exception.getMessage());
433
        }
434
        
435
        @Override
436
        public void warning(SAXParseException exception) {
437
            System.err.println("Warning: " + exception.getMessage());
438
        }
439
        
440
        @Override
441
        public void info(SAXParseException exception) {
442
            System.out.println("Info: " + exception.getMessage());
443
        }
444
        
445
        public boolean hasErrors() {
446
            return hasErrors;
447
        }
448
    }
449
}
450
```