Provides the interface for an annotation processor.
*Annotation processing is divided into a series of rounds, * with the input for each round being a subset of the output * from the previous round. The input for the initial round * are those provided to the tool by the user, but, for the * purposes of operation, can be thought of as coming from a * virtual preceding round, as the behaviour is the same. * Once a processor is asked to process inputs in a particular * round, it is asked to do so in all subsequent rounds, even * if there are no annotations left for it to process. These * inputs can include files generated by the tool's operation.
*Annotation processors are found using a tool-specific
* discovery method which may involve them being named directly
* or discovered via a service-based lookup. The processors which
* are actually used are determined by which of the annotations present
* on the root elements are supported by the processor and whether or
* not it claims them. Claimed annotation types are removed from
* the set of unmatched annotations and are not passed to other
* processors. A round is complete once the set is empty or no
* more processors are available. If there are no annotation types
* on the root elements (i.e. the set is empty to begin with), then
* only
The tool infrastructure expects the following from an annotation * processor:
*Use outside the above protocol is undefined. A processor supporting * {@code "*"} and returning {@code true} from the {@code process} method * will claim all annotations and prevent other processors from running. * If this is not the intention, then {@code false} should be returned.
*To work well with different tool implementations, the processor * should make sure the following properties hold:
*If a processor raises an error, this will be noted and the round * completed. The subsequent round can then query as to whether an * error was raised using {@link RoundEnvironment#errorRaised()}. If * an uncaught exception is raised, the tool may cease the use of other * annotation processors, so this should be used only in situations where * the usual error recovery process is infeasible.
*The tool environment need not support annotation processors accessing * environmental resources, either per round or cross-round, in a multi-threaded * environment. If a method returns {@code null} or other invalid input, or throws * an exception, in response to a configuration query, the tool may treat this * as an error condition.
*The {@link Filer} interface documentation provides more information on how * files are handled and the restrictions in place. Implementators may find it * easier to base their implementation on the {@link AbstractProcessor} class * rather than implementing this interface directly.
* * @author Andrew John Hughes (gnu_andrew@member.fsf.org) * @since 1.6 */ public interface Processor { /** *Returns the names of the annotation types supported by this * processor. These can take one of the following forms:
*For example, {@code "gnu.classpath.annotations.ProcessMe"} matches * the specific annotation class, {@code ProcessMe}. Alternatively, * {@code "gnu.classpath.annotations.*"} matches all annotations under * the package {@code gnu.classpath.annotations}. Finally, {@code .*} * matches all annotations.
*Processors should avoid claiming annotations they don't support, * as this may cause performance issues, and, if they also return * {@code true} when asked to {@link #process()} them, then they may * prevent other processors from handling those annotations.
* * @return the names of the supported annotation types. * @see SupportedAnnotationTypes */ Set* Returns a series of suggested completions for an annotation or an empty * {@link Iterable}. As a completion is being requested, the information * provided to the method may be incomplete, but either {@code element} or * {@code userText} must be non-{@code null}. If the processor can not * provide any completions due to a lack of available information, it should * not throw a {@link NullPointerException}, but instead return an empty * {@code Iterable} or a single completion with an empty value string and * a message explaining why completions could not be returned. *
** Completions are aimed at annotation members where validity constraints reduce * the range of possible values. For example, imagine an annotation {@code RainbowColour} * which takes as its value one of the following strings: {@code "RED"}, {@code "ORANGE"}, * {@code "YELLOW"}, {@code "GREEN"}, {@code "BLUE"}, {@code "INDIGO"} and {@code "VIOLET"}. * If this annotation is passed as the annotation mirror argument to this method, then * a list of {@code Completion} objects may be returned as follows:
*return Arrays.asList({@link Completions#of}("RED"), of("ORANGE"), of("YELLOW"),
* of("GREEN"), of("BLUE"), of("INDIGO"), of("VIOLET"));. If {@code userText}
* is set, it may be used to further reduce the range of possible values. For example,
* if {@code userText} was "R", then {@code Arrays.asList(of("RED"))} would be returned,
* as only one possible value starts with {@code "R"}. However, if {@code userText}
* was {@code "P"}, then {@code Collections.emptyList()} would be returned, as there
* are no possible values beginning with {@code "P"}. Alternatively,
* {@code of("", "No colours begin with the letter " + userText)} may be used to
* give a more informative result.
*
*
* @param element the element being annotated.
* @param annotation the annotation (possibly partial) being applied to the element.
* @param member the annotation member to return completions for.
* @param userText the source code text to be completed.
* @return an {@code Iterable} over suggested completions to the annotation.
*/
Iterable getCompletions(Element element, AnnotationMirror annotation,
ExecutableElement member, String userText);
}