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