1 /*
2 * Copyright (c) 2004, 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 com.sun.mirror.apt;
27
28
29 import java.util.Collection;
30 import java.util.Map;
31
32 import com.sun.mirror.declaration.*;
33 import com.sun.mirror.util.*;
34
35
36 /**
37 * The environment encapsulating the state needed by an annotation processor.
38 * An annotation processing tool makes this environment available
39 * to all annotation processors.
40 *
41 * <p> When an annotation processing tool is invoked, it is given a
42 * set of type declarations on which to operate. These
43 * are refered to as the <i>specified</i> types.
44 * The type declarations said to be <i>included</i> in this invocation
45 * consist of the specified types and any types nested within them.
46 *
47 * <p> {@link DeclarationFilter}
48 * provides a simple way to select just the items of interest
49 * when a method returns a collection of declarations.
50 *
51 * @deprecated All components of this API have been superseded by the
52 * standardized annotation processing API. The replacement for the
53 * functionality of this interface is {@link
54 * javax.annotation.processing.ProcessingEnvironment}.
55 *
56 * @author Joseph D. Darcy
57 * @author Scott Seligman
58 * @since 1.5
59 */
60 @Deprecated
61 @SuppressWarnings("deprecation")
62 public interface AnnotationProcessorEnvironment {
63
64 /**
65 * Returns the options passed to the annotation processing tool.
66 * Options are returned in the form of a map from option name
67 * (such as <tt>"-encoding"</tt>) to option value.
68 * For an option with no value (such as <tt>"-help"</tt>), the
69 * corresponding value in the map is <tt>null</tt>.
70 *
71 * <p> Options beginning with <tt>"-A"</tt> are <i>processor-specific.</i>
72 * Such options are unrecognized by the tool, but intended to be used by
73 * some annotation processor.
74 *
75 * @return the options passed to the tool
76 */
77 Map<String,String> getOptions();
78
79 /**
80 * Returns the messager used to report errors, warnings, and other
81 * notices.
82 *
83 * @return the messager
84 */
85 Messager getMessager();
86
87 /**
88 * Returns the filer used to create new source, class, or auxiliary
89 * files.
90 *
91 * @return the filer
92 */
93 Filer getFiler();
94
95
96 /**
97 * Returns the declarations of the types specified when the
98 * annotation processing tool was invoked.
99 *
100 * @return the types specified when the tool was invoked, or an
101 * empty collection if there were none
102 */
103 Collection<TypeDeclaration> getSpecifiedTypeDeclarations();
104
105 /**
106 * Returns the declaration of a package given its fully qualified name.
107 *
108 * @param name fully qualified package name, or "" for the unnamed package
109 * @return the declaration of the named package, or null if it cannot
110 * be found
111 */
112 PackageDeclaration getPackage(String name);
113
114 /**
115 * Returns the declaration of a type given its fully qualified name.
116 *
117 * @param name fully qualified type name
118 * @return the declaration of the named type, or null if it cannot be
119 * found
120 */
121 TypeDeclaration getTypeDeclaration(String name);
122
123 /**
124 * A convenience method that returns the declarations of the types
125 * {@linkplain AnnotationProcessorEnvironment <i>included</i>}
126 * in this invocation of the annotation processing tool.
127 *
128 * @return the declarations of the types included in this invocation
129 * of the tool, or an empty collection if there are none
130 */
131 Collection<TypeDeclaration> getTypeDeclarations();
132
133 /**
134 * Returns the declarations annotated with the given annotation type.
135 * Only declarations of the types
136 * {@linkplain AnnotationProcessorEnvironment <i>included</i>}
137 * in this invocation of the annotation processing tool, or
138 * declarations of members, parameters, or type parameters
139 * declared within those, are returned.
140 *
141 * @param a annotation type being requested
142 * @return the declarations annotated with the given annotation type,
143 * or an empty collection if there are none
144 */
145 Collection<Declaration> getDeclarationsAnnotatedWith(
146 AnnotationTypeDeclaration a);
147
148 /**
149 * Returns an implementation of some utility methods for
150 * operating on declarations.
151 *
152 * @return declaration utilities
153 */
154 Declarations getDeclarationUtils();
155
156 /**
157 * Returns an implementation of some utility methods for
158 * operating on types.
159 *
160 * @return type utilities
161 */
162 Types getTypeUtils();
163
164 /**
165 * Add a listener. If the listener is currently registered to listen,
166 * adding it again will have no effect.
167 *
168 * @param listener The listener to add.
169 * @throws NullPointerException if the listener is null
170 */
171 void addListener(AnnotationProcessorListener listener);
172
173
174 /**
175 * Remove a listener. If the listener is not currently listening,
176 * the method call does nothing.
177 *
178 * @param listener The listener to remove.
179 * @throws NullPointerException if the listener is null
180 */
181 void removeListener(AnnotationProcessorListener listener);
182 }