0
# Apache Avro Maven Plugin
1

2
The Apache Avro Maven Plugin provides comprehensive code generation capabilities for the Avro data serialization system. It enables automatic generation of Java classes from Avro schema files, IDL files, and protocol files, while also supporting reverse engineering of Avro schemas from existing Java classes.
3

4
## Package Information
5

6
- **Package Name**: avro-maven-plugin
7
- **Package Type**: maven-plugin
8
- **Group ID**: org.apache.avro
9
- **Artifact ID**: avro-maven-plugin
10
- **Language**: Java
11
- **Installation**: Add to pom.xml build plugins section
12

13
## Core Maven Coordinates
14

15
```xml { .api }
16
<groupId>org.apache.avro</groupId>
17
<artifactId>avro-maven-plugin</artifactId>
18
<version>1.12.0</version>
19
```
20

21
## Basic Usage
22

23
Add the plugin to your Maven project's `pom.xml`:
24

25
```xml
26
<build>
27
  <plugins>
28
    <plugin>
29
      <groupId>org.apache.avro</groupId>
30
      <artifactId>avro-maven-plugin</artifactId>
31
      <version>1.12.0</version>
32
      <executions>
33
        <execution>
34
          <goals>
35
            <goal>schema</goal>
36
          </goals>
37
        </execution>
38
      </executions>
39
    </plugin>
40
  </plugins>
41
</build>
42
```
43

44
Generate Java classes from Avro schema files in `src/main/avro/`:
45

46
```bash
47
mvn avro:schema
48
```
49

50
## Maven Goals
51

52
### Schema Compilation (avro:schema)
53

54
Generates Java classes from Avro schema files (.avsc).
55

56
```xml { .api }
57
<goal>schema</goal>
58
```
59

60
**Default phase**: `generate-sources`
61
**File pattern**: `**/*.avsc` (configurable via `includes` parameter)
62
**Test file pattern**: `**/*.avsc` (configurable via `testIncludes` parameter)
63
**Input directory**: `${basedir}/src/main/avro`
64
**Output directory**: `${project.build.directory}/generated-sources/avro`
65

66
### IDL Compilation (avro:idl)
67

68
Generates Java classes and interfaces from Avro IDL files (.avdl).
69

70
```xml { .api }
71
<goal>idl</goal>
72
```
73

74
**Default phase**: `generate-sources`
75
**File pattern**: `**/*.avdl` (configurable via `includes` parameter)
76
**Test file pattern**: `**/*.avdl` (configurable via `testIncludes` parameter)
77
**Input directory**: `${basedir}/src/main/avro`
78
**Output directory**: `${project.build.directory}/generated-sources/avro`
79

80
### Protocol Compilation (avro:protocol)
81

82
Generates Java classes and interfaces from Avro protocol files (.avpr).
83

84
```xml { .api }
85
<goal>protocol</goal>
86
```
87

88
**Default phase**: `generate-sources`
89
**File pattern**: `**/*.avpr` (configurable via `includes` parameter)
90
**Test file pattern**: `**/*.avpr` (configurable via `testIncludes` parameter)
91
**Input directory**: `${basedir}/src/main/avro`
92
**Output directory**: `${project.build.directory}/generated-sources/avro`
93

94
### Schema Induction (avro:induce)
95

96
Generates Avro schema (.avsc) or protocol (.avpr) files from existing Java classes.
97

98
```xml { .api }
99
<goal>induce</goal>
100
```
101

102
**Default phase**: `process-classes`
103
**Input type**: Java class files (.java)
104
**Input directory**: `${basedir}/src/main/java` (configurable via `javaSourceDirectories`)
105
**Output directory**: `${project.build.directory}/generated-resources/avro` (configurable via `avroOutputDirectory`)
106
**Output files**: Schema files (.avsc) for classes, protocol files (.avpr) for interfaces
107

108
### Legacy IDL Protocol (avro:idl-protocol)
109

110
Legacy goal for IDL compilation, maintained for backwards compatibility. Identical functionality to `avro:idl`.
111

112
```xml { .api }
113
<goal>idl-protocol</goal>
114
```
115

116
## Configuration Parameters
117

118
### Common Directory Configuration
119
- `sourceDirectory` - Source directory for Avro files (default: `${basedir}/src/main/avro`)
120
- `outputDirectory` - Output directory for generated sources (default: `${project.build.directory}/generated-sources/avro`)
121
- `testSourceDirectory` - Test source directory (default: `${basedir}/src/test/avro`)
122
- `testOutputDirectory` - Test output directory (default: `${project.build.directory}/generated-test-sources/avro`)
123

124
### Code Generation Options
125
- `fieldVisibility` - Field visibility for generated classes: PRIVATE, PUBLIC, PROTECTED (default: PRIVATE)
126
- `stringType` - Java type for Avro strings: CharSequence, String, Utf8 (default: CharSequence)
127
- `createSetters` - Generate setter methods (default: true)
128
- `createOptionalGetters` - Generate getOptional... methods for Java 8+ (default: false)
129
- `gettersReturnOptional` - Generate get... methods returning Optional for Java 8+ (default: false)
130
- `optionalGettersForNullableFieldsOnly` - Optional getters only for nullable fields (default: false)
131
- `createNullSafeAnnotations` - Add JetBrains @Nullable/@NotNull annotations (default: false)
132

