AnnotationProcessorEnvironment


1   /*
2    * @(#)AnnotationProcessorEnvironment.java  1.7 04/07/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL.  Use is subject to license terms.
6    */
7   
8   package com.sun.mirror.apt;
9   
10  
11  import java.util.Collection  ;
12  import java.util.Map  ;
13  
14  import com.sun.mirror.declaration.*;
15  import com.sun.mirror.util.*;
16  
17  
18  /**
19   * The environment encapsulating the state needed by an annotation processor.
20   * An annotation processing tool makes this environment available
21   * to all annotation processors.
22   *
23   * <p> When an annotation processing tool is invoked, it is given a
24   * set of type declarations on which to operate.  These
25   * are refered to as the <i>specified</i> types.
26   * The type declarations said to be <i>included</i> in this invocation
27   * consist of the specified types and any types nested within them.
28   *
29   * <p> {@link DeclarationFilter}
30   * provides a simple way to select just the items of interest
31   * when a method returns a collection of declarations.
32   *
33   * @author Joseph D. Darcy
34   * @author Scott Seligman
35   * @version 1.7 04/07/19
36   * @since 1.5
37   */
38  
39  public interface AnnotationProcessorEnvironment {
40  
41      /**
42       * Returns the options passed to the annotation processing tool.
43       * Options are returned in the form of a map from option name
44       * (such as <tt>"-encoding"</tt>) to option value.
45       * For an option with no value (such as <tt>"-help"</tt>), the
46       * corresponding value in the map is <tt>null</tt>.
47       *
48       * <p> Options beginning with <tt>"-A"</tt> are <i>processor-specific.</i>
49       * Such options are unrecognized by the tool, but intended to be used by
50       * some annotation processor.
51       *
52       * @return the options passed to the tool
53       */
54      Map  <String  ,String  > getOptions();
55  
56      /**
57       * Returns the messager used to report errors, warnings, and other
58       * notices.
59       *
60       * @return the messager
61       */
62      Messager getMessager();
63  
64      /**
65       * Returns the filer used to create new source, class, or auxiliary
66       * files.
67       *
68       * @return the filer
69       */
70      Filer getFiler();
71  
72  
73  
74      /**
75       * Returns the declarations of the types specified when the
76       * annotation processing tool was invoked.
77       *
78       * @return the types specified when the tool was invoked, or an
79       * empty collection if there were none
80       */
81      Collection  <TypeDeclaration> getSpecifiedTypeDeclarations();
82  
83      /**
84       * Returns the declaration of a package given its fully qualified name.
85       *
86       * @param name  fully qualified package name, or "" for the unnamed package
87       * @return the declaration of the named package, or null if it cannot
88       * be found
89       */
90      PackageDeclaration getPackage(String   name);
91  
92      /**
93       * Returns the declaration of a type given its fully qualified name.
94       *
95       * @param name  fully qualified type name
96       * @return the declaration of the named type, or null if it cannot be
97       * found
98       */
99      TypeDeclaration getTypeDeclaration(String   name);
100 
101     /**
102      * A convenience method that returns the declarations of the types
103      * {@linkplain AnnotationProcessorEnvironment <i>included</i>}
104      * in this invocation of the annotation processing tool.
105      *
106      * @return the declarations of the types included in this invocation
107      * of the tool, or an empty collection if there are none
108      */
109     Collection  <TypeDeclaration> getTypeDeclarations();
110 
111     /**
112      * Returns the declarations annotated with the given annotation type.
113      * Only declarations of the types
114      * {@linkplain AnnotationProcessorEnvironment <i>included</i>}
115      * in this invocation of the annotation processing tool, or
116      * declarations of members, parameters, or type parameters
117      * declared within those, are returned.
118      *
119      * @param a  annotation type being requested
120      * @return the declarations annotated with the given annotation type,
121      * or an empty collection if there are none
122      */
123     Collection  <Declaration> getDeclarationsAnnotatedWith(
124                         AnnotationTypeDeclaration a);
125 
126     /**
127      * Returns an implementation of some utility methods for
128      * operating on declarations.
129      *
130      * @return declaration utilities
131      */
132     Declarations getDeclarationUtils();
133 
134     /**
135      * Returns an implementation of some utility methods for
136      * operating on types.
137      *
138      * @return type utilities
139      */
140     Types getTypeUtils();
141 
142     /**
143      * Add a listener.  If the listener is currently registered to listen,
144      * adding it again will have no effect.
145      *
146      * @param listener The listener to add.
147      * @throws NullPointerException if the listener is null
148      */
149     void addListener(AnnotationProcessorListener listener);
150  
151  
152     /**
153      * Remove a listener.  If the listener is not currently listening,
154      * the method call does nothing.
155      *
156      * @param listener The listener to remove.
157      * @throws NullPointerException if the listener is null
158      */
159     void removeListener(AnnotationProcessorListener listener);
160 }
161
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags