The usage of Completion in java annotation

Question

There is a lot of confusion about the getCompletions method in the javax.annotation.processing package. What is the completion function returned by this method? Can you give me an example of specific use. Thank you。

 Iterable<? extends Completion> getCompletions(Element element,
                                                  AnnotationMirror annotation,
                                                  ExecutableElement member,
                                                  String userText);

Answer 1

There is a lot of confusion about the getCompletions method in the javax.annotation.processing package.

By who?

What is the completion function returned by this method?

it's a nice-to-have, optional feature. What it is for, is to help IDEs specifically.

When you compile code with javac or some other command line compiler, this method isn't invoked at all. It's there solely for IDEs. When you open up your eclipse or intellij or whatnot, type "Hello". and wait 500msec or hit CTRL+SPACE or whatever the IDE uses for shortcut for 'auto-complete', you get a menu of sorts that shows all the various methods that strings have. And possibly some templates and other features as well; IDEs are free to add whatever they want to this, there is no actual java specification for 'auto completers in IDEs'.

Nevertheless, that's what this method is for.

Specifically, it's for having the IDE help you out when you type: @YourAnn(someAnnotationParamName=...) - anywhere in the... part, that's where this feature is relevant.

How to help yourself next time

Docs are good... if they are there. But in this case, they were there. The docs on this feature can be found where-ever you find your javadoc (google, your IDE, and so many other places): The javadoc of Processor.getCompletions explains stuff, including a great example.

Given that this example is quite nice, I dispute your characterization that 'there is a lot of confusion about the getCompletions method':)

Answer 2

getCompletions is intended for use by IDEs. It helps users to know what arguments may be supplied to an annotation.

It is well described by its Javadoc documentation .

The example used there is: Suppose there is an annotation defined as

@MersennePrime {
    int value(); // must be a prime of the form 2^n-1, e.g., 3, 7, 31, 127, 8191, ...
}

The implementation of getComletions could be

return Arrays.asList(of("3"),
                      of("7"),
                      of("31"),
                      of("127"),
                      of("8191"),
                      of("131071"),
                      of("524287"),
                      of("2147483647"));

If a user has written @MersennePrime , the IDE can suggest the arguments returned by getCompletions . If a user has written @MersennePrime(1 , then getCompletions is passed "1" as its userText command-line argument and should return a list containing just 127 and 131071 .