001: /*
002: * @(#)AnnotationProcessorEnvironment.java 1.7 04/07/19
003: *
004: * Copyright (c) 2004, Sun Microsystems, Inc.
005: * All rights reserved.
006: *
007: * Redistribution and use in source and binary forms, with or without
008: * modification, are permitted provided that the following conditions are met:
009: *
010: * * Redistributions of source code must retain the above copyright
011: * notice, this list of conditions and the following disclaimer.
012: * * Redistributions in binary form must reproduce the above copyright
013: * notice, this list of conditions and the following disclaimer in the
014: * documentation and/or other materials provided with the distribution.
015: * * Neither the name of the Sun Microsystems, Inc. nor the names of
016: * its contributors may be used to endorse or promote products derived from
017: * this software without specific prior written permission.
018: *
019: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
020: * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
021: * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
022: * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
023: * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
024: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
025: * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
026: * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
027: * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
028: * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
029: * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
030: */
031:
032: package com.sun.mirror.apt;
033:
034: import java.util.Collection;
035: import java.util.Map;
036:
037: import com.sun.mirror.declaration.*;
038: import com.sun.mirror.util.*;
039:
040: /**
041: * The environment encapsulating the state needed by an annotation processor.
042: * An annotation processing tool makes this environment available
043: * to all annotation processors.
044: *
045: * <p> When an annotation processing tool is invoked, it is given a
046: * set of type declarations on which to operate. These
047: * are refered to as the <i>specified</i> types.
048: * The type declarations said to be <i>included</i> in this invocation
049: * consist of the specified types and any types nested within them.
050: *
051: * <p> {@link DeclarationFilter}
052: * provides a simple way to select just the items of interest
053: * when a method returns a collection of declarations.
054: *
055: * @author Joseph D. Darcy
056: * @author Scott Seligman
057: * @version 1.7 04/07/19
058: * @since 1.5
059: */
060:
061: public interface AnnotationProcessorEnvironment {
062:
063: /**
064: * Returns the options passed to the annotation processing tool.
065: * Options are returned in the form of a map from option name
066: * (such as <tt>"-encoding"</tt>) to option value.
067: * For an option with no value (such as <tt>"-help"</tt>), the
068: * corresponding value in the map is <tt>null</tt>.
069: *
070: * <p> Options beginning with <tt>"-A"</tt> are <i>processor-specific.</i>
071: * Such options are unrecognized by the tool, but intended to be used by
072: * some annotation processor.
073: *
074: * @return the options passed to the tool
075: */
076: Map<String, String> getOptions();
077:
078: /**
079: * Returns the messager used to report errors, warnings, and other
080: * notices.
081: *
082: * @return the messager
083: */
084: Messager getMessager();
085:
086: /**
087: * Returns the filer used to create new source, class, or auxiliary
088: * files.
089: *
090: * @return the filer
091: */
092: Filer getFiler();
093:
094: /**
095: * Returns the declarations of the types specified when the
096: * annotation processing tool was invoked.
097: *
098: * @return the types specified when the tool was invoked, or an
099: * empty collection if there were none
100: */
101: Collection<TypeDeclaration> getSpecifiedTypeDeclarations();
102:
103: /**
104: * Returns the declaration of a package given its fully qualified name.
105: *
106: * @param name fully qualified package name, or "" for the unnamed package
107: * @return the declaration of the named package, or null if it cannot
108: * be found
109: */
110: PackageDeclaration getPackage(String name);
111:
112: /**
113: * Returns the declaration of a type given its fully qualified name.
114: *
115: * @param name fully qualified type name
116: * @return the declaration of the named type, or null if it cannot be
117: * found
118: */
119: TypeDeclaration getTypeDeclaration(String name);
120:
121: /**
122: * A convenience method that returns the declarations of the types
123: * {@linkplain AnnotationProcessorEnvironment <i>included</i>}
124: * in this invocation of the annotation processing tool.
125: *
126: * @return the declarations of the types included in this invocation
127: * of the tool, or an empty collection if there are none
128: */
129: Collection<TypeDeclaration> getTypeDeclarations();
130:
131: /**
132: * Returns the declarations annotated with the given annotation type.
133: * Only declarations of the types
134: * {@linkplain AnnotationProcessorEnvironment <i>included</i>}
135: * in this invocation of the annotation processing tool, or
136: * declarations of members, parameters, or type parameters
137: * declared within those, are returned.
138: *
139: * @param a annotation type being requested
140: * @return the declarations annotated with the given annotation type,
141: * or an empty collection if there are none
142: */
143: Collection<Declaration> getDeclarationsAnnotatedWith(
144: AnnotationTypeDeclaration a);
145:
146: /**
147: * Returns an implementation of some utility methods for
148: * operating on declarations.
149: *
150: * @return declaration utilities
151: */
152: Declarations getDeclarationUtils();
153:
154: /**
155: * Returns an implementation of some utility methods for
156: * operating on types.
157: *
158: * @return type utilities
159: */
160: Types getTypeUtils();
161:
162: /**
163: * Add a listener. If the listener is currently registered to listen,
164: * adding it again will have no effect.
165: *
166: * @param listener The listener to add.
167: * @throws NullPointerException if the listener is null
168: */
169: void addListener(AnnotationProcessorListener listener);
170:
171: /**
172: * Remove a listener. If the listener is not currently listening,
173: * the method call does nothing.
174: *
175: * @param listener The listener to remove.
176: * @throws NullPointerException if the listener is null
177: */
178: void removeListener(AnnotationProcessorListener listener);
179: }
|