Apache Avro Maven Plugin

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.

Package Information

• Package Name: avro-maven-plugin
• Package Type: maven-plugin
• Group ID: org.apache.avro
• Artifact ID: avro-maven-plugin
• Language: Java
• Installation: Add to pom.xml build plugins section

Core Maven Coordinates

<groupId>org.apache.avro</groupId>
<artifactId>avro-maven-plugin</artifactId>
<version>1.12.0</version>

Basic Usage

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

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.avro</groupId>
      <artifactId>avro-maven-plugin</artifactId>
      <version>1.12.0</version>
      <executions>
        <execution>
          <goals>
            <goal>schema</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

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

mvn avro:schema

Maven Goals

Schema Compilation (avro:schema)

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

<goal>schema</goal>

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

IDL Compilation (avro:idl)

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

<goal>idl</goal>

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

Protocol Compilation (avro:protocol)

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

<goal>protocol</goal>

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

Schema Induction (avro:induce)

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

<goal>induce</goal>

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

Legacy IDL Protocol (avro:idl-protocol)

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

<goal>idl-protocol</goal>

Configuration Parameters

Common Directory Configuration

• sourceDirectory - Source directory for Avro files (default: ${basedir}/src/main/avro)
• outputDirectory - Output directory for generated sources (default: ${project.build.directory}/generated-sources/avro)
• testSourceDirectory - Test source directory (default: ${basedir}/src/test/avro)
• testOutputDirectory - Test output directory (default: ${project.build.directory}/generated-test-sources/avro)

Code Generation Options

• fieldVisibility - Field visibility for generated classes: PRIVATE, PUBLIC, PROTECTED (default: PRIVATE)
• stringType - Java type for Avro strings: CharSequence, String, Utf8 (default: CharSequence)
• createSetters - Generate setter methods (default: true)
• createOptionalGetters - Generate getOptional... methods for Java 8+ (default: false)
• gettersReturnOptional - Generate get... methods returning Optional for Java 8+ (default: false)
• optionalGettersForNullableFieldsOnly - Optional getters only for nullable fields (default: false)
• createNullSafeAnnotations - Add JetBrains @Nullable/@NotNull annotations (default: false)

Advanced Configuration

• imports - Files/directories to compile first for imports
• includes - Ant-like inclusion patterns for source files (default: goal-specific patterns)
• excludes - Ant-like exclusion patterns for source files (default: empty array)
• testIncludes - Ant-like inclusion patterns for test files (default: goal-specific patterns)
• testExcludes - Ant-like exclusion patterns for test files (default: empty array)
• templateDirectory - Custom Velocity template directory (default: "/org/apache/avro/compiler/specific/templates/java/classic/")
• velocityToolsClassesNames - Additional Velocity tool classes (default: empty array)
• customConversions - Custom Conversion implementation classes (default: empty array)
• customLogicalTypeFactories - Custom LogicalTypeFactory implementation classes (default: empty array)
• enableDecimalLogicalType - Use Java classes for decimal types (default: false)
• createNullSafeAnnotations - Add JetBrains @Nullable/@NotNull annotations (default: false)

Class Inheritance Configuration

• recordSpecificClass - Base class for generated record classes (default: org.apache.avro.specific.SpecificRecordBase)
• errorSpecificClass - Base class for generated error classes (default: org.apache.avro.specific.SpecificExceptionBase)

Induce Goal Specific Configuration

• javaSourceDirectories - Java source directories for schema induction (default: ${basedir}/src/main/java)
• avroOutputDirectory - Output directory for induced schemas (default: ${project.build.directory}/generated-resources/avro)
• encoding - Output file encoding (default: ${project.build.sourceEncoding} or system default if not set)
• allowNull - Use ReflectData.AllowNull for nullable fields (default: false)
• reflectDataImplementation - Custom ReflectData implementation class (must be subclass of ReflectData)

Complete Plugin Configuration Example

<plugin>
  <groupId>org.apache.avro</groupId>
  <artifactId>avro-maven-plugin</artifactId>
  <version>1.12.0</version>
  <configuration>
    <sourceDirectory>${project.basedir}/src/main/avro</sourceDirectory>
    <outputDirectory>${project.build.directory}/generated-sources/avro</outputDirectory>
    <fieldVisibility>PUBLIC</fieldVisibility>
    <stringType>String</stringType>
    <createSetters>true</createSetters>
    <createOptionalGetters>true</createOptionalGetters>
    <enableDecimalLogicalType>true</enableDecimalLogicalType>
    <includes>
      <include>**/*.avsc</include>
      <include>**/*.avdl</include>
    </includes>
    <excludes>
      <exclude>**/test-*.avsc</exclude>
    </excludes>
  </configuration>
  <executions>
    <execution>
      <id>schemas</id>
      <phase>generate-sources</phase>
      <goals>
        <goal>schema</goal>
        <goal>idl</goal>
      </goals>
    </execution>
    <execution>
      <id>induce</id>
      <phase>process-classes</phase>
      <goals>
        <goal>induce</goal>
      </goals>
      <configuration>
        <javaSourceDirectories>
          <javaSourceDirectory>${project.basedir}/src/main/java</javaSourceDirectory>
        </javaSourceDirectories>
        <avroOutputDirectory>${project.build.directory}/generated-resources/avro</avroOutputDirectory>
      </configuration>
    </execution>
  </executions>
</plugin>

Common Usage Patterns

Multiple Source Directories

Configure multiple Avro source directories:

<configuration>
  <sourceDirectory>${project.basedir}/src/main/avro</sourceDirectory>
  <imports>
    <import>${project.basedir}/src/main/avro/common</import>
    <import>${project.basedir}/src/main/avro/shared</import>
  </imports>
</configuration>

Custom String Types

Use regular Java String instead of CharSequence:

<configuration>
  <stringType>String</stringType>
</configuration>

Optional Getters for Java 8+

Enable Optional return types for nullable fields:

<configuration>
  <gettersReturnOptional>true</gettersReturnOptional>
  <optionalGettersForNullableFieldsOnly>true</optionalGettersForNullableFieldsOnly>
</configuration>

Schema Generation from Java Classes

Generate Avro schemas from existing Java classes:

<execution>
  <goals>
    <goal>induce</goal>
  </goals>
  <configuration>
    <javaSourceDirectories>
      <javaSourceDirectory>src/main/java/com/example/models</javaSourceDirectory>
    </javaSourceDirectories>
  </configuration>
</execution>