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 public abstract class JavacTask implements CompilationTask { 52 53 /** 54 * Returns the {@code JavacTask} for a {@code ProcessingEnvironment}. 55 * If the compiler is being invoked using a 56 * {@link javax.tools.JavaCompiler.CompilationTask CompilationTask}, 57 * then that task will be returned. 58 * @param processingEnvironment the processing environment 59 * @return the {@code JavacTask} for a {@code ProcessingEnvironment} 60 * @since 1.8 61 */ 62 public static JavacTask instance(ProcessingEnvironment processingEnvironment) { 63 if (!processingEnvironment.getClass().getName().equals( 64 "com.sun.tools.javac.processing.JavacProcessingEnvironment")) 65 throw new IllegalArgumentException(); 66 Context c = ((JavacProcessingEnvironment) processingEnvironment).getContext(); 67 JavacTask t = c.get(JavacTask.class); 68 return (t != null) ? t : new BasicJavacTask(c, true); 69 } 70 71 /** 72 * Parses the specified files returning a list of abstract syntax trees. 73 * 74 * @return a list of abstract syntax trees 75 * @throws IOException if an unhandled I/O error occurred in the compiler. 76 * @throws IllegalStateException if the operation cannot be performed at this time. 77 */ 78 public abstract Iterable<? extends CompilationUnitTree> parse() 79 throws IOException; 80 81 /** 82 * Completes all analysis. 83 * 84 * @return a list of elements that were analyzed 85 * @throws IOException if an unhandled I/O error occurred in the compiler. 86 * @throws IllegalStateException if the operation cannot be performed at this time. 87 */ 88 public abstract Iterable<? extends Element> analyze() throws IOException; 89 90 /** 91 * Generates code. 92 * 93 * @return a list of files that were generated 94 * @throws IOException if an unhandled I/O error occurred in the compiler. 95 * @throws IllegalStateException if the operation cannot be performed at this time. 96 */ 97 public abstract Iterable<? extends JavaFileObject> generate() throws IOException; 98 99 /** 100 * Sets a specified listener to receive notification of events 101 * describing the progress of this compilation task. 102 * 103 * If another listener is receiving notifications as a result of a prior 104 * call of this method, then that listener will no longer receive notifications. 105 * 106 * Informally, this method is equivalent to calling {@code removeTaskListener} for 107 * any listener that has been previously set, followed by {@code addTaskListener} 108 * for the new listener. 109 * 110 * @param taskListener the task listener 111 * @throws IllegalStateException if the specified listener has already been added. 112 */ 113 public abstract void setTaskListener(TaskListener taskListener); 114 115 /** 116 * Adds a specified listener so that it receives notification of events 117 * describing the progress of this compilation task. 118 * 119 * This method may be called at any time before or during the compilation. 120 * 121 * @param taskListener the task listener 122 * @throws IllegalStateException if the specified listener has already been added. 123 * @since 1.8 124 */ 125 public abstract void addTaskListener(TaskListener taskListener); 126 127 /** 128 * Removes the specified listener so that it no longer receives 129 * notification of events describing the progress of this 130 * compilation task. 131 * 132 * This method may be called at any time before or during the compilation. 133 * 134 * @param taskListener the task listener 135 * @since 1.8 136 */ 137 public abstract void removeTaskListener(TaskListener taskListener); 138 139 /** 140 * Returns a type mirror of the tree node determined by the specified path. 141 * This method has been superceded by methods on 142 * {@link com.sun.source.util.Trees Trees}. 143 * 144 * @param path the path 145 * @return the type mirror 146 * @see com.sun.source.util.Trees#getTypeMirror 147 */ 148 public abstract TypeMirror getTypeMirror(Iterable<? extends Tree> path); 149 150 /** 151 * Returns a utility object for dealing with program elements. 152 * 153 * @return a utility object for dealing with program elements 154 */ 155 public abstract Elements getElements(); 156 157 /** 158 * Returns a utility object for dealing with type mirrors. 159 * 160 * @return the utility object for dealing with type mirrors 161 */ 162 public abstract Types getTypes(); 163 }