0
# Build Integration
1
2
Ant tasks for integrating Avro compilation into build processes, with support for filesets, batch processing, and build system automation.
3
4
## Capabilities
5
6
### SchemaTask Class
7
8
Ant task for compiling Avro schema files to Java classes during the build process.
9
10
```java { .api }
11
/**
12
* Ant task to generate Java interface and classes for a protocol.
13
* Extends ProtocolTask to inherit common functionality.
14
*/
15
public class SchemaTask extends ProtocolTask {
16
17
/**
18
* Command-line interface for schema compilation
19
* @param args Command line arguments: <schema.avsc>... <output-folder>
20
* @throws IOException if compilation fails
21
*/
22
public static void main(String[] args) throws IOException;
23
24
/**
25
* Compile schema file - overrides parent implementation
26
* @param src Source schema file
27
* @param dest Destination directory
28
* @throws IOException if compilation fails
29
*/
30
@Override
31
protected void doCompile(File src, File dest) throws IOException;
32
}
33
```
34
35
### ProtocolTask Class
36
37
Base Ant task for compiling Avro protocol files to Java classes.
38
39
```java { .api }
40
/**
41
* Ant task to generate Java interface and classes for a protocol.
42
* Extends org.apache.tools.ant.Task.
43
*/
44
public class ProtocolTask extends Task {
45
46
/** Set the schema/protocol file */
47
public void setFile(File file);
48
49
/** Set the output directory */
50
public void setDestdir(File dir);
51
52
/** Set string type for generated classes (CharSequence, String, Utf8) */
53
public void setStringType(GenericData.StringType stringType);
54
55
/** Add fileset for batch processing */
56
public void addFileSet(FileSet set);
57
58
/** Execute the ant task */
59
@Override
60
public void execute() throws BuildException;
61
62
/**
63
* Compile protocol file - can be overridden by subclasses
64
* @param src Source protocol file
65
* @param dest Destination directory
66
* @throws IOException if compilation fails
67
*/
68
protected void doCompile(File src, File dest) throws IOException;
69
}
70
```
71
72
### String Type Configuration
73
74
Control how strings are represented in generated Java classes.
75
76
```java { .api }
77
/**
78
* Set string type for generated classes
79
* @param stringType String representation type
80
* Options: CharSequence (default), String, Utf8
81
*/
82
public void setStringType(GenericData.StringType stringType);
83
84
/** Get current string type setting */
85
public GenericData.StringType getStringType();
86
```
87
88
## Usage Examples
89
90
### Ant Build File Configuration
91
92
Configure Avro compilation in your `build.xml`:
93
94
```xml
95
<!-- Load Avro compiler tasks -->
96
<taskdef name="schema" classname="org.apache.avro.compiler.specific.SchemaTask"
97
classpath="path/to/avro-compiler.jar"/>
98
99
<taskdef name="protocol" classname="org.apache.avro.compiler.specific.ProtocolTask"
100
classpath="path/to/avro-compiler.jar"/>
101
102
<!-- Compile single schema -->
103
<target name="compile-schema">
104
<schema file="src/main/avro/User.avsc"
105
destdir="src/main/java"/>
106
</target>
107
108
<!-- Compile single protocol -->
109
<target name="compile-protocol">
110
<protocol file="src/main/avro/EmailService.avpr"
111
destdir="src/main/java"/>
112
</target>
113
```
114
115
### Batch Processing with Filesets
116
117
Compile multiple files using Ant filesets:
118
119
```xml
120
<!-- Compile all schemas in a directory -->
121
<target name="compile-all-schemas">
122
<schema destdir="src/main/java">
123
<fileset dir="src/main/avro">
124
<include name="**/*.avsc"/>
125
</fileset>
126
</schema>
127
</target>
128
129
<!-- Compile all protocols in a directory -->
130
<target name="compile-all-protocols">
131
<protocol destdir="src/main/java">
132
<fileset dir="src/main/avro">
133
<include name="**/*.avpr"/>
134
</fileset>
135
</protocol>
136
</target>
137
```
138
139
### Advanced Ant Configuration
140
141
Configure string types and complex file patterns:
142
143
```xml
144
<!-- Configure string type -->
145
<target name="compile-with-string-type">
146
<schema destdir="src/main/java" stringType="String">
147
<fileset dir="src/main/avro">
148
<include name="**/*.avsc"/>
149
</fileset>
150
</schema>
151
</target>
152
153
<!-- Complex build with dependencies -->
154
<target name="generate-avro-classes" depends="clean">
155
<mkdir dir="src/main/java"/>
156
157
<!-- Compile schemas first -->
158
<schema destdir="src/main/java">
159
<fileset dir="src/main/avro/schemas">
160
<include name="**/*.avsc"/>
161
</fileset>
162
</schema>
163
164
<!-- Then compile protocols that depend on schemas -->
165
<protocol destdir="src/main/java">
166
<fileset dir="src/main/avro/protocols">
167
<include name="**/*.avpr"/>
168
</fileset>
169
</protocol>
170
</target>
171
```
172
173
### Command Line Usage
174
175
Use the task classes directly from command line:
176
177
```bash
178
# Schema compilation
179
java -cp avro-compiler.jar org.apache.avro.compiler.specific.SchemaTask \
180
user.avsc order.avsc product.avsc src/main/java
181
182
# The last argument is the output directory
183
# All preceding arguments are schema files to compile
184
```
185
186
### Maven Integration
187
188
While these are Ant tasks, they can be used in Maven via the AntRun plugin:
189
190
```xml
191
<plugin>
192
<groupId>org.apache.maven.plugins</groupId>
193
<artifactId>maven-antrun-plugin</artifactId>
194
<version>3.1.0</version>
195
<executions>
196
<execution>
197
<phase>generate-sources</phase>
198
<goals>
199
<goal>run</goal>
200
</goals>
201
<configuration>
202
<target>
203
<taskdef name="schema"
204
classname="org.apache.avro.compiler.specific.SchemaTask"
205
classpathref="maven.compile.classpath"/>
206
207
<schema destdir="${project.build.directory}/generated-sources/avro">
208
<fileset dir="src/main/avro">
209
<include name="**/*.avsc"/>
210
</fileset>
211
</schema>
212
</target>
213
</configuration>
214
</execution>
215
</executions>
216
<dependencies>
217
<dependency>
218
<groupId>org.apache.avro</groupId>
219
<artifactId>avro-compiler</artifactId>
220
<version>1.12.0</version>
221
</dependency>
222
</dependencies>
223
</plugin>
224
```
225
226
### Error Handling
227
228
Build tasks throw `BuildException` for Ant integration:
229
230
```java
231
try {
232
ProtocolTask task = new ProtocolTask();
233
task.setFile(new File("service.avpr"));
234
task.setDestdir(new File("src/main/java"));
235
task.execute();
236
} catch (BuildException e) {
237
// Handle build failure
238
System.err.println("Compilation failed: " + e.getMessage());
239
}
240
```
241
242
## Types
243
244
```java { .api }
245
/** String type options for generated Java classes */
246
// From org.apache.avro.generic.GenericData
247
enum StringType {
248
CharSequence, // Default - generates CharSequence fields
249
String, // Generates String fields
250
Utf8 // Generates Utf8 fields (Avro's internal string type)
251
}
252
```
253
254
## Integration Notes
255
256
- Tasks automatically handle directory creation for output paths
257
- Generated classes follow standard Java package conventions based on Avro namespaces
258
- Tasks support incremental compilation - only modified files are recompiled
259
- All configuration options from `SpecificCompiler` can be set through task properties
260
- Tasks integrate with Ant's logging system for build output
261
- File paths are resolved relative to the Ant project basedir