[jira] [Created] (AVRO-3535) Ability to add a deprecation notice in javaAnnotations

["Jeroen Bastijns (Jira)" <ji...@apache.org>]

Jeroen Bastijns created AVRO-3535:
-------------------------------------

             Summary: Ability to add a deprecation notice in javaAnnotations
                 Key: AVRO-3535
                 URL: https://issues.apache.org/jira/browse/AVRO-3535
             Project: Apache Avro
          Issue Type: Wish
          Components: java
    Affects Versions: 1.11.0
            Reporter: Jeroen Bastijns
         Attachments: record.vm

Hi,

I would like to be able to generate a deprecation notice via the javaAnnotations field in the AVRO record definition.

An example of this is following record definition:


{code:java}
{
  "namespace" : "com.something",
  "type" : "record",
  "name" : "VehicleRefueled",
  "fields" : [
    {"name":"licensePlate","type":"string", "doc": "The license plate of the vehicle"},
    {"name":"fuelType",
      "type": {
        "type":"enum",
        "name": "FuelType",
        "symbols": ["GASOLINE","DIESEL","LPG", "CNG", "ELECTRICITY"]
      }
    },
    {"name":"fuelAmount", "type":"double", "default":0.0},
    {"name":"fuelUnit",
      "javaAnnotation": [ "java.lang.Deprecated(since = \"2\", forRemoval = true)" ],
      "type": {
        "name": "FuelUnit",
        "type":"enum",
        "symbols": ["LITER", "KWH"]
      }
    }
  ]
} {code}

Here I used the 'Deprecated' standard Java annotation to declare the fuelUnit field as deprecated since version 2 and it will be removed on the next version of the schema.

Currently the velocity template used by the compiler will only add annotations on top of the field declaration, not the accessors or builder methods. As these are the main accesspoints for a developer to set or get fields, we're missing the point of deprecating the field, because IDE's will only display the deprecation notice when it is annotated on these main accesspoints (accessors and builder methods).

On my local project I've used the option to provide the velocity templates myself and have adapted the template in a non-breaking way to set the javaAnnotations on field accessors and builder methods when the given annotation is the Java deprecated annotation.
The template can be found in the attachments, it is based on the 1.11 branch [^record.vm].

Now why am I asking this to be altered in the Avro code base?

When using a schema registry with compatibility rules (such as APIcurio or Confluent Schema registry) and you use the forward compatibility validation, it is nice to give the consumers of your schema/data a head up on the deprecation of a field and an aditional warning when the field might disappear in a next version.
You can use your own templates to achieve this, like I did, but if the original velocity template changes in a next version of Avro, this will always be a hurdle to take and adapt as a developer. 
When providing your own template to achieve this, you still have to distribute the template to the consumers of your schema/data which may be cumbersome when they are on different versions of Apache Avro.

I think this is a feature other development teams also might benefit from. I'm willing to put together a pull request to change the template and provide unit tests when this feature would be accepted.

Overall a deprecation notice field on schema field level would be an even nicer implementation, but also requires steps to implement for the other supported languages.



--
This message was sent by Atlassian Jira
(v8.20.7#820007)