1 /*
   2  * Copyright (c) 2005, 2007, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.annotation.processing;
  27 
  28 import javax.lang.model.element.Element;
  29 import javax.lang.model.element.TypeElement;
  30 import java.util.Set;
  31 import java.lang.annotation.Annotation;
  32 
  33 /**
  34  * An annotation processing tool framework will {@linkplain
  35  * Processor#process provide an annotation processor with an object
  36  * implementing this interface} so that the processor can query for
  37  * information about a round of annotation processing.
  38  *
  39  * @author Joseph D. Darcy
  40  * @author Scott Seligman
  41  * @author Peter von der Ahé
  42  * @since 1.6
  43  */
  44 public interface RoundEnvironment {
  45     /**
  46      * Returns {@code true} if types generated by this round will not
  47      * be subject to a subsequent round of annotation processing;
  48      * returns {@code false} otherwise.
  49      *
  50      * @return {@code true} if types generated by this round will not
  51      * be subject to a subsequent round of annotation processing;
  52      * returns {@code false} otherwise
  53      */
  54     boolean processingOver();
  55 
  56     /**
  57      * Returns {@code true} if an error was raised in the prior round
  58      * of processing; returns {@code false} otherwise.
  59      *
  60      * @return {@code true} if an error was raised in the prior round
  61      * of processing; returns {@code false} otherwise
  62      */
  63     boolean errorRaised();
  64 
  65     /**
  66      * Returns the root elements for annotation processing generated
  67      * by the prior round.
  68      *
  69      * @return the root elements for annotation processing generated
  70      * by the prior round, or an empty set if there were none
  71      */
  72     Set<? extends Element> getRootElements();
  73 
  74     /**
  75      * Returns the elements annotated with the given annotation type.
  76      * The annotation may appear directly or be inherited.  Only
  77      * package elements and type elements <i>included</i> in this
  78      * round of annotation processing, or declarations of members,
  79      * constructors, parameters, or type parameters declared within
  80      * those, are returned.  Included type elements are {@linkplain
  81      * #getRootElements root types} and any member types nested within
  82      * them.  Elements in a package are not considered included simply
  83      * because a {@code package-info} file for that package was
  84      * created.
  85      *
  86      * @param a  annotation type being requested
  87      * @return the elements annotated with the given annotation type,
  88      * or an empty set if there are none
  89      * @throws IllegalArgumentException if the argument does not
  90      * represent an annotation type
  91      */
  92     Set<? extends Element> getElementsAnnotatedWith(TypeElement a);
  93 
  94     /**
  95      * Returns the elements annotated with the given annotation type.
  96      * The annotation may appear directly or be inherited.  Only
  97      * package elements and type elements <i>included</i> in this
  98      * round of annotation processing, or declarations of members,
  99      * constructors, parameters, or type parameters declared within
 100      * those, are returned.  Included type elements are {@linkplain
 101      * #getRootElements root types} and any member types nested within
 102      * them.  Elements in a package are not considered included simply
 103      * because a {@code package-info} file for that package was
 104      * created.
 105      *
 106      * @param a  annotation type being requested
 107      * @return the elements annotated with the given annotation type,
 108      * or an empty set if there are none
 109      * @throws IllegalArgumentException if the argument does not
 110      * represent an annotation type
 111      */
 112     Set<? extends Element> getElementsAnnotatedWith(Class<? extends Annotation> a);
 113 }