How to implement build specific annotation retention in Java

Question

I have an annotation that I currently use only for internal build and documentation purposes. It does not offer any value at runtime, which is why I chose @Retention(SOURCE):

@Retention(SOURCE)
public @interface X

However, in order to validate its proper usage, I would like to implement a unit test that navigates the entire API to check whether the annotation is applied everywhere it should be applied to. That unit test would be quite easy to implement by using ordinary Java reflection APIs, but I cannot do that as the tests can't reflect over the annotation, given its @Retention(SOURCE).

In order to use reflection in tests, I would have to change it to @Retention(RUNTIME), which I would like to avoid due to the overhead in byte code at run time.

Workarounds I'm aware of:

There are workarounds as always. I'm aware of these:

• We could use an annotation processor that fails the build instead of running unit tests. This is feasible but less optimal, as the tests are quite sophisticated and much more difficult to implement using annotation processors rather than unit tests using both junit APIs and the much more convenient reflection API. I would like to use this workaround as a last resort only.
• We could change the @Retention to RUNTIME in our sources, build the sources with these additional tests, then pre-process the API to remove the retention again, and then build the API a second time for production usage. This is an annoying workaround as it would complicate and slow down the build.

Question:

Is there a more convenient way to retain the annotation at runtime only for tests, but not in the actually built jar file, using Maven?

Answer 1

Here's a hybrid approach that might work.

Write an annotation processor that doesn't implement the full testing that you want to do, but instead merely records in a sidecar file where the annotations occurred. If you're annotating classes, methods, and fields, the location can be recorded fairly straightforwardly using the package-qualified class name plus a method or field descriptor. (This may be more difficult, though, if your annotation can appear in more obscure places such as on method parameters or at type use sites.) Then, you can keep the retention policy as SOURCE.

Next, write your junit tests to do whatever reflective analysis you're intending to do. Instead of trying to find the annotations reflectively, though (since they won't be there) read in the sidecar file and look there.

Answer 2

I think you covered the solution space pretty well.

Two more you didn't cover:

• Strip the annotation later in a post processing step using a tool like proguard.

• Hack your compiler to switch the annotation retention depending on a flag. Pretty sure you can switch some flag in the internal meta data. Maybe injected by another annotation processor triggered by the annotation @DynamicRetention("flag")?