Make @API annotation available via Java reflection

[volkovs]

API annotation could be retrieved from byte code (e.g. by using org.reflections), however it would be much more convenient (for #144) to retrieve annotations via Java Reflection.

---

I hereby agree to the terms of the JUnit Contributor License Agreement.

[smoyer64]

This would make #144 much easier.

[marcphilipp]

Hmm, I'm not sure about this one. I've never used org.reflections. How hard would it be to access the annotations using it?

[smoyer64]

@marcphilipp - I missed that and was thinking about runtime reflection via java.lang.reflect.

[volkovs]

@marcphilipp > How hard would it be to access the annotations using it?

That would be as easy as:

    Reflections reflections = new Reflections(PACKAGE_TO_SCAN,
            new TypeAnnotationsScanner(),
            new MethodAnnotationsScanner()
    );

    Set<Class<?>> annotatedTypes = reflections.getTypesAnnotatedWith(API.class);
    Set<Method> annotatedMethods = reflections.getMethodsAnnotatedWith(API.class);
    Set<Constructor> annotatedConstructors = reflections.getConstructorsAnnotatedWith(API.class);

But as far as I know there is no way to define annotation parameter values as filters (to fetch only Internal or only Experimental classes). So, Java Reflection might still be required. And, as mentioned above, Java Reflection doesn't see annotations with CLASS Retention Policy.

[marcphilipp]

@junit-team/junit-lambda I agree that it would be much easier to work with @API if we merged this change. Any objections?

[sbrannen]

I do not have any objection to this PR.

However, if we're going to do this, I think we should also remove the @API(Internal) declaration on API itself (which I believe has also been suggested elsewhere).

[nipafx]

However, if we're going to do this, I think we should also remove the @API(Internal) declaration on API itself (which I believe has also been suggested elsewhere).

That would be #317.

[marcphilipp]

Shall we make it Experimental?

[sbrannen]

Shall we make it Experimental?

I honestly think we should just delete the declaration of @API on API completely and close #317 as invalid.

But... if you think that's too bold for the time being, I could also live with making it Experimental (and still closing #317). 😉

[sbrannen]

This has been merged into master.

[sbrannen]

FYI: this issue is related to #436.