0
# JAXB XJC (XML to Java Compiler)
1

2
JAXB XJC is a comprehensive code generation tool that automatically transforms XML Schema definitions (XSD) into strongly-typed Java classes, enabling seamless XML data binding within Java applications. As part of the Eclipse Implementation of JAXB (Jakarta XML Binding), this tool provides both command-line and programmatic interfaces for enterprise XML processing workflows.
3

4
## Package Information
5

6
- **Package Name**: jaxb-xjc
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.glassfish.jaxb</groupId>
13
    <artifactId>jaxb-xjc</artifactId>
14
    <version>4.0.5</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import com.sun.tools.xjc.api.XJC;
22
import com.sun.tools.xjc.api.SchemaCompiler;
23
import com.sun.tools.xjc.api.S2JJAXBModel;
24
import com.sun.tools.xjc.Driver;
25
```
26

27
For plugin development:
28
```java
29
import com.sun.tools.xjc.Plugin;
30
import com.sun.tools.xjc.outline.Outline;
31
import com.sun.tools.xjc.Options;
32
```
33

34
## Basic Usage
35

36
### Command Line Usage
37

38
```bash
39
# Basic schema compilation
40
xjc schema.xsd
41

42
# Generate into specific package
43
xjc -p com.example.generated schema.xsd
44

45
# Generate into target directory
46
xjc -d target/generated-sources schema.xsd
47

48
# Enable verbose output
49
xjc -verbose schema.xsd
50
```
51

52
### Programmatic Usage
53

54
```java
55
import com.sun.tools.xjc.api.XJC;
56
import com.sun.tools.xjc.api.SchemaCompiler;
57
import com.sun.tools.xjc.api.S2JJAXBModel;
58
import com.sun.tools.xjc.api.ErrorListener;
59
import com.sun.codemodel.JCodeModel;
60
import com.sun.codemodel.writer.FileCodeWriter;
61
import org.xml.sax.InputSource;
62
import org.xml.sax.SAXParseException;
63
import java.io.File;
64

65
// Create schema compiler
66
SchemaCompiler compiler = XJC.createSchemaCompiler();
67

68
// Configure compiler
69
compiler.setDefaultPackageName("com.example.generated");
70
compiler.setErrorListener(new ErrorListener() {
71
    public void error(SAXParseException exception) { /* handle error */ }
72
    public void warning(SAXParseException exception) { /* handle warning */ }
73
    public void info(SAXParseException exception) { /* handle info */ }
74
});
75

76
// Parse schema
77
compiler.parseSchema(new InputSource("schema.xsd"));
78

79
// Compile and generate code
80
S2JJAXBModel model = compiler.bind();
81
JCodeModel codeModel = model.generateCode(null, null);
82

83
// Write generated classes to filesystem
84
codeModel.build(new FileCodeWriter(new File("target/generated")));
85
```
86

87
## Architecture
88

89
JAXB XJC is built around several key architectural components:
90

91
- **Schema Parsing**: Multi-format schema reader supporting XML Schema, DTD, RelaxNG, and WSDL
92
- **Model Building**: Internal object model representing parsed schemas and binding decisions
93
- **Code Generation**: Bean generator producing JAXB-annotated Java classes with proper type safety
94
- **Plugin System**: Extensible architecture allowing custom code generation and model modification
95
- **CLI Interface**: Command-line driver providing comprehensive configuration options
96
- **Programmatic API**: Type-safe Java API for embedding XJC in build tools and applications
97

98
## Capabilities
99

100
### Command Line Interface (CLI)
101

102
Command-line tool for batch processing XML schemas with comprehensive configuration options. Ideal for build scripts and automated code generation workflows.
103

104
```java { .api }
105
public final class Driver {
106
    public static void main(String[] args) throws Exception;
107
    public static int run(String[] args, PrintStream status, PrintStream out) throws Exception;
108
    public static int run(String[] args, XJCListener listener) throws BadCommandLineException;
109
    public static void usage(Options opts, boolean privateUsage);
110
    public static String getBuildID();
111
}
112
```
113

114
[Command Line Interface](./cli.md)
115

116
### Programmatic API
117

118
Type-safe Java API for embedding schema compilation in applications, build tools, and IDEs. Provides full control over compilation process and generated code.
119

120
```java { .api }
121
public final class XJC {
122
    public static SchemaCompiler createSchemaCompiler();
123
    public static String getDefaultPackageName(String namespaceUri);
124
}
125

126
public interface SchemaCompiler {
127
    ContentHandler getParserHandler(String systemId);
128
    void parseSchema(InputSource source);
129
    void parseSchema(String systemId, Element element);
130
    void parseSchema(String systemId, XMLStreamReader reader);
131
    void setTargetVersion(SpecVersion version);
132
    void setErrorListener(ErrorListener errorListener);
133
    void setEntityResolver(EntityResolver entityResolver);
134
    void setDefaultPackageName(String packageName);
135
    void forcePackageName(String packageName);
136
    void setClassNameAllocator(ClassNameAllocator allocator);
137
    void resetSchema();
138
    S2JJAXBModel bind();
139
}
140
```
141

142
[Programmatic API](./programmatic-api.md)
143

144
### Plugin System
145

146
Extensible plugin architecture for customizing code generation, adding annotations, and implementing domain-specific features.
147

148
```java { .api }
149
public abstract class Plugin {
150
    public abstract String getOptionName();
151
    public abstract String getUsage();
152
    public abstract boolean run(Outline outline, Options opt, ErrorHandler errorHandler) throws SAXException;
153
    public int parseArgument(Options opt, String[] args, int i) throws BadCommandLineException, IOException;
154
    public List<String> getCustomizationURIs();
155
    public void onActivated(Options opts) throws BadCommandLineException;
156
    public void postProcessModel(Model model, ErrorHandler errorHandler);
157
}
158
```
159

160
[Plugin System](./plugin-system.md)
161

162
### Code Generation and Customization
163

164
Bean generation system with customizable field rendering and type mapping for generating optimized JAXB classes.
165

166
```java { .api }
167
public interface Outline {
168
    Model getModel();
169
    JCodeModel getCodeModel();
170
    Collection<? extends ClassOutline> getClasses();
171
    ClassOutline getClazz(CClassInfo clazz);
172
    FieldOutline getField(CPropertyInfo fu);
173
    PackageOutline getPackageContext(JPackage _Package);
174
}
175

