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: import java.util.Collection;
029: import java.util.Map;
030:
031: import com.sun.mirror.declaration.*;
032: import com.sun.mirror.util.*;
033:
034: /**
035: * The environment encapsulating the state needed by an annotation processor.
036: * An annotation processing tool makes this environment available
037: * to all annotation processors.
038: *
039: * <p> When an annotation processing tool is invoked, it is given a
040: * set of type declarations on which to operate. These
041: * are refered to as the <i>specified</i> types.
042: * The type declarations said to be <i>included</i> in this invocation
043: * consist of the specified types and any types nested within them.
044: *
045: * <p> {@link DeclarationFilter}
046: * provides a simple way to select just the items of interest
047: * when a method returns a collection of declarations.
048: *
049: * @author Joseph D. Darcy
050: * @author Scott Seligman
051: * @version 1.14 07/05/05
052: * @since 1.5
053: */
054:
055: public interface AnnotationProcessorEnvironment {
056:
057: /**
058: * Returns the options passed to the annotation processing tool.
059: * Options are returned in the form of a map from option name
060: * (such as <tt>"-encoding"</tt>) to option value.
061: * For an option with no value (such as <tt>"-help"</tt>), the
062: * corresponding value in the map is <tt>null</tt>.
063: *
064: * <p> Options beginning with <tt>"-A"</tt> are <i>processor-specific.</i>
065: * Such options are unrecognized by the tool, but intended to be used by
066: * some annotation processor.
067: *
068: * @return the options passed to the tool
069: */
070: Map<String, String> getOptions();
071:
072: /**
073: * Returns the messager used to report errors, warnings, and other
074: * notices.
075: *
076: * @return the messager
077: */
078: Messager getMessager();
079:
080: /**
081: * Returns the filer used to create new source, class, or auxiliary
082: * files.
083: *
084: * @return the filer
085: */
086: Filer getFiler();
087:
088: /**
089: * Returns the declarations of the types specified when the
090: * annotation processing tool was invoked.
091: *
092: * @return the types specified when the tool was invoked, or an
093: * empty collection if there were none
094: */
095: Collection<TypeDeclaration> getSpecifiedTypeDeclarations();
096:
097: /**
098: * Returns the declaration of a package given its fully qualified name.
099: *
100: * @param name fully qualified package name, or "" for the unnamed package
101: * @return the declaration of the named package, or null if it cannot
102: * be found
103: */
104: PackageDeclaration getPackage(String name);
105:
106: /**
107: * Returns the declaration of a type given its fully qualified name.
108: *
109: * @param name fully qualified type name
110: * @return the declaration of the named type, or null if it cannot be
111: * found
112: */
113: TypeDeclaration getTypeDeclaration(String name);
114:
115: /**
116: * A convenience method that returns the declarations of the types
117: * {@linkplain AnnotationProcessorEnvironment <i>included</i>}
118: * in this invocation of the annotation processing tool.
119: *
120: * @return the declarations of the types included in this invocation
121: * of the tool, or an empty collection if there are none
122: */
123: Collection<TypeDeclaration> getTypeDeclarations();
124:
125: /**
126: * Returns the declarations annotated with the given annotation type.
127: * Only declarations of the types
128: * {@linkplain AnnotationProcessorEnvironment <i>included</i>}
129: * in this invocation of the annotation processing tool, or
130: * declarations of members, parameters, or type parameters
131: * declared within those, are returned.
132: *
133: * @param a annotation type being requested
134: * @return the declarations annotated with the given annotation type,
135: * or an empty collection if there are none
136: */
137: Collection<Declaration> getDeclarationsAnnotatedWith(
138: AnnotationTypeDeclaration a);
139:
140: /**
141: * Returns an implementation of some utility methods for
142: * operating on declarations.
143: *
144: * @return declaration utilities
145: */
146: Declarations getDeclarationUtils();
147:
148: /**
149: * Returns an implementation of some utility methods for
150: * operating on types.
151: *
152: * @return type utilities
153: */
154: Types getTypeUtils();
155:
156: /**
157: * Add a listener. If the listener is currently registered to listen,
158: * adding it again will have no effect.
159: *
160: * @param listener The listener to add.
161: * @throws NullPointerException if the listener is null
162: */
163: void addListener(AnnotationProcessorListener listener);
164:
165: /**
166: * Remove a listener. If the listener is not currently listening,
167: * the method call does nothing.
168: *
169: * @param listener The listener to remove.
170: * @throws NullPointerException if the listener is null
171: */
172: void removeListener(AnnotationProcessorListener listener);
173: }
|