Compiling generated libraries with Java 9+ fails due to javax.annotation.Generated

[chanseokoh]

For example, compiling a "self-service" generated library with ./gradlew check fails:

> Task :proto-google-cloud-retail-v2alpha-java:compileJava
/tmp/google-cloud-retail-v2alpha-java/proto-google-cloud-retail-v2alpha-java/src/main/java/com/google/cloud/retail/v2alpha/LocationName.java:27: error: cannot find symbol
import javax.annotation.Generated;

The javax.annotation package space is really a mess from the perspective of Java 9+ JPMS, and it has caused a lot of trouble to many people with Java 9+.

The right solution for Java 9+ is to drop javax.annotation.Generated and migrate to javax.annotation.processing.Generated. However, doing so will cause Java 8 to fail with the same "cannot find symbol" error. An option would be to completely drop using the annotation. However, the gRPC proto compiler generated files with the annotation, so they are out of our control:

@javax.annotation.processing.Generated(
    value = "by gRPC proto compiler",
    comments = "Source: google/cloud/retail/v2alpha/product_service.proto")

A workaround for the users hitting this issue is to declare the following dependency, but this isn't really the right solution.

implementation 'javax.annotation:javax.annotation-api:1.3.2'

Refs:
google/dagger#880
grpc/grpc-java#3633
vavr-io/vavr#2154

[chanseokoh]

#889 added the dependency as a workaround. Eventually when we drop Java 8, we should migrate our code to use javax.annotation.processing.Generated.

[vam-google]

@chanseokoh Is this bug still relevant? Keeping this bug open for the Java8 support drop time is probably not practical, as we are guaranteed to not drop it till 2030 at minimum (current end of Java8 Extended Suppport by Oracle https://www.oracle.com/java/technologies/java-se-support-roadmap.html)

[chanseokoh]

We need way to track this issue, so that we don't forget to fix it when the time comes.

Are we not allowed to leave a bug open for some set period of time? If so, I'll have no choice but to close it.

[suztomo]

Why it's not happening in Java 11 and Java 17 CIs?

[chanseokoh]

Let me clarify. The workaround is in place, so things are working fine with any Java version. But the workaround is kinda ugly. The right solution is to drop javax.annotation.Generated and migrate to javax.annotation.processing.Generated after reverting the workaround. However, we can only do that when we stop building with Java 8. This issue is open to track implementing the right solution in the future.

[suztomo]

Glad to hear that the workaround is in place. Thank you for clarification.

Memo: https://docs.oracle.com/javase/9/docs/api/javax/annotation/processing/Generated.html has @Retention(SOURCE).
I thought compiling JDK 11 targeting Java 8 would resolve this issue but it turned out that the "--release 8" flag, which is required to generate Java8-compatible bytecode, prevents us from using the annotation:

suztomo@suztomo2:~/java8-library-and-graal-sdk$ java -version
openjdk version "11.0.12" 2021-07-20
OpenJDK Runtime Environment 18.9 (build 11.0.12+7)
OpenJDK 64-Bit Server VM 18.9 (build 11.0.12+7, mixed mode)
suztomo@suztomo2:~/java8-library-and-graal-sdk$ mvn compile 
...
[INFO] --- maven-compiler-plugin:3.10.1:compile (default-compile) @ java8-library-and-graal-sdk ---
[INFO] Changes detected - recompiling the module!
[INFO] Compiling 3 source files to /usr/local/google/home/suztomo/java8-library-and-graal-sdk/target/classes
[INFO] -------------------------------------------------------------
[ERROR] COMPILATION ERROR : 
[INFO] -------------------------------------------------------------
[ERROR] /usr/local/google/home/suztomo/java8-library-and-graal-sdk/src/main/java/org/example/BarGenerated.java:[3,35] cannot find symbol
  symbol:   class Generated
  location: package javax.annotation.processing
[ERROR] /usr/local/google/home/suztomo/java8-library-and-graal-sdk/src/main/java/org/example/BarGenerated.java:[5,2] cannot find symbol
  symbol: class Generated
[INFO] 2 errors 
...
suztomo@suztomo2:~/java8-library-and-graal-sdk$ tail pom.xml 
      <activation>
        <jdk>[9,]</jdk>
      </activation>
      <properties>
        <!-- The flag is only available in JDK 9 or higher -->
        <maven.compiler.release>8</maven.compiler.release>
      </properties>
    </profile>
  </profiles>
</project>

Removing the "--release 8" flag passes the compilation in JDK 11. But this carries the risk of generating Java8-incompatible bytecode.