src/share/classes/javax/annotation/processing/Processor.java

Print this page

        

*** 1,7 **** /* ! * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this --- 1,7 ---- /* ! * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this
*** 24,33 **** --- 24,35 ---- */ package javax.annotation.processing; import java.util.Set; + import javax.lang.model.util.Elements; + import javax.lang.model.AnnotatedConstruct; import javax.lang.model.element.*; import javax.lang.model.SourceVersion; /** * The interface for an annotation processor.
*** 86,112 **** * used for a {@linkplain java.util.ServiceLoader service-style} * lookup. Other tool implementations may have different * configuration mechanisms, such as command line options; for * details, refer to the particular tool's documentation. Which * processors the tool asks to {@linkplain #process run} is a function ! * of what annotations are present on the {@linkplain * RoundEnvironment#getRootElements root elements}, what {@linkplain * #getSupportedAnnotationTypes annotation types a processor ! * processes}, and whether or not a processor {@linkplain #process ! * claims the annotations it processes}. A processor will be asked to * process a subset of the annotation types it supports, possibly an * empty set. * ! * For a given round, the tool computes the set of annotation types on ! * the root elements. If there is at least one annotation type ! * present, as processors claim annotation types, they are removed ! * from the set of unmatched annotations. When the set is empty or no ! * more processors are available, the round has run to completion. If * there are no annotation types present, annotation processing still * occurs but only <i>universal processors</i> which support ! * processing {@code "*"} can claim the (empty) set of annotation ! * types. * * <p>Note that if a processor supports {@code "*"} and returns {@code * true}, all annotations are claimed. Therefore, a universal * processor being used to, for example, implement additional validity * checks should return {@code false} so as to not prevent other such --- 88,143 ---- * used for a {@linkplain java.util.ServiceLoader service-style} * lookup. Other tool implementations may have different * configuration mechanisms, such as command line options; for * details, refer to the particular tool's documentation. Which * processors the tool asks to {@linkplain #process run} is a function ! * of the types of the annotations <em>{@linkplain AnnotatedConstruct present}</em> ! * on the {@linkplain * RoundEnvironment#getRootElements root elements}, what {@linkplain * #getSupportedAnnotationTypes annotation types a processor ! * supports}, and whether or not a processor {@linkplain #process ! * claims the annotation types it processes}. A processor will be asked to * process a subset of the annotation types it supports, possibly an * empty set. * ! * For a given round, the tool computes the set of annotation types ! * that are present on the elements enclosed within the root elements. ! * If there is at least one annotation type present, then as ! * processors claim annotation types, they are removed from the set of ! * unmatched annotation types. When the set is empty or no more ! * processors are available, the round has run to completion. If * there are no annotation types present, annotation processing still * occurs but only <i>universal processors</i> which support ! * processing all annotation types, {@code "*"}, can claim the (empty) ! * set of annotation types. ! * ! * <p>An annotation type is considered present if there is at least ! * one annotation of that type present on an element enclosed within ! * the root elements of a round. For this purpose, a type parameter is ! * considered to be enclosed by its {@linkplain ! * TypeParameterElement#getGenericElement generic ! * element}. Annotations on {@linkplain ! * java.lang.annotation.ElementType#TYPE_USE type uses}, as opposed to ! * annotations on elements, are ignored when computing whether or not ! * an annotation type is present. ! * ! * <p>An annotation is present if it meets the definition of being ! * present given in {@link AnnotatedConstruct}. In brief, an ! * annotation is considered present for the purposes of discovery if ! * it is directly present or present via inheritance. An annotation is ! * <em>not</em> considered present by virtue of being wrapped by a ! * container annotation. Operationally, this is equivalent to an ! * annotation being present on an element if and only if it would be ! * included in the results of {@link ! * Elements#getAllAnnotationMirrors(Element)} called on that element. Since ! * annotations inside container annotations are not considered ! * present, to properly process {@linkplain ! * java.lang.annotation.Repeatable repeatable annotation types}, ! * processors are advised to include both the repeatable annotation ! * type and its containing annotation type in the set of {@linkplain ! * #getSupportedAnnotationTypes() supported annotation types} of a ! * processor. * * <p>Note that if a processor supports {@code "*"} and returns {@code * true}, all annotations are claimed. Therefore, a universal * processor being used to, for example, implement additional validity * checks should return {@code false} so as to not prevent other such
*** 255,279 **** void init(ProcessingEnvironment processingEnv); /** * Processes a set of annotation types on type elements * originating from the prior round and returns whether or not ! * these annotations are claimed by this processor. If {@code ! * true} is returned, the annotations are claimed and subsequent * processors will not be asked to process them; if {@code false} ! * is returned, the annotations are unclaimed and subsequent * processors may be asked to process them. A processor may * always return the same boolean value or may vary the result * based on chosen criteria. * * <p>The input set will be empty if the processor supports {@code * "*"} and the root elements have no annotations. A {@code * Processor} must gracefully handle an empty set of annotations. * * @param annotations the annotation types requested to be processed * @param roundEnv environment for information about the current and prior round ! * @return whether or not the set of annotations are claimed by this processor */ boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv); /** --- 286,310 ---- void init(ProcessingEnvironment processingEnv); /** * Processes a set of annotation types on type elements * originating from the prior round and returns whether or not ! * these annotation types are claimed by this processor. If {@code ! * true} is returned, the annotation types are claimed and subsequent * processors will not be asked to process them; if {@code false} ! * is returned, the annotation types are unclaimed and subsequent * processors may be asked to process them. A processor may * always return the same boolean value or may vary the result * based on chosen criteria. * * <p>The input set will be empty if the processor supports {@code * "*"} and the root elements have no annotations. A {@code * Processor} must gracefully handle an empty set of annotations. * * @param annotations the annotation types requested to be processed * @param roundEnv environment for information about the current and prior round ! * @return whether or not the set of annotation types are claimed by this processor */ boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv); /**