1 /* 2 * Copyright (c) 2005, 2014, 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.type.TypeMirror; 33 import javax.lang.model.util.Elements; 34 import javax.lang.model.util.Types; 35 import javax.tools.JavaCompiler.CompilationTask; 36 import javax.tools.JavaFileObject; 37 38 import com.sun.source.tree.CompilationUnitTree; 39 import com.sun.source.tree.Tree; 40 import com.sun.tools.javac.api.BasicJavacTask; 41 import com.sun.tools.javac.processing.JavacProcessingEnvironment; 42 import com.sun.tools.javac.util.Context; 43 44 /** 45 * Provides access to functionality specific to the JDK Java Compiler, javac. 46 * 47 * @author Peter von der Ahé 48 * @author Jonathan Gibbons 49 * @since 1.6 50 */ 51 @jdk.Exported 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 * Returns a type mirror of the tree node determined by the specified path. 142 * This method has been superceded by methods on 143 * {@link com.sun.source.util.Trees Trees}. 144 * 145 * @param path the path 146 * @return the type mirror 147 * @see com.sun.source.util.Trees#getTypeMirror 148 */ 149 public abstract TypeMirror getTypeMirror(Iterable<? extends Tree> path); 150 151 /** 152 * Returns a utility object for dealing with program elements. 153 * 154 * @return a utility object for dealing with program elements 155 */ 156 public abstract Elements getElements(); 157 158 /** 159 * Returns a utility object for dealing with type mirrors. 160 * 161 * @return the utility object for dealing with type mirrors 162 */ 163 public abstract Types getTypes(); 164 }