133
### Advanced Configuration
134
- `imports` - Files/directories to compile first for imports
135
- `includes` - Ant-like inclusion patterns for source files (default: goal-specific patterns)
136
- `excludes` - Ant-like exclusion patterns for source files (default: empty array)
137
- `testIncludes` - Ant-like inclusion patterns for test files (default: goal-specific patterns)
138
- `testExcludes` - Ant-like exclusion patterns for test files (default: empty array)
139
- `templateDirectory` - Custom Velocity template directory (default: "/org/apache/avro/compiler/specific/templates/java/classic/")
140
- `velocityToolsClassesNames` - Additional Velocity tool classes (default: empty array)
141
- `customConversions` - Custom Conversion implementation classes (default: empty array)
142
- `customLogicalTypeFactories` - Custom LogicalTypeFactory implementation classes (default: empty array)
143
- `enableDecimalLogicalType` - Use Java classes for decimal types (default: false)
144
- `createNullSafeAnnotations` - Add JetBrains @Nullable/@NotNull annotations (default: false)
145

146
### Class Inheritance Configuration
147
- `recordSpecificClass` - Base class for generated record classes (default: org.apache.avro.specific.SpecificRecordBase)
148
- `errorSpecificClass` - Base class for generated error classes (default: org.apache.avro.specific.SpecificExceptionBase)
149

150
### Induce Goal Specific Configuration
151
- `javaSourceDirectories` - Java source directories for schema induction (default: `${basedir}/src/main/java`)
152
- `avroOutputDirectory` - Output directory for induced schemas (default: `${project.build.directory}/generated-resources/avro`)
153
- `encoding` - Output file encoding (default: `${project.build.sourceEncoding}` or system default if not set)
154
- `allowNull` - Use ReflectData.AllowNull for nullable fields (default: false)
155
- `reflectDataImplementation` - Custom ReflectData implementation class (must be subclass of ReflectData)
156

157
## Complete Plugin Configuration Example
158

159
```xml { .api }
160
<plugin>
161
  <groupId>org.apache.avro</groupId>
162
  <artifactId>avro-maven-plugin</artifactId>
163
  <version>1.12.0</version>
164
  <configuration>
165
    <sourceDirectory>${project.basedir}/src/main/avro</sourceDirectory>
166
    <outputDirectory>${project.build.directory}/generated-sources/avro</outputDirectory>
167
    <fieldVisibility>PUBLIC</fieldVisibility>
168
    <stringType>String</stringType>
169
    <createSetters>true</createSetters>
170
    <createOptionalGetters>true</createOptionalGetters>
171
    <enableDecimalLogicalType>true</enableDecimalLogicalType>
172
    <includes>
173
      <include>**/*.avsc</include>
174
      <include>**/*.avdl</include>
175
    </includes>
176
    <excludes>
177
      <exclude>**/test-*.avsc</exclude>
178
    </excludes>
179
  </configuration>
180
  <executions>
181
    <execution>
182
      <id>schemas</id>
183
      <phase>generate-sources</phase>
184
      <goals>
185
        <goal>schema</goal>
186
        <goal>idl</goal>
187
      </goals>
188
    </execution>
189
    <execution>
190
      <id>induce</id>
191
      <phase>process-classes</phase>
192
      <goals>
193
        <goal>induce</goal>
194
      </goals>
195
      <configuration>
196
        <javaSourceDirectories>
197
          <javaSourceDirectory>${project.basedir}/src/main/java</javaSourceDirectory>
198
        </javaSourceDirectories>
199
        <avroOutputDirectory>${project.build.directory}/generated-resources/avro</avroOutputDirectory>
200
      </configuration>
201
    </execution>
202
  </executions>
203
</plugin>
204
```
205

206
## Common Usage Patterns
207

208
### Multiple Source Directories
209

210
Configure multiple Avro source directories:
211

212
```xml { .api }
213
<configuration>
214
  <sourceDirectory>${project.basedir}/src/main/avro</sourceDirectory>
215
  <imports>
216
    <import>${project.basedir}/src/main/avro/common</import>
217
    <import>${project.basedir}/src/main/avro/shared</import>
218
  </imports>
219
</configuration>
220
```
221

222
### Custom String Types
223

224
Use regular Java String instead of CharSequence:
225

226
```xml { .api }
227
<configuration>
228
  <stringType>String</stringType>
229
</configuration>
230
```
231

232
### Optional Getters for Java 8+
233

234
Enable Optional return types for nullable fields:
235

236
```xml { .api }
237
<configuration>
238
  <gettersReturnOptional>true</gettersReturnOptional>
239
  <optionalGettersForNullableFieldsOnly>true</optionalGettersForNullableFieldsOnly>
240
</configuration>
241
```
242

243
### Schema Generation from Java Classes
244

245
Generate Avro schemas from existing Java classes:
246

247
```xml { .api }
248
<execution>
249
  <goals>
250
    <goal>induce</goal>
251
  </goals>
252
  <configuration>
253
    <javaSourceDirectories>
254
      <javaSourceDirectory>src/main/java/com/example/models</javaSourceDirectory>
255
    </javaSourceDirectories>
256
  </configuration>
257
</execution>
258
```