001 /*
002 * Copyright 2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package com.sun.mirror.apt;
027
028
029 import java.util.Collection;
030 import java.util.Map;
031
032 import com.sun.mirror.declaration.*;
033 import com.sun.mirror.util.*;
034
035
036 /**
037 * The environment encapsulating the state needed by an annotation processor.
038 * An annotation processing tool makes this environment available
039 * to all annotation processors.
040 *
041 * <p> When an annotation processing tool is invoked, it is given a
042 * set of type declarations on which to operate. These
043 * are refered to as the <i>specified</i> types.
044 * The type declarations said to be <i>included</i> in this invocation
045 * consist of the specified types and any types nested within them.
046 *
047 * <p> {@link DeclarationFilter}
048 * provides a simple way to select just the items of interest
049 * when a method returns a collection of declarations.
050 *
051 * @author Joseph D. Darcy
052 * @author Scott Seligman
053 * @since 1.5
054 */
055
056 public interface AnnotationProcessorEnvironment {
057
058 /**
059 * Returns the options passed to the annotation processing tool.
060 * Options are returned in the form of a map from option name
061 * (such as <tt>"-encoding"</tt>) to option value.
062 * For an option with no value (such as <tt>"-help"</tt>), the
063 * corresponding value in the map is <tt>null</tt>.
064 *
065 * <p> Options beginning with <tt>"-A"</tt> are <i>processor-specific.</i>
066 * Such options are unrecognized by the tool, but intended to be used by
067 * some annotation processor.
068 *
069 * @return the options passed to the tool
070 */
071 Map<String,String> getOptions();
072
073 /**
074 * Returns the messager used to report errors, warnings, and other
075 * notices.
076 *
077 * @return the messager
078 */
079 Messager getMessager();
080
081 /**
082 * Returns the filer used to create new source, class, or auxiliary
083 * files.
084 *
085 * @return the filer
086 */
087 Filer getFiler();
088
089
090
091 /**
092 * Returns the declarations of the types specified when the
093 * annotation processing tool was invoked.
094 *
095 * @return the types specified when the tool was invoked, or an
096 * empty collection if there were none
097 */
098 Collection<TypeDeclaration> getSpecifiedTypeDeclarations();
099
100 /**
101 * Returns the declaration of a package given its fully qualified name.
102 *
103 * @param name fully qualified package name, or "" for the unnamed package
104 * @return the declaration of the named package, or null if it cannot
105 * be found
106 */
107 PackageDeclaration getPackage(String name);
108
109 /**
110 * Returns the declaration of a type given its fully qualified name.
111 *
112 * @param name fully qualified type name
113 * @return the declaration of the named type, or null if it cannot be
114 * found
115 */
116 TypeDeclaration getTypeDeclaration(String name);
117
118 /**
119 * A convenience method that returns the declarations of the types
120 * {@linkplain AnnotationProcessorEnvironment <i>included</i>}
121 * in this invocation of the annotation processing tool.
122 *
123 * @return the declarations of the types included in this invocation
124 * of the tool, or an empty collection if there are none
125 */
126 Collection<TypeDeclaration> getTypeDeclarations();
127
128 /**
129 * Returns the declarations annotated with the given annotation type.
130 * Only declarations of the types
131 * {@linkplain AnnotationProcessorEnvironment <i>included</i>}
132 * in this invocation of the annotation processing tool, or
133 * declarations of members, parameters, or type parameters
134 * declared within those, are returned.
135 *
136 * @param a annotation type being requested
137 * @return the declarations annotated with the given annotation type,
138 * or an empty collection if there are none
139 */
140 Collection<Declaration> getDeclarationsAnnotatedWith(
141 AnnotationTypeDeclaration a);
142
143 /**
144 * Returns an implementation of some utility methods for
145 * operating on declarations.
146 *
147 * @return declaration utilities
148 */
149 Declarations getDeclarationUtils();
150
151 /**
152 * Returns an implementation of some utility methods for
153 * operating on types.
154 *
155 * @return type utilities
156 */
157 Types getTypeUtils();
158
159 /**
160 * Add a listener. If the listener is currently registered to listen,
161 * adding it again will have no effect.
162 *
163 * @param listener The listener to add.
164 * @throws NullPointerException if the listener is null
165 */
166 void addListener(AnnotationProcessorListener listener);
167
168
169 /**
170 * Remove a listener. If the listener is not currently listening,
171 * the method call does nothing.
172 *
173 * @param listener The listener to remove.
174 * @throws NullPointerException if the listener is null
175 */
176 void removeListener(AnnotationProcessorListener listener);
177 }