176
public interface FieldRendererFactory {
177
    FieldRenderer getDefault();
178
    FieldRenderer getArray();
179
    FieldRenderer getList(JClass coreList);
180
    FieldRenderer getSingle();
181
    FieldRenderer getConst(FieldRenderer fallback);
182
}
183
```
184

185
[Code Generation](./code-generation.md)
186

187
### Error Handling and Validation
188

189
Comprehensive error reporting system with configurable error listeners and validation support for schema processing and code generation.
190

191
```java { .api }
192
public interface ErrorListener {
193
    void error(SAXParseException exception);
194
    void warning(SAXParseException exception);
195
    void info(SAXParseException exception);
196
}
197

198
public abstract class ErrorReceiver {
199
    public abstract void error(SAXParseException exception);
200
    public abstract void warning(SAXParseException exception);
201
    public abstract void info(SAXParseException exception);
202
    public void pollAbort() throws AbortException;
203
}
204
```
205

206
[Error Handling](./error-handling.md)
207

208
### Build Tool Integration
209

210
Ant tasks and build system integration components for Maven, Gradle, and other build tools.
211

212
```java { .api }
213
public class XJC2Task extends Task {
214
    // Ant task implementation for XJC
215
}
216

217
public class XJCBase {
218
    // Base class for build tool integration
219
}
220
```
221

222
[Build Integration](./build-integration.md)
223

224
## Types
225

226
### Core Model Types
227

228
```java { .api }
229
public interface S2JJAXBModel extends JAXBModel {
230
    Mapping get(QName elementName);
231
    List<JClass> getAllObjectFactories();
232
    Collection<? extends Mapping> getMappings();
233
    TypeAndAnnotation getJavaType(QName xmlTypeName);
234
    JCodeModel generateCode(Plugin[] extensions, ErrorListener errorListener) throws IOException;
235
}
236

237
public interface JAXBModel {
238
    List<String> getClassList();
239
}
240

241
public class Model implements TypeInfoSet<TypeInfo,CClassInfo,CElementInfo,CEnumLeafInfo> {
242
    public Outline generateCode(Options opt, ErrorReceiver receiver);
243
    public JCodeModel codeModel;
244
}
245
```
246

247
### Configuration Types
248

249
```java { .api }
250
public class Options {
251
    public boolean debugMode;
252
    public boolean verbose;
253
    public boolean quiet;
254
    public boolean readOnly;
255
    public String encoding;
256
    public File targetDir;
257
    public String defaultPackage;
258
    
259
    public int parseArgument(String[] args, int i) throws BadCommandLineException;
260
    public void parseArguments(String[] args) throws BadCommandLineException;
261
    public FieldRendererFactory getFieldRendererFactory();
262
    public void setFieldRendererFactory(FieldRendererFactory frf, Plugin owner);
263
    public ClassLoader getUserClassLoader(ClassLoader parent);
264
}
265
```
266

267
### Outline Types
268

269
```java { .api }
270
public abstract class ClassOutline {
271
    public final CClassInfo target;
272
    public final JDefinedClass ref;
273
    public abstract Outline parent();
274
}
275

276
public abstract class FieldOutline {
277
    // Field-specific outline information
278
}
279

280
public interface PackageOutline {
281
    // Package-specific outline information
282
}
283
```
284

285
### API Utility Types
286

287
```java { .api }
288
public interface Property {
289
    String name();
290
    JType type();
291
    QName elementName();
292
    QName rawName();
293
}
294

295
public interface ClassNameAllocator {
296
    String assignClassName(String packageName, String className);
297
}
298

299
public interface TypeAndAnnotation {
300
    // Type and annotation information
301
}
302

303
public interface Mapping {
304
    // XML to Java mapping information
305
}
306
```
307

308
### Enumeration Types
309

310
```java { .api }
311
public enum SpecVersion {
312
    V2_3("2.3"),
313
    V3_0("3.0");
314
    
315
    public final String version;
316
    
317
    SpecVersion(String version);
318
    public static SpecVersion parse(String token);
319
    public boolean isLaterThan(SpecVersion other);
320
}
321

322
public enum Language {
323
    DTD("DTD", "dtd"),
324
    XMLSCHEMA("XML Schema", "xsd"),
325
    RELAXNG("RELAX NG", "rng"),
326
    RELAXNG_COMPACT("RELAX NG (compact syntax)", "rnc"),
327
    WSDL("WSDL", "wsdl");
328
    
329
    public final String displayName;
330
    public final String[] expectedExtensions;
331
    
332
    Language(String displayName, String... expectedExtensions);
333
}
334
```
335

336
### Exception Types
337

338
```java { .api }
339
public class BadCommandLineException extends Exception {
340
    public BadCommandLineException(String message);
341
    public BadCommandLineException(String message, Throwable cause);
342
}
343

344
public class AbortException extends RuntimeException {
345
    public AbortException();
346
    public AbortException(String message);
347
}
348
```