RoundEnvironment.java revision 2571:10fc81ac75b4 
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
26package javax.annotation.processing;
27
28import javax.lang.model.element.Element;
29import javax.lang.model.element.TypeElement;
30import java.util.Set;
31import 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 */
44public 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}
114