0
# Apache Avro Compiler
1

2
Apache Avro Compiler provides comprehensive code generation capabilities for the Avro data serialization system. It transforms Avro schema definitions and IDL (Interface Definition Language) files into Java classes, enabling type-safe serialization and deserialization of data with schema evolution support.
3

4
## Package Information
5

6
- **Package Name**: avro-compiler
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `<dependency><groupId>org.apache.avro</groupId><artifactId>avro-compiler</artifactId><version>1.12.0</version></dependency>`
10

11
## Core Imports
12

13
```java
14
import org.apache.avro.compiler.specific.SpecificCompiler;
15
import org.apache.avro.compiler.specific.SchemaTask;
16
import org.apache.avro.compiler.specific.ProtocolTask;
17
import org.apache.avro.compiler.schema.Schemas;
18
import org.apache.avro.compiler.schema.SchemaVisitor;
19
import org.apache.avro.compiler.schema.SchemaVisitorAction;
20
import org.apache.avro.compiler.schema.CloningVisitor;
21
import org.apache.avro.compiler.idl.ResolvingVisitor;
22
import org.apache.avro.compiler.idl.IsResolvedSchemaVisitor;
23
import org.apache.avro.generic.GenericData.StringType;
24
```
25

26
## Basic Usage
27

28
```java
29
import org.apache.avro.Schema;
30
import org.apache.avro.compiler.specific.SpecificCompiler;
31
import java.io.File;
32
import java.io.IOException;
33

34
// Compile a schema file to Java classes
35
File schemaFile = new File("user.avsc");
36
File outputDir = new File("src/main/java");
37

38
Schema.Parser parser = new Schema.Parser();
39
Schema schema = parser.parse(schemaFile);
40

41
SpecificCompiler compiler = new SpecificCompiler(schema);
42
compiler.compileToDestination(schemaFile, outputDir);
43

44
// Or use static convenience methods
45
SpecificCompiler.compileSchema(schemaFile, outputDir);
46
```
47

48
## Architecture
49

50
The Avro Compiler is built around several key components:
51

52
- **Code Generation Engine**: `SpecificCompiler` class that generates Java code from schemas and protocols
53
- **Build Integration**: Ant tasks (`SchemaTask`, `ProtocolTask`) for build system integration
54
- **Schema Utilities**: `Schemas` utility class for schema traversal and manipulation
55
- **Visitor Pattern**: `SchemaVisitor` interface for custom schema processing
56
- **Template Engine**: Apache Velocity integration for customizable code generation
57
- **IDL Processing**: Support for Avro IDL parsing and compilation (deprecated, use avro-idl)
58

59
## Capabilities
60

61
### Code Generation from Schemas
62

63
Core functionality for generating Java classes from Avro schemas. Supports customizable field visibility, getter/setter generation, and logical type conversions.
64

65
```java { .api }
66
// Constructors for schema compilation
67
SpecificCompiler(Schema schema);
68
SpecificCompiler(Collection<Schema> schemas);
69
SpecificCompiler(Iterable<Schema> schemas);
70

71
// Main compilation method
72
void compileToDestination(File src, File dst) throws IOException;
73

74
// Static convenience methods
75
static void compileSchema(File src, File dest) throws IOException;
76
static void compileSchema(File[] srcFiles, File dest) throws IOException;
77
```
78

79
[Schema Code Generation](./schema-code-generation.md)
80

81
### Code Generation from Protocols
82

83
Generate Java interfaces and classes from Avro protocol definitions, supporting RPC-style service definitions.
84

85
```java { .api }
86
// Constructor for protocol compilation
87
SpecificCompiler(Protocol protocol);
88

89
// Static convenience methods for protocols
90
static void compileProtocol(File src, File dest) throws IOException;
91
static void compileProtocol(File[] srcFiles, File dest) throws IOException;
92
```
93

94
[Protocol Code Generation](./protocol-code-generation.md)
95

96
### Build System Integration
97

98
Ant tasks for integrating Avro compilation into build processes, with support for filesets and batch processing.
99

100
```java { .api }
101
// Ant task for schema compilation
102
public class SchemaTask extends ProtocolTask {
103
    static void main(String[] args) throws IOException;
104
}
105

106
// Base Ant task for protocol compilation
107
public class ProtocolTask extends Task {
108
    void setFile(File file);
109
    void setDestdir(File dir);
110
    void execute() throws BuildException;
111
}
112
```
113

114
[Build Integration](./build-integration.md)
115

116
### Schema Manipulation Utilities
117

118
Utility functions for schema traversal, cloning, and manipulation operations.
119

120
```java { .api }
121
// Schema traversal and visiting
122
static <T> T visit(Schema start, SchemaVisitor<T> visitor);
123

124
// Schema utility operations
125
static void copyAliases(Schema from, Schema to);
126
static void copyLogicalTypes(Schema from, Schema to);
127
static boolean hasGeneratedJavaClass(Schema schema);
128
static String getJavaClassName(Schema schema);
129
```
130

131
[Schema Utilities](./schema-utilities.md)
132

133
### Customization and Configuration
134

135
Configuration options for controlling code generation behavior, including field visibility, annotations, and template customization.
136

137
```java { .api }
138
// Field visibility configuration
139
void setFieldVisibility(FieldVisibility fieldVisibility);
140
boolean publicFields();
141
boolean privateFields();
142

143
// Getter/setter configuration  
144
boolean isCreateSetters();
145
void setCreateSetters(boolean createSetters);
146
void setCreateOptionalGetters(boolean createOptionalGetters);
147
boolean isGettersReturnOptional();
148
void setGettersReturnOptional(boolean gettersReturnOptional);
149
void setOptionalGettersForNullableFieldsOnly(boolean optionalGettersForNullableFieldsOnly);
150

151
// String type configuration
152
void setStringType(StringType stringType);
153
StringType getStringType();
154

155
// Logical type support
156
void setEnableDecimalLogicalType(boolean enableDecimalLogicalType);
157
void addCustomConversion(Class<?> conversionClass);
158
```
159

160
[Configuration Options](./configuration.md)
161

162
## Common Types
163

164
```java { .api }
165
// Field visibility options
166
enum FieldVisibility {
167
    PUBLIC, PRIVATE
168
}
169

170
// String type options (from org.apache.avro.generic.GenericData)
171
enum StringType {
172
    CharSequence, String, Utf8
173
}
174

175
// Schema visitor for traversal operations
176
interface SchemaVisitor<T> {
177
    SchemaVisitorAction visitTerminal(Schema terminal);
178
    SchemaVisitorAction visitNonTerminal(Schema nonTerminal);
179
    SchemaVisitorAction afterVisitNonTerminal(Schema nonTerminal);
180
    T get();
181
}
182

183
// Actions for controlling schema traversal
184
enum SchemaVisitorAction {
185
    CONTINUE, SKIP_SUBTREE, SKIP_SIBLINGS, TERMINATE
186
}
187

188
// Built-in visitor implementations
189
class CloningVisitor implements SchemaVisitor<Schema> {
190
    CloningVisitor(Schema root);
191
    CloningVisitor(PropertyCopier copyProperties, boolean copyDocs, Schema root);
192
}
193

194
// Note: The following visitor classes are in org.apache.avro.compiler.idl package
195
class ResolvingVisitor implements SchemaVisitor<Schema> {
196
    ResolvingVisitor(Schema root, IdentityHashMap<Schema, Schema> replace,
197
                    Function<String, Schema> symbolTable);
198
}
199

200
class IsResolvedSchemaVisitor implements SchemaVisitor<Boolean> {
201
    IsResolvedSchemaVisitor();
202
}
203
```