remove Annotations and add AnnotationBuilder

[Ladicek]

The Annotations API was a provisional solution for creating
annotation instances. This commit replaces it with a simpler,
more traditional builder API: AnnotationBuilder. Considering
that AnnotationInfo.target() was dropped, the builder can
simply produce AnnotationInfo instances, which allows
simplification of other APIs that expect users to pass
annotation instances (annotation transformation and synthetic
component registration).

Additionally, this commit tries to establish a convention
for documenting null handling:

• if the user is forbidden to pass null, we say "must not
  be null" and we don't have to document that a NPE will be
  thrown;
• if the API guarantees that null will never be returned,
  we simply say "never null".

[graemerocher]

I was wondering if this is necessary since in Micronaut we don't actually store the enum type and only the constant value so it would be complicate matters, given the user can already lookup types via the Types impl ?

[Ladicek]

I noticed you dropped this method and I thought it's probably a mistake, so I added it back. What I didn't notice is that you added a parameter to <E extends Enum<E>> E asEnum(Class<E> enumType) :-) IMHO, that should just be <E extends Enum<E>> E asEnum(). The enum type is available on the declaration of the annotation member, isn't it? As in, you should always be able to find it even if you don't remember it?

[graemerocher]

Looks like as of today we just store enum values as strings. See https://github.com/micronaut-projects/micronaut-core/blob/a949a27c69ff00fe50fa751adf0501540aee79b2/inject-java/src/main/java/io/micronaut/annotation/processing/JavaAnnotationMetadataBuilder.java#L637-L641

I guess we would have to rework that code to store the actual enum values, although I am not sure how possible that is, we would I guess need to store the underlying VariableElement from the annotation processing API

[Ladicek]

Alright that sounds weird. I don't know how you [intend to] implement this, but if your implementation of AnnotationMemberValue retains a reference to whatever you use to implement AnnotationInfo, you should be able to lookup the declaration of the annotation member and from there, lookup the enum type. Am I missing something?

[graemerocher]

yeah probably there is a way, will try work it out

[Ladicek]

Yea I thought asEnum might be problematic, I originally had a TODO for that method: // TODO should this be present?

Does adding the Class parameter help with the classpath issues? If so, I'm fine with leaving it there (and indeed it also help with type inference).

OK, I'll submit another PR to change AnnotationInfo.members() to return Map<String, SomeAnnotationMemberValueType_ProbablyAnnotationMember> and remove AnnotationMember as it currently stands. I've have to figure out one other thing now, but I should get to it later today.

[graemerocher]

Yes having the Class parameter is better as the API user knows they have to have the class before they can the enum. That is why I added it in the other PR

[Ladicek]

Here, the API user is the extension author. That is typically not the same person as the extension user.

I'd rather remove asEnum completely than having it sometimes failing with classloading errors, to be honest :-)

[graemerocher]

Right, my point was if the extension author has to supply a Class parameter, they know that they have to configure their classpath to make sure the Class they are requesting is on the same classpath as the extension.

FooEnum e = info.asEnum(FooEnum.class);

In the above case FooEnum will not be referencable if it is not on the classpath of the extension and the extension author would get a compilation error.

[Ladicek]

OK, if you're fine with it, then I am :-) Let's keep asEnum as it is now, then. I'll remove the TODO comment.