Tue, 09 Oct 2012 19:10:00 -0700
8000663: clean up langtools imports
Reviewed-by: darcy
duke@1 | 1 | /* |
jjg@1357 | 2 | * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved. |
duke@1 | 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
duke@1 | 4 | * |
duke@1 | 5 | * This code is free software; you can redistribute it and/or modify it |
duke@1 | 6 | * under the terms of the GNU General Public License version 2 only, as |
ohair@554 | 7 | * published by the Free Software Foundation. Oracle designates this |
duke@1 | 8 | * particular file as subject to the "Classpath" exception as provided |
ohair@554 | 9 | * by Oracle in the LICENSE file that accompanied this code. |
duke@1 | 10 | * |
duke@1 | 11 | * This code is distributed in the hope that it will be useful, but WITHOUT |
duke@1 | 12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
duke@1 | 13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
duke@1 | 14 | * version 2 for more details (a copy is included in the LICENSE file that |
duke@1 | 15 | * accompanied this code). |
duke@1 | 16 | * |
duke@1 | 17 | * You should have received a copy of the GNU General Public License version |
duke@1 | 18 | * 2 along with this work; if not, write to the Free Software Foundation, |
duke@1 | 19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
duke@1 | 20 | * |
ohair@554 | 21 | * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
ohair@554 | 22 | * or visit www.oracle.com if you need additional information or have any |
ohair@554 | 23 | * questions. |
duke@1 | 24 | */ |
duke@1 | 25 | |
duke@1 | 26 | package javax.annotation.processing; |
duke@1 | 27 | |
duke@1 | 28 | import java.util.Map; |
duke@1 | 29 | import java.util.Locale; |
duke@1 | 30 | import javax.lang.model.SourceVersion; |
duke@1 | 31 | import javax.lang.model.util.Elements; |
duke@1 | 32 | import javax.lang.model.util.Types; |
duke@1 | 33 | |
duke@1 | 34 | /** |
duke@1 | 35 | * An annotation processing tool framework will {@linkplain |
duke@1 | 36 | * Processor#init provide an annotation processor with an object |
duke@1 | 37 | * implementing this interface} so the processor can use facilities |
duke@1 | 38 | * provided by the framework to write new files, report error |
duke@1 | 39 | * messages, and find other utilities. |
duke@1 | 40 | * |
duke@1 | 41 | * <p>Third parties may wish to provide value-add wrappers around the |
duke@1 | 42 | * facility objects from this interface, for example a {@code Filer} |
duke@1 | 43 | * extension that allows multiple processors to coordinate writing out |
duke@1 | 44 | * a single source file. To enable this, for processors running in a |
duke@1 | 45 | * context where their side effects via the API could be visible to |
duke@1 | 46 | * each other, the tool infrastructure must provide corresponding |
duke@1 | 47 | * facility objects that are {@code .equals}, {@code Filer}s that are |
duke@1 | 48 | * {@code .equals}, and so on. In addition, the tool invocation must |
duke@1 | 49 | * be able to be configured such that from the perspective of the |
duke@1 | 50 | * running annotation processors, at least the chosen subset of helper |
duke@1 | 51 | * classes are viewed as being loaded by the same class loader. |
duke@1 | 52 | * (Since the facility objects manage shared state, the implementation |
duke@1 | 53 | * of a wrapper class must know whether or not the same base facility |
duke@1 | 54 | * object has been wrapped before.) |
duke@1 | 55 | * |
duke@1 | 56 | * @author Joseph D. Darcy |
duke@1 | 57 | * @author Scott Seligman |
duke@1 | 58 | * @author Peter von der Ahé |
duke@1 | 59 | * @since 1.6 |
duke@1 | 60 | */ |
duke@1 | 61 | public interface ProcessingEnvironment { |
duke@1 | 62 | /** |
duke@1 | 63 | * Returns the processor-specific options passed to the annotation |
duke@1 | 64 | * processing tool. Options are returned in the form of a map from |
duke@1 | 65 | * option name to option value. For an option with no value, the |
duke@1 | 66 | * corresponding value in the map is {@code null}. |
duke@1 | 67 | * |
duke@1 | 68 | * <p>See documentation of the particular tool infrastructure |
duke@1 | 69 | * being used for details on how to pass in processor-specific |
duke@1 | 70 | * options. For example, a command-line implementation may |
duke@1 | 71 | * distinguish processor-specific options by prefixing them with a |
duke@1 | 72 | * known string like {@code "-A"}; other tool implementations may |
duke@1 | 73 | * follow different conventions or provide alternative mechanisms. |
duke@1 | 74 | * A given implementation may also provide implementation-specific |
duke@1 | 75 | * ways of finding options passed to the tool in addition to the |
duke@1 | 76 | * processor-specific options. |
duke@1 | 77 | * |
duke@1 | 78 | * @return the processor-specific options passed to the tool |
duke@1 | 79 | */ |
duke@1 | 80 | Map<String,String> getOptions(); |
duke@1 | 81 | |
duke@1 | 82 | /** |
duke@1 | 83 | * Returns the messager used to report errors, warnings, and other |
duke@1 | 84 | * notices. |
duke@1 | 85 | * |
duke@1 | 86 | * @return the messager |
duke@1 | 87 | */ |
duke@1 | 88 | Messager getMessager(); |
duke@1 | 89 | |
duke@1 | 90 | /** |
duke@1 | 91 | * Returns the filer used to create new source, class, or auxiliary |
duke@1 | 92 | * files. |
duke@1 | 93 | * |
duke@1 | 94 | * @return the filer |
duke@1 | 95 | */ |
duke@1 | 96 | Filer getFiler(); |
duke@1 | 97 | |
duke@1 | 98 | /** |
duke@1 | 99 | * Returns an implementation of some utility methods for |
duke@1 | 100 | * operating on elements |
duke@1 | 101 | * |
duke@1 | 102 | * @return element utilities |
duke@1 | 103 | */ |
duke@1 | 104 | Elements getElementUtils(); |
duke@1 | 105 | |
duke@1 | 106 | /** |
duke@1 | 107 | * Returns an implementation of some utility methods for |
duke@1 | 108 | * operating on types. |
duke@1 | 109 | * |
duke@1 | 110 | * @return type utilities |
duke@1 | 111 | */ |
duke@1 | 112 | Types getTypeUtils(); |
duke@1 | 113 | |
duke@1 | 114 | /** |
duke@1 | 115 | * Returns the source version that any generated {@linkplain |
duke@1 | 116 | * Filer#createSourceFile source} and {@linkplain |
duke@1 | 117 | * Filer#createClassFile class} files should conform to. |
duke@1 | 118 | * |
duke@1 | 119 | * @return the source version to which generated source and class |
duke@1 | 120 | * files should conform to |
duke@1 | 121 | * @see Processor#getSupportedSourceVersion |
duke@1 | 122 | */ |
duke@1 | 123 | SourceVersion getSourceVersion(); |
duke@1 | 124 | |
duke@1 | 125 | /** |
duke@1 | 126 | * Returns the current locale or {@code null} if no locale is in |
duke@1 | 127 | * effect. The locale can be be used to provide localized |
duke@1 | 128 | * {@linkplain Messager messages}. |
duke@1 | 129 | * |
duke@1 | 130 | * @return the current locale or {@code null} if no locale is in |
duke@1 | 131 | * effect |
duke@1 | 132 | */ |
duke@1 | 133 | Locale getLocale(); |
duke@1 | 134 | } |