java generator: mark all generated classes and interfaces with javax.annotation.Generated

[estekhin]

javax.annotation.Generated exists since Java 6 (relevant javadoc) so it should be safe to generate source code that contains it. The presence of this annotation has no impact on the runtime characteristics of the annotated classes.

When this annotation is present it greatly helps in configuration of different tools related to code analysis, tests and tests coverage.

Both the outer Java class and all inner builder and message classes and interfaces should be annotated with javax.annotation.Generated.

[froque]

it seems that there is already an option for this: --java_opt=annotate_code but it is not documented in the help text

[liujisi]

Annotating generated code is on our radar. There are several different proposals (for different use case) that we haven't reached consensus yet (e.g. whether to use custom annotations, whether to use runtime retention etc)

[sergei-ivanov]

I've just played around with the undocumented --java_opt=annotate_code.

Obviously, it only works in proto3, and in the latest versions only (fails with protoc 3.1.0). That's fair enough though (especially as it is not officially supported).

It looks like when the option is specified, only top-level classes and interfaces are being annotated. java_multiple_files option only affects it in a way that more top-level (annotated) classes are being produced, but any nested classes or interfaces are still not annotated. I am pretty sure that most of the static analysis tools and IDEs will not automatically apply/propagate @Generated from the outer class to the inner classes.

protoc also generates a binary xxx.java.pb.meta file for each generated xxx.java class. The purpose of these files is unclear and there is no way to suppress their generation either.

I have also tried adding option annotate_code = true; to the proto file, but that has been rejected as an invalid option by the compiler. Looking at the source code of protoc confirmed that only command line option is supported at the moment. I think an option at the proto source file level this might be a good alternative way of controlling the annotations generation, perhaps in addition to the command line option.

I hope the kind folks at Google are going to provide a bit more clarity in the due course.

[xfxyjwf]

@sergei-ivanov I believe the option --java_opt=annotate_code is not meant to be published. It was introduced for a Google internal source code indexing pipeline and not designed for public consumption.

[froque]

People seem to want this feature, I now I do. There is already the code to enable it. Why not make it public?

[dimo414]

@pherl what's the concern with adding @javax.annotation.Generated? I can understand also wanting to add some custom annotation and needing to figure out its retention policy, but many tools rely on the javax annotation, and it exists specifically for this purpose.

[liujisi]

There were several teams asking for annotations but with different requirement, e.g. runtime retention vs compile time retention; annotation with type information. All of those will affect how we should annotate the classes. There is also on-going experimental java runtime developement work that uses annotations. I think after the new runtime work is done, we can revisit the annotation issue.

[estekhin]

@javax.annotation.Generated and any other custom google-specific internal annotation(s) are separate issues.

Adding @javax.annotation.Generated will not preclude you to generate any number of additional annotations with any combination of retention and whatever.

@javax.annotation.Generated is the best standard option available right now, it is already supported by some static analysis tools, and it does not require anybody to vendor-lock on some custom annotations.

[ejona86]

@Generated is a bit more complex with Java 9, since it is being removed from the default class path. See grpc/grpc-java#3638 (comment)

[estekhin]

Yeah, in Java 9 there is a new annotation javax.annotation.processing
.Generated.

But you can wait four more years before using it just in case something will be deprecated/removed from the classpath/whatever.

[sergei-ivanov]

@ejona86 My feeling is that with Java9 and beyond Oracle is going to become more aggressive in deprecating and removing classes from the core JDK. Now that they have a mechanism for that (modules and multiple version jars), there's no stopping them. Which probably means that the only choice for protobuf project is to introduce something like option java_release = "9"; into proto files, or a similar command line option for protoc. And then use it to generate code that targets the specific Java release.

[ryanrhee]

Is there an equivalent for javalite? I tried --javalite_opt=annotate_code but it did nothing.

[mkobit]

Would a PR for a different Proto option (maybe something like -java_opt=annotated_javax_generated) to add javax.annotation.processing.Generated to generated code be accepted?

What would it take to get this feature in?

[ejona86]

I don't find javax.annotation.processing.Generated to be a replacement for javax.annotation.Generated. I mention that for gRPC at grpc/grpc-java#3633 . I also talk about the issue with using options to tweak the behavior in that issue.

For gRPC we ended up just continuing to use javax.annotation.Generated and suggesting users to depend on javax.annotation-api. We could maybe make that easier by adding a fake dependency on javax.annotation-api from protobuf.

[ghost]

With the new version of Java lite, you can also use the annotate_code option like this:
For Java: --java_out=annotate_code:...
For JavaLite: --java_out=annotate_code,lite:...

We will likely continue to use the javax.annotation.Generated just like gRPC.