Returns to the tool infrastructure an iterable of suggested
completions to an annotation. Since completions are being asked
for, the information provided about the annotation may be
incomplete, as if for a source code fragment. A processor may
return an empty iterable. Annotation processors should focus
their efforts on providing completions for annotation members
with additional validity constraints known to the processor, for
example an
int
member whose value should lie between 1
and 10 or a string member that should be recognized by a known
grammar, such as a regular expression or a URL.
Since incomplete programs are being modeled, some of the
parameters may only have partial information or may be null
. At least one of element
and userText
must be non-null
. If element
is non-null
, annotation
and member
may be null
. Processors may not throw a NullPointerException
if some parameters are null
; if a processor has no
completions to offer based on the provided information, an
empty iterable can be returned. The processor may also return
a single completion with an empty value string and a message
describing why there are no completions.
Completions are informative and may reflect additional
validity checks performed by annotation processors. For
example, consider the simple annotation:
@MersennePrime {
int value();
}
(A Mersenne prime is prime number of the form
2
n - 1.) Given an
AnnotationMirror
for this annotation type, a list of all such primes in the
int
range could be returned without examining any other
arguments to
getCompletions
:
import static javax.annotation.processing.Completions.*;
...
return Arrays.asList(of
("3"),
of("7"),
of("31"),
of("127"),
of("8191"),
of("131071"),
of("524287"),
of("2147483647"));
A more informative set of completions would include the number
of each prime:
return Arrays.asList(of
("3", "M2"),
of("7", "M3"),
of("31", "M5"),
of("127", "M7"),
of("8191", "M13"),
of("131071", "M17"),
of("524287", "M19"),
of("2147483647", "M31"));
However, if the
userText
is available, it can be checked
to see if only a subset of the Mersenne primes are valid. For
example, if the user has typed
@MersennePrime(1
the value of
userText
will be
"1"
; and only
two of the primes are possible completions:
return Arrays.asList(of("127", "M7"),
of("131071", "M17"));
Sometimes no valid completion is possible. For example, there
is no in-range Mersenne prime starting with 9:
@MersennePrime(9
An appropriate response in this case is to either return an
empty list of completions,
return Collections.emptyList();
or a single empty completion with a helpful message
return Arrays.asList(of("", "No in-range Mersenne primes start with 9"));
Returns:
suggested completions to the annotation
Parameters:
-
element - the element being annotated
-
annotation - the (perhaps partial) annotation being
applied to the element
-
member - the annotation member to return possible completions for
-
userText - source code text to be completed