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  ;
11  import java.util.List  ;
12  import java.util.Locale  ;
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  ;
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  <String  ,String  > 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   getLocale();
119 }
120
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags