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)
