1 /* 2 * Copyright (c) 2005, 2013, 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.Supported 52 public abstract class JavacTask implements CompilationTask { 53 54 /** 55 * Get 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 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 * Parse 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 * Complete 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 * Generate 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 * The specified listener will 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 * @throws IllegalStateException if the specified listener has already been added. 112 */ 113 public abstract void setTaskListener(TaskListener taskListener); 114 115 /** 116 * The specified listener will receive 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 * @throws IllegalStateException if the specified listener has already been added. 122 * @since 1.8 123 */ 124 public abstract void addTaskListener(TaskListener taskListener); 125 126 /** 127 * The specified listener will no longer receive notification of events 128 * describing the progress of this compilation task. 129 * 130 * This method may be called at any time before or during the compilation. 131 * 132 * @since 1.8 133 */ 134 public abstract void removeTaskListener(TaskListener taskListener); 135 136 /** 137 * Get a type mirror of the tree node determined by the specified path. 138 * This method has been superceded by methods on 139 * {@link com.sun.source.util.Trees Trees}. 140 * @see com.sun.source.util.Trees#getTypeMirror 141 */ 142 public abstract TypeMirror getTypeMirror(Iterable<? extends Tree> path); 143 144 /** 145 * Get a utility object for dealing with program elements. 146 */ 147 public abstract Elements getElements(); 148 149 /** 150 * Get a utility object for dealing with type mirrors. 151 */ 152 public abstract Types getTypes(); 153 }