{"id":15056570,"url":"https://github.com/davidmc24/gradle-avro-plugin","last_synced_at":"2025-10-04T16:31:03.587Z","repository":{"id":11351443,"uuid":"13782491","full_name":"davidmc24/gradle-avro-plugin","owner":"davidmc24","description":"A Gradle plugin to allow easily performing Java code generation for Apache Avro. It supports JSON schema declaration files, JSON protocol declaration files, and Avro IDL files.","archived":true,"fork":false,"pushed_at":"2023-12-28T00:14:00.000Z","size":1536,"stargazers_count":321,"open_issues_count":0,"forks_count":78,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-09-30T04:01:33.322Z","etag":null,"topics":["avro","gradle-plugin","groovy","java"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidmc24.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"davidmc24"}},"created_at":"2013-10-22T18:45:09.000Z","updated_at":"2024-09-28T01:15:39.000Z","dependencies_parsed_at":"2023-12-28T02:24:05.754Z","dependency_job_id":"15ef0886-8aad-45e0-8d5c-6031e3a96d18","html_url":"https://github.com/davidmc24/gradle-avro-plugin","commit_stats":null,"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmc24%2Fgradle-avro-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmc24%2Fgradle-avro-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmc24%2Fgradle-avro-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmc24%2Fgradle-avro-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidmc24","download_url":"https://codeload.github.com/davidmc24/gradle-avro-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235274420,"owners_count":18963916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["avro","gradle-plugin","groovy","java"],"created_at":"2024-09-24T21:53:33.166Z","updated_at":"2025-10-04T16:30:58.246Z","avatar_url":"https://github.com/davidmc24.png","language":"Java","funding_links":["https://github.com/sponsors/davidmc24"],"categories":[],"sub_categories":[],"readme":"# End of life\n\nThis project is no longer maintained.\nIts code has been donated to the [Apache Avro project](http://avro.apache.org/), which will be handling releases going forward.\n\n# Overview\n\nThis is a [Gradle](http://www.gradle.org/) plugin to allow easily performing Java code generation for [Apache Avro](http://avro.apache.org/).  It supports JSON schema declaration files, JSON protocol declaration files, and Avro IDL files.\n\n[![Build Status](https://github.com/davidmc24/gradle-avro-plugin/workflows/CI%20Build/badge.svg)](https://github.com/davidmc24/gradle-avro-plugin/actions)\n\n# Compatibility\n\n**NOTE**: Pre-1.0 versions used a different publishing process/namespace.  It is strongly recommended to upgrade to a newer version.  Further details can be found in the [change log](CHANGES.md).\n\n* Currently tested against Java 8, 11, and 17-19\n    * Though not supported yet, tests are also run against Java 20 to provide early notification of potential incompatibilities.\n    * Java 19 support requires Gradle 7.6 or higher (as per Gradle's release notes)\n    * Java 18 support requires Gradle 7.5 or higher (as per Gradle's release notes)\n    * Java 17 support requires Gradle 7.3 or higher (as per Gradle's release notes)\n    * Java 16 support requires Gradle 7.0 or higher (as per Gradle's release notes)\n    * Java 15 support requires Gradle 6.7 or higher (as per Gradle's release notes)\n    * Java 14 support requires Gradle 6.3 or higher (as per Gradle's release notes)\n    * Java 13 support requires Gradle 6.0 or higher\n    * Java 8-12 support requires Gradle 5.1 or higher (versions lower than 5.1 are no longer supported)\n* Currently built against Gradle 7.6\n    * Currently tested against Gradle 5.1-5.6.4 and 6.0-7.6\n* Currently built against Avro 1.11.3\n    * Currently tested against Avro 1.11.0-1.11.3\n    * Avro 1.9.0-1.10.2 were last supported in version 1.2.1 \n* Support for Kotlin\n    * Dropped integration with the Kotlin plugin in plugin version 1.4.0, as Kotlin 1.7.x would require compile-time dependency on a specific Kotlin version\n      * Wiring between the tasks added by the plugin and the Kotlin compilation tasks can either be added by your build logic, or a derived plugin\n    * Plugin version 1.3.0 was the last version with tested support for Kotlin \n      * It is believed to work with Kotlin 1.6.x as well\n      * It was tested against Kotlin plugin versions 1.3.20-1.3.72 and 1.4.0-1.4.32 and 1.5.0-1.5.31 using the latest compatible version of Gradle\n      * It was tested against Kotlin plugin versions 1.2.20-1.2.71 and 1.3.0-1.3.11 using Gradle 5.1\n    * Kotlin plugin versions 1.4.20-1.4.32 require special settings to work with Java 17+; see [KT-43704](https://youtrack.jetbrains.com/issue/KT-43704#focus=Comments-27-4639603.0-0)\n    * Kotlin plugin version 1.3.30 is not compatible with Gradle 7.0+\n    * Kotlin plugin versions starting with 1.4.0 require Gradle 5.3+\n    * Kotlin plugin versions prior to 1.3.20 do not support Gradle 6.0+\n    * Kotlin plugin versions prior to 1.2.30 do not support Java 10+\n    * Version of the Kotlin plugin prior to 1.2.20 are unlikely to work\n* Support for Gradle Kotlin DSL\n\n# Usage\n\nAdd the following to your build files.  Substitute the desired version based on [CHANGES.md](https://github.com/davidmc24/gradle-avro-plugin/blob/master/CHANGES.md).\n\n`settings.gradle`:\n```groovy\npluginManagement {\n    repositories {\n        gradlePluginPortal()\n        mavenCentral()\n    }\n}\n```\n\n`build.gradle`:\n```groovy\nplugins {\n    id \"com.github.davidmc24.gradle.plugin.avro\" version \"VERSION\"\n}\n```\n\nAdditionally, ensure that you have an implementation dependency on Avro, such as:\n\n```groovy\nrepositories {\n    mavenCentral()\n}\ndependencies {\n    implementation \"org.apache.avro:avro:1.11.0\"\n}\n```\n\nIf you now run `gradle build`, Java classes will be compiled from Avro files in `src/main/avro`.\nActually, it will attempt to process an \"avro\" directory in every `SourceSet` (main, test, etc.)\n\n# Configuration\n\nThere are a number of configuration options supported in the `avro` block.\n\n| option                               | default                            | description                                                                                                       |\n|--------------------------------------|------------------------------------|-------------------------------------------------------------------------------------------------------------------|\n| createSetters                        | `true`                             | `createSetters` passed to Avro compiler                                                                           |\n| createOptionalGetters                | `false`                            | `createOptionalGetters` passed to Avro compiler                                                                   |\n| gettersReturnOptional                | `false`                            | `gettersReturnOptional` passed to Avro compiler                                                                   |\n| optionalGettersForNullableFieldsOnly | `false`                            | `optionalGettersForNullableFieldsOnly` passed to Avro compiler                                                    |\n| fieldVisibility                      | `\"PRIVATE\"`                        | `fieldVisibility` passed to Avro compiler                                                                         |\n| outputCharacterEncoding              | see below                          | `outputCharacterEncoding` passed to Avro compiler                                                                 |\n| stringType                           | `\"String\"`                         | `stringType` passed to Avro compiler                                                                              |\n| templateDirectory                    | see below                          | `templateDir` passed to Avro compiler                                                                             |\n| additionalVelocityToolClasses        | see below                          | `additionalVelocityTools` passed to Avro compiler                                                                 |\n| enableDecimalLogicalType             | `true`                             | `enableDecimalLogicalType` passed to Avro compiler                                                                |\n| conversionsAndTypeFactoriesClasspath | empty `ConfigurableFileCollection` | used for loading custom conversions and logical type factories                                                    |\n| logicalTypeFactoryClassNames         | empty `Map`                        | map from names to class names of logical types factories to be loaded from `conversionsAndTypeFactoriesClasspath` |\n| customConversionClassNames           | empty `List`                       | class names of custom conversions to be loaded from `conversionsAndTypeFactoriesClasspath`                        |\n\nAdditionally, the `avro` extension exposes the following methods:\n\n* `logicalTypeFactory(String typeName, Class typeFactoryClass)`: register an additional logical type factory\n* `customConversion(Class conversionClass)`: register a custom conversion\n\n## createSetters\n\nValid values: `true` (default), `false`; supports equivalent `String` values\n\nSet to `false` to not create setter methods in the generated classes.\n\nExample:\n\n```groovy\navro {\n    createSetters = false\n}\n```\n\n## createOptionalGetters\n\nValid values: `false` (default), `true`; supports equivalent `String` values\n\nSet to `true` to create additional getter methods that return their fields wrapped in an\n[Optional](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html). For a field with\nname `abc` and type `string`, this setting will create a method\n`Optional\u003cjava.lang.String\u003e getOptionalAbc()`.\n\nExample:\n\n```groovy\navro {\n    createOptionalGetters = false\n}\n```\n\n## gettersReturnOptional\n\nValid values: `false` (default), `true`; supports equivalent `String` values\n\nSet to `true` to cause getter methods to return\n[Optional](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html) wrappers of the\nunderlying type. Where [`createOptionalGetters`](#createoptionalgetters) generates an additional\nmethod, this one replaces the existing getter.\n\nExample:\n\n```groovy\navro {\n    gettersReturnOptional = false\n}\n```\n\n## optionalGettersForNullableFieldsOnly\n\nValid values: `false` (default), `true`; supports equivalent `String` values\n\nSet to `true` in conjuction with `gettersReturnOptional` to `true` to return\n[Optional](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html) wrappers of the\nunderlying type. Where [`gettersReturnOptional`](#gettersReturnOptional) alone changes all getters to\nreturn `Optional`, this one only returns Optional for nullable (null union) field definitions.\nSetting this to `true` without setting `gettersReturnOptional` to `true` will result in this flag having no effect.\n\nExample:\n```groovy\navro {\n    gettersReturnOptional = true\n    optionalGettersForNullableFieldsOnly = true\n}\n```\n\n## fieldVisibility\n\nValid values: any [FieldVisibility](https://avro.apache.org/docs/1.11.0/api/java/org/apache/avro/compiler/specific/SpecificCompiler.FieldVisibility.html) or equivalent `String` name (matched case-insensitively); default `\"PRIVATE\"` (default)\n\nBy default, the fields in generated Java files will have private visibility.\nSet to `\"PRIVATE\"` to explicitly specify private visibility of the fields, or `\"PUBLIC\"` to specify public visibility of the fields.\n\nExample:\n\n```groovy\navro {\n    fieldVisibility = \"PUBLIC\"\n}\n```\n\n## outputCharacterEncoding\n\nValid values: any [Charset](http://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html) or equivalent `String` name\n\nControls the character encoding of generated Java files.\nIf using the plugin's conventions (i.e., not just the base plugin), the associated `JavaCompile` task's encoding will be used automatically.\nOtherwise, it will use the value configured in the `avro` block, defaulting to `\"UTF-8\"`.\n\nExamples:\n\n```groovy\n// Option 1: configure compilation task (avro plugin will automatically match)\ntasks.withType(JavaCompile).configureEach {\n    options.encoding = 'UTF-8'\n}\n// Option 2: just configure avro plugin\navro {\n    outputCharacterEncoding = \"UTF-8\"\n}\n```\n\n## stringType\n\nValid values: any [StringType](http://avro.apache.org/docs/1.8.1/api/java/org/apache/avro/generic/GenericData.StringType.html) or equivalent `String` name (matched case-insensitively); default `\"String\"` (default)\n\nBy default, the generated Java files will use [`java.lang.String`](http://docs.oracle.com/javase/7/docs/api/java/lang/String.html) to represent string types.\nAlternatively, you can set it to `\"Utf8\"` to use [`org.apache.avro.util.Utf8`](https://avro.apache.org/docs/1.8.1/api/java/org/apache/avro/util/Utf8.html) or `\"charSequence\"` to use [`java.lang.CharSequence`](http://docs.oracle.com/javase/7/docs/api/java/lang/CharSequence.html).\n\n```groovy\navro {\n    stringType = \"CharSequence\"\n}\n```\n\n## templateDirectory\n\nBy default, files will be generated using Avro's default templates.\nIf desired, you can override the template set used by either setting this property or the `\"org.apache.avro.specific.templates\"` System property.\n\n```groovy\navro {\n    templateDirectory = \"/path/to/velocity/templates\"\n}\n```\n\n## additionalVelocityToolClasses\n\nWhen overriding the default set of Velocity templates provided with Avro, it is often desirable to provide additional tools to use during generation. \nThe class names you provide will be made available for use in your Velocity templates. An instance of each class provided will be created using \nthe default constructor (required). When registered, they will be available as $class.simpleName(). Given the example configuration below,\ntwo tools would be registered, and be available as escape and json.\n \n\n```groovy\navro {\n  additionalVelocityToolClasses = ['com.yourpackage.Escape', 'com.yourpackage.JSON']\n}\n```\n\n## enableDecimalLogicalType\n\nValid values: `true` (default), `false`; supports equivalent `String` values\n\nBy default, generated Java files will use [`java.math.BigDecimal`](https://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html)\nfor representing `fixed` or `bytes` fields annotated with `\"logicalType\": \"decimal\"`.\nSet to `false` to use [`java.nio.ByteBuffer`](https://docs.oracle.com/javase/7/docs/api/java/nio/ByteBuffer.html) in generated classes.\n\nExample:\n\n```groovy\navro {\n    enableDecimalLogicalType = false\n}\n```\n\n## conversionsAndTypeFactoriesClasspath, logicalTypeFactoryClassNames and customConversionClassNames\n\nProperties that can be used for loading [Conversion](https://avro.apache.org/docs/current/api/java/org/apache/avro/Conversion.html) and [LogicalTypeFactory](https://avro.apache.org/docs/current/api/java/org/apache/avro/LogicalTypes.LogicalTypeFactory.html) classes from outside of the build classpath.\n\nExample:\n\n```groovy\nconfigurations {\n    customConversions\n}\n\ndependencies {\n    customConversions(project(\":custom-conversions\"))\n}\n\navro {\n    conversionsAndTypeFactoriesClasspath.from(configurations.customConversions)\n    logicalTypeFactoryClassNames.put(\"timezone\", \"com.github.davidmc24.gradle.plugin.avro.test.custom.TimeZoneLogicalTypeFactory\")\n    customConversionClassNames.add(\"com.github.davidmc24.gradle.plugin.avro.test.custom.TimeZoneConversion\")\n}\n```\n\n# IntelliJ Integration\n\nThe plugin attempts to make IntelliJ play more smoothly with generated sources when using Gradle-generated project files.\nHowever, there are still some rough edges.  It will work best if you first run `gradle build`, and _after_ that run `gradle idea`.\nIf you do it in the other order, IntelliJ may not properly exclude some directories within your `build` directory.\n\n# Alternate Usage\n\nIf the defaults used by the plugin don't work for you, you can still use the tasks by themselves.\nIn this case, use the `com.github.davidmc24.gradle.plugin.avro-base` plugin instead, and create tasks of type `GenerateAvroJavaTask` and/or `GenerateAvroProtocolTask`.\n\nHere's a short example of what this might look like:\n\n```groovy\nimport com.github.davidmc24.gradle.plugin.avro.GenerateAvroJavaTask\n\napply plugin: \"java\"\napply plugin: \"com.github.davidmc24.gradle.plugin.avro-base\"\n\ndependencies {\n    implementation \"org.apache.avro:avro:1.11.0\"\n}\n\ndef generateAvro = tasks.register(\"generateAvro\", GenerateAvroJavaTask) {\n    source(\"src/avro\")\n    outputDir = file(\"dest/avro\")\n}\n\ntasks.named(\"compileJava\").configure {\n    source(generateAvro)\n}\n```\n\n# File Processing\n\nWhen using this plugin, it is recommended to define each record/enum/fixed type in its own file rather than using inline type definitions.\nThis approach allows defining any type of schema structure, and eliminates the potential for conflicting definitions of a type between multiple files.\nThe plugin will automatically recognize the dependency and compile the files in the correct order.\nFor example, instead of `Cat.avsc`:\n\n```json\n{\n    \"name\": \"Cat\",\n    \"namespace\": \"example\",\n    \"type\": \"record\",\n    \"fields\" : [\n        {\n            \"name\": \"breed\",\n            \"type\": {\n                \"name\": \"Breed\",\n                \"type\": \"enum\",\n                \"symbols\" : [\n                    \"ABYSSINIAN\", \"AMERICAN_SHORTHAIR\", \"BIRMAN\", \"MAINE_COON\", \"ORIENTAL\", \"PERSIAN\", \"RAGDOLL\", \"SIAMESE\", \"SPHYNX\"\n                ]\n            }\n        }\n    ]\n}\n```\n\nuse `Breed.avsc`:\n\n```json\n{\n    \"name\": \"Breed\",\n    \"namespace\": \"example\",\n    \"type\": \"enum\",\n    \"symbols\" : [\"ABYSSINIAN\", \"AMERICAN_SHORTHAIR\", \"BIRMAN\", \"MAINE_COON\", \"ORIENTAL\", \"PERSIAN\", \"RAGDOLL\", \"SIAMESE\", \"SPHYNX\"]\n}\n```\n\n\nand `Cat.avsc`:\n\n```json\n{\n    \"name\": \"Cat\",\n    \"namespace\": \"example\",\n    \"type\": \"record\",\n    \"fields\" : [\n        {\"name\": \"breed\", \"type\": \"Breed\"}\n    ]\n}\n```\n\nThere may be cases where the schema files contain inline type definitions and it is undesirable to modify them.\nIn this case, the plugin will automatically recognize any duplicate type definitions and check if they match.\nIf any conflicts are identified, it will cause a build failure.\n\n# Kotlin Support\n\nThe Java classes generated from your Avro files should be automatically accessible in the classpath to Kotlin classes in the same sourceset, and transitively to any sourcesets that depend on that sourceset.\nThis is accomplished by this plugin detecting that the Kotlin plugin has been applied, and informing the Kotlin compilation tasks of the presence of the generated sources directories for cross-compilation.\n\nThis support does *not* support producing the Avro generated classes as Kotlin classes, as that functionality is not currently provided by the upstream Avro library.\n\n# Kotlin DSL Support\n\nSpecial notes relevant to using this plugin via the Gradle Kotlin DSL:\n\n* Apply the plugin declaratively using the `plugins {}` block.  Otherwise, various features may not work as intended.  See [Configuring Plugins in the Gradle Kotlin DSL](https://github.com/gradle/kotlin-dsl/blob/master/doc/getting-started/Configuring-Plugins.md) for more details.\n* Configuration in the `avro {}` block must be applied differently than in the Groovy DSL.  See the example below for details.\n\n### Example Kotlin DSL Setup:\n\nIn `gradle.build.kts` add:\n\n```kotlin\nplugins {\n    // Find latest release here: https://github.com/davidmc24/gradle-avro-plugin/releases\n    id(\"com.github.davidmc24.gradle.plugin.avro\") version \"VERSION\"\n}\n```\n\nAnd then in your `settings.gradle.kts` add:\n\n```kotlin\npluginManagement {\n    repositories {\n        gradlePluginPortal()\n        mavenCentral()\n    }\n}\n```\n\nThe syntax for configuring the extension looks like this:\n\n```kotlin\navro {\n    isCreateSetters.set(true)\n    isCreateOptionalGetters.set(false)\n    isGettersReturnOptional.set(false)\n    isOptionalGettersForNullableFieldsOnly.set(false)\n    fieldVisibility.set(\"PUBLIC_DEPRECATED\")\n    outputCharacterEncoding.set(\"UTF-8\")\n    stringType.set(\"String\")\n    templateDirectory.set(null as String?)\n    isEnableDecimalLogicalType.set(true)\n}\n```\n\n# Resolving schema dependencies\n\nIf desired, you can generate JSON schema with dependencies resolved.\n\nExample build:\n\n```groovy\nimport com.github.davidmc24.gradle.plugin.avro.ResolveAvroDependenciesTask\n\napply plugin: \"com.github.davidmc24.gradle.plugin.avro-base\"\n\ntasks.register(\"resolveAvroDependencies\", ResolveAvroDependenciesTask) {\n    source file(\"src/avro/normalized\")\n    outputDir = file(\"build/avro/resolved\")\n}\n```\n\n# Generating schema files from protocol/IDL\n\nIf desired, you can generate JSON schema files.\nTo do this, apply the plugin (either `avro` or `avro-base`), and define custom tasks as needed for the schema generation.\nFrom JSON protocol files, all that's needed is the `GenerateAvroSchemaTask`.\nFrom IDL files, first use `GenerateAvroProtocolTask` to convert the IDL files to JSON protocol files, then use `GenerateAvroSchemaTask`.\n\nExample using base plugin with support for both IDL and JSON protocol files in `src/main/avro`:\n\n```groovy\nimport com.github.davidmc24.gradle.plugin.avro.GenerateAvroProtocolTask\nimport com.github.davidmc24.gradle.plugin.avro.GenerateAvroSchemaTask\n\napply plugin: \"com.github.davidmc24.gradle.plugin.avro-base\"\n\ndef generateProtocol = tasks.register(\"generateProtocol\", GenerateAvroProtocolTask) {\n    source file(\"src/main/avro\")\n    include(\"**/*.avdl\")\n    outputDir = file(\"build/generated-avro-main-avpr\")\n}\n\ntasks.register(\"generateSchema\", GenerateAvroSchemaTask) {\n    dependsOn generateProtocol\n    source file(\"src/main/avro\")\n    source file(\"build/generated-avro-main-avpr\")\n    include(\"**/*.avpr\")\n    outputDir = file(\"build/generated-main-avro-avsc\")\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidmc24%2Fgradle-avro-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidmc24%2Fgradle-avro-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidmc24%2Fgradle-avro-plugin/lists"}