001: /*
002: * Copyright 2005-2006 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 javax.annotation.processing;
027:
028: import java.util.Map;
029: import java.util.List;
030: import java.util.Locale;
031: import javax.lang.model.SourceVersion;
032: import javax.lang.model.util.Elements;
033: import javax.lang.model.util.Types;
034: import java.io.File;
035:
036: /**
037: * An annotation processing tool framework will {@linkplain
038: * Processor#init provide an annotation processor with an object
039: * implementing this interface} so the processor can use facilities
040: * provided by the framework to write new files, report error
041: * messages, and find other utilities.
042: *
043: * <p>Third parties may wish to provide value-add wrappers around the
044: * facility objects from this interface, for example a {@code Filer}
045: * extension that allows multiple processors to coordinate writing out
046: * a single source file. To enable this, for processors running in a
047: * context where their side effects via the API could be visible to
048: * each other, the tool infrastructure must provide corresponding
049: * facility objects that are {@code .equals}, {@code Filer}s that are
050: * {@code .equals}, and so on. In addition, the tool invocation must
051: * be able to be configured such that from the perspective of the
052: * running annotation processors, at least the chosen subset of helper
053: * classes are viewed as being loaded by the same class loader.
054: * (Since the facility objects manage shared state, the implementation
055: * of a wrapper class must know whether or not the same base facility
056: * object has been wrapped before.)
057: *
058: * @author Joseph D. Darcy
059: * @author Scott Seligman
060: * @author Peter von der Ahé
061: * @version 1.11 07/05/05
062: * @since 1.6
063: */
064: public interface ProcessingEnvironment {
065: /**
066: * Returns the processor-specific options passed to the annotation
067: * processing tool. Options are returned in the form of a map from
068: * option name to option value. For an option with no value, the
069: * corresponding value in the map is {@code null}.
070: *
071: * <p>See documentation of the particular tool infrastructure
072: * being used for details on how to pass in processor-specific
073: * options. For example, a command-line implementation may
074: * distinguish processor-specific options by prefixing them with a
075: * known string like {@code "-A"}; other tool implementations may
076: * follow different conventions or provide alternative mechanisms.
077: * A given implementation may also provide implementation-specific
078: * ways of finding options passed to the tool in addition to the
079: * processor-specific options.
080: *
081: * @return the processor-specific options passed to the tool
082: */
083: Map<String, String> getOptions();
084:
085: /**
086: * Returns the messager used to report errors, warnings, and other
087: * notices.
088: *
089: * @return the messager
090: */
091: Messager getMessager();
092:
093: /**
094: * Returns the filer used to create new source, class, or auxiliary
095: * files.
096: *
097: * @return the filer
098: */
099: Filer getFiler();
100:
101: /**
102: * Returns an implementation of some utility methods for
103: * operating on elements
104: *
105: * @return element utilities
106: */
107: Elements getElementUtils();
108:
109: /**
110: * Returns an implementation of some utility methods for
111: * operating on types.
112: *
113: * @return type utilities
114: */
115: Types getTypeUtils();
116:
117: /**
118: * Returns the source version that any generated {@linkplain
119: * Filer#createSourceFile source} and {@linkplain
120: * Filer#createClassFile class} files should conform to.
121: *
122: * @return the source version to which generated source and class
123: * files should conform to
124: * @see Processor#getSupportedSourceVersion
125: */
126: SourceVersion getSourceVersion();
127:
128: /**
129: * Returns the current locale or {@code null} if no locale is in
130: * effect. The locale can be be used to provide localized
131: * {@linkplain Messager messages}.
132: *
133: * @return the current locale or {@code null} if no locale is in
134: * effect
135: */
136: Locale getLocale();
137: }
|