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);
/**