Use of javac --release-8 or -source=8 flags can cause compile issues

[eeverman]

Quick solution for users dealing with this issue
If you are targeting JDK 1.8, do the build using 1.8. This issue affects AndHow versions 1.4.1.

Read on for more discussion...

Describe the bug
Java broke annotations processors going from JDK 1.8 to JDK 9. Annotation processors are supposed to annotate classes they generate with a Generated annotation, however the package containing that annotation changed between the two releases:

• JDK 1.8 : javax.annotation.Generated
• JDK 9 : javax.annotation.processing.Generated

When an annotation processor generates a class, it is supposed to annotate the generated class with a Generated annotation, like this:

@javax.annotation.Generated(value="who.generated.me", date="...", comments="...")
public class $SomeGeneratedClass { ... }  //JDK 8 compatible

... or maybe this...

@javax.annotation.processing.Generated(value="who.generated.me", date="...", comments="...")
public class $SomeGeneratedClass { ... }  //JDK 8 compatible

Picking the right Generated annotation class should be easy, but its not. There are two things to work from:

• The version of the JDK used to compile, i.e. calling System.getProperty("java.version")
• The ProcessingEnvironment.getSourceVersion(), which is passed to the annotation processor

JDK	Options	reported srcVersion	actual Generated on path	Notes
1.8	Any	1.8	1.8	All compiles on 1.8 are no problem
9+	no options	9+	9+	A standard build on JDK 9 or greater is no problem
15	-source=9	9	9	Specifying a source 9 or greater is also no problem
9+	-source=8 -target=any	1.8	9	Even though src is set to 8, JDK 9 Generated is on the path
9+	-release=8	1.8	8	With -release=8 set, JDK 8 Generated is on the path

So far, there seems to be no way to distinguish between those last two rows in the table. One potential option would be to check which Generated class is on the path in the annotation processor, but this doesn't help because javac seems to maintain two different class paths: One for the annotation processor and one for the compiler. Expanding those last two rows from above with more detail:

JDK	Options	reported srcVer.	Generated on path for Annotation Processor	Generated on path for compiler	Notes
9+	-source=8	1.8	9	9	This one is at least consistent
9+	-release=8	1.8	9	8	!!!

The javac options -source=8 and -release=8 are indistinguishable to the annotation processor, but change the class path visible to the compiler. The annotation processor cannot determine the correct 'Generated' class version to generate.

Given that these two cases cannot be distinguished, I think the only option is to comment out the Generated annotation when:

• The JDK is 9 or greater, and
• ProcessingEnvironment.getSourceVersion() reports JDK 8
  The Generated annotation is not a requirement. Its intended to be informative for tools like lint checkers to not report on these classes. Commenting out the annotation may allow some of these checkers to still work, depending on how they detect the Generated annotation.

Perhaps an annotation processor option could be added to force the use of the JDK 8 Generated annotation. That would be a very slim use case, however.

Note: The Generated annotation has SOURCE level retention, thus it is only present in the source code and during compilation, however, it is not present in the generated class file. Thus, generated classes will have no dependency on the the Generated class.

[eeverman]

Fixed by #634