KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > annotation > processing > ProcessingEnvironment


1 /*
2  * @(#)ProcessingEnvironment.java 1.5 06/07/17
3  *
4  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package javax.annotation.processing;
9
10 import java.util.Map JavaDoc;
11 import java.util.List JavaDoc;
12 import java.util.Locale JavaDoc;
13 import javax.lang.model.SourceVersion;
14 import javax.lang.model.util.Elements;
15 import javax.lang.model.util.Types;
16 import java.io.File JavaDoc;
17
18 /**
19  * An annotation processing tool framework will {@linkplain
20  * Processor#init provide an annotation processor with an object
21  * implementing this interface} so the processor can use facilities
22  * provided by the framework to write new files, report error
23  * messages, and find other utilities.
24  *
25  * <p>Third parties may wish to provide value-add wrappers around the
26  * facility objects from this interface, for example a {@code Filer}
27  * extension that allows multiple processors to coordinate writing out
28  * a single source file. To enable this, for processors running in a
29  * context where their side effects via the API could be visible to
30  * each other, the tool infrastructure must provide corresponding
31  * facility objects that are {@code .equals}, {@code Filer}s that are
32  * {@code .equals}, and so on. In addition, the tool invocation must
33  * be able to be configured such that from the perspective of the
34  * running annotation processors, at least the chosen subset of helper
35  * classes are viewed as being loaded by the same class loader.
36  * (Since the facility objects manage shared state, the implementation
37  * of a wrapper class must know whether or not the same base facility
38  * object has been wrapped before.)
39  *
40  * @author Joseph D. Darcy
41  * @author Scott Seligman
42  * @author Peter von der Ah&eacute;
43  * @version 1.5 06/07/17
44  * @since 1.6
45  */

46 public interface ProcessingEnvironment {
47     /**
48      * Returns the processor-specific options passed to the annotation
49      * processing tool. Options are returned in the form of a map from
50      * option name to option value. For an option with no value, the
51      * corresponding value in the map is {@code null}.
52      *
53      * <p>See documentation of the particular tool infrastructure
54      * being used for details on how to pass in processor-specific
55      * options. For example, a command-line implementation may
56      * distinguish processor-specific options by prefixing them with a
57      * known string like {@code "-A"}; other tool implementations may
58      * follow different conventions or provide alternative mechanisms.
59      * A given implementation may also provide implementation-specific
60      * ways of finding options passed to the tool in addition to the
61      * processor-specific options.
62      *
63      * @return the processor-specific options passed to the tool
64      */

65     Map JavaDoc<String JavaDoc,String JavaDoc> getOptions();
66
67     /**
68      * Returns the messager used to report errors, warnings, and other
69      * notices.
70      *
71      * @return the messager
72      */

73     Messager getMessager();
74
75     /**
76      * Returns the filer used to create new source, class, or auxiliary
77      * files.
78      *
79      * @return the filer
80      */

81     Filer getFiler();
82
83     /**
84      * Returns an implementation of some utility methods for
85      * operating on elements
86      *
87      * @return element utilities
88      */

89     Elements getElementUtils();
90
91     /**
92      * Returns an implementation of some utility methods for
93      * operating on types.
94      *
95      * @return type utilities
96      */

97     Types getTypeUtils();
98
99     /**
100      * Returns the source version that any generated {@linkplain
101      * Filer#createSourceFile source} and {@linkplain
102      * Filer#createClassFile class} files should conform to.
103      *
104      * @return the source version to which generated source and class
105      * files should conform to
106      * @see Processor#getSupportedSourceVersion
107      */

108     SourceVersion getSourceVersion();
109
110     /**
111      * Returns the current locale or {@code null} if no locale is in
112      * effect. The locale can be be used to provide localized
113      * {@linkplain Messager messages}.
114      *
115      * @return the current locale or {@code null} if no locale is in
116      * effect
117      */

118     Locale JavaDoc getLocale();
119 }
120
Popular Tags