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 com.sun.source.util; 27 28 import java.io.IOException; 29 30 import javax.annotation.processing.ProcessingEnvironment; 31 import javax.lang.model.element.Element; 32 import javax.lang.model.element.VariableElement; 33 import javax.lang.model.type.TypeMirror; 34 import javax.lang.model.util.Elements; 35 import javax.lang.model.util.Types; 36 import javax.tools.JavaCompiler.CompilationTask; 37 import javax.tools.JavaFileObject; 38 39 import com.sun.source.tree.CompilationUnitTree; 40 import com.sun.source.tree.Tree; 41 import com.sun.tools.javac.api.BasicJavacTask; 42 import com.sun.tools.javac.processing.JavacProcessingEnvironment; 43 import com.sun.tools.javac.util.Context; 44 45 /** 46 * Provides access to functionality specific to the JDK Java Compiler, javac. 47 * 48 * @author Peter von der Ahé 49 * @author Jonathan Gibbons 50 * @since 1.6 51 */ 52 public abstract class JavacTask implements CompilationTask { 53 54 /** 55 * Returns the {@code JavacTask} for a {@code ProcessingEnvironment}. 56 * If the compiler is being invoked using a 57 * {@link javax.tools.JavaCompiler.CompilationTask CompilationTask}, 58 * then that task will be returned. 59 * @param processingEnvironment the processing environment 60 * @return the {@code JavacTask} for a {@code ProcessingEnvironment} 61 * @since 1.8 62 */ 63 public static JavacTask instance(ProcessingEnvironment processingEnvironment) { 64 if (!processingEnvironment.getClass().getName().equals( 65 "com.sun.tools.javac.processing.JavacProcessingEnvironment")) 66 throw new IllegalArgumentException(); 67 Context c = ((JavacProcessingEnvironment) processingEnvironment).getContext(); 68 JavacTask t = c.get(JavacTask.class); 69 return (t != null) ? t : new BasicJavacTask(c, true); 70 } 71 72 /** 73 * Parses the specified files returning a list of abstract syntax trees. 74 * 75 * @return a list of abstract syntax trees 76 * @throws IOException if an unhandled I/O error occurred in the compiler. 77 * @throws IllegalStateException if the operation cannot be performed at this time. 78 */ 79 public abstract Iterable<? extends CompilationUnitTree> parse() 80 throws IOException; 81 82 /** 83 * Completes all analysis. 84 * 85 * @return a list of elements that were analyzed 86 * @throws IOException if an unhandled I/O error occurred in the compiler. 87 * @throws IllegalStateException if the operation cannot be performed at this time. 88 */ 89 public abstract Iterable<? extends Element> analyze() throws IOException; 90 91 /** 92 * Generates code. 93 * 94 * @return a list of files that were generated 95 * @throws IOException if an unhandled I/O error occurred in the compiler. 96 * @throws IllegalStateException if the operation cannot be performed at this time. 97 */ 98 public abstract Iterable<? extends JavaFileObject> generate() throws IOException; 99 100 /** 101 * Sets a specified listener to receive notification of events 102 * describing the progress of this compilation task. 103 * 104 * If another listener is receiving notifications as a result of a prior 105 * call of this method, then that listener will no longer receive notifications. 106 * 107 * Informally, this method is equivalent to calling {@code removeTaskListener} for 108 * any listener that has been previously set, followed by {@code addTaskListener} 109 * for the new listener. 110 * 111 * @param taskListener the task listener 112 * @throws IllegalStateException if the specified listener has already been added. 113 */ 114 public abstract void setTaskListener(TaskListener taskListener); 115 116 /** 117 * Adds a specified listener so that it receives notification of events 118 * describing the progress of this compilation task. 119 * 120 * This method may be called at any time before or during the compilation. 121 * 122 * @param taskListener the task listener 123 * @throws IllegalStateException if the specified listener has already been added. 124 * @since 1.8 125 */ 126 public abstract void addTaskListener(TaskListener taskListener); 127 128 /** 129 * Removes the specified listener so that it no longer receives 130 * notification of events describing the progress of this 131 * compilation task. 132 * 133 * This method may be called at any time before or during the compilation. 134 * 135 * @param taskListener the task listener 136 * @since 1.8 137 */ 138 public abstract void removeTaskListener(TaskListener taskListener); 139 140 /** 141 * Sets the specified {@link ParameterNameProvider}. It may be used when 142 * {@link VariableElement#getSimpleName()} is called for a method parameter 143 * for which an authoritative name is not found. The given 144 * {@code ParameterNameProvider} may infer a user-friendly name 145 * for the method parameter. 146 * 147 * Setting a new {@code ParameterNameProvider} will clear any previously set 148 * {@code ParameterNameProvider}, which won't be queried any more. 149 * 150 * When no {@code ParameterNameProvider} is set, or when it returns null from 151 * {@link ParameterNameProvider#getParameterName(javax.lang.model.element.VariableElement)}, 152 * an automatically synthesized name is returned from {@code VariableElement.getSimpleName()}. 153 * 154 * @implSpec The default implementation of this method does nothing. 155 * 156 * @param provider the provider. 157 * @since 13 158 */ 159 public void setParameterNameProvider(ParameterNameProvider provider) {} 160 161 /** 162 * Returns a type mirror of the tree node determined by the specified path. 163 * This method has been superseded by methods on 164 * {@link com.sun.source.util.Trees Trees}. 165 * 166 * @param path the path 167 * @return the type mirror 168 * @see com.sun.source.util.Trees#getTypeMirror 169 */ 170 public abstract TypeMirror getTypeMirror(Iterable<? extends Tree> path); 171 172 /** 173 * Returns a utility object for dealing with program elements. 174 * 175 * @return a utility object for dealing with program elements 176 */ 177 public abstract Elements getElements(); 178 179 /** 180 * Returns a utility object for dealing with type mirrors. 181 * 182 * @return the utility object for dealing with type mirrors 183 */ 184 public abstract Types getTypes(); 185 }