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.tools.javap; //javax.tools; 27 28 import java.io.Writer; 29 import java.nio.charset.Charset; 30 import java.util.Locale; 31 import java.util.concurrent.Callable; 32 import javax.tools.Diagnostic; 33 import javax.tools.DiagnosticListener; 34 import javax.tools.JavaFileManager; 35 import javax.tools.JavaFileObject; 36 import javax.tools.OptionChecker; 37 import javax.tools.StandardJavaFileManager; 38 import javax.tools.StandardLocation; 39 import javax.tools.Tool; 40 41 /** 42 * This class is intended to be put in javax.tools. 43 * 44 * @see DiagnosticListener 45 * @see Diagnostic 46 * @see JavaFileManager 47 * @since 1.7 48 * 49 * <p><b>This is NOT part of any supported API. 50 * If you write code that depends on this, you do so at your own risk. 51 * This code and its internal interfaces are subject to change or 52 * deletion without notice.</b> 53 */ 54 public interface DisassemblerTool extends Tool, OptionChecker { 55 56 /** 57 * Creates a future for a disassembly task with the given 58 * components and arguments. The task might not have 59 * completed as described in the DissemblerTask interface. 60 * 61 * <p>If a file manager is provided, it must be able to handle all 62 * locations defined in {@link StandardLocation}. 63 * 64 * @param out a Writer for additional output from the compiler; 65 * use {@code System.err} if {@code null} 66 * @param fileManager a file manager; if {@code null} use the 67 * compiler's standard filemanager 68 * @param diagnosticListener a diagnostic listener; if {@code 69 * null} use the compiler's default method for reporting 70 * diagnostics 71 * @param options compiler options, {@code null} means no options 72 * @param classes class names (for annotation processing), {@code 73 * null} means no class names 74 * @return a task to perform the disassembly 75 * @throws RuntimeException if an unrecoverable error 76 * occurred in a user supplied component. The 77 * {@linkplain Throwable#getCause() cause} will be the error in 78 * user code. 79 * @throws IllegalArgumentException if any of the given 80 * compilation units are of other kind than 81 * {@linkplain JavaFileObject.Kind#SOURCE source} 82 */ 83 DisassemblerTask getTask(Writer out, 84 JavaFileManager fileManager, 85 DiagnosticListener<? super JavaFileObject> diagnosticListener, 86 Iterable<String> options, 87 Iterable<String> classes); 88 89 /** 90 * Returns a new instance of the standard file manager implementation 91 * for this tool. The file manager will use the given diagnostic 92 * listener for producing any non-fatal diagnostics. Fatal errors 93 * will be signalled with the appropriate exceptions. 94 * 95 * <p>The standard file manager will be automatically reopened if 96 * it is accessed after calls to {@code flush} or {@code close}. 97 * The standard file manager must be usable with other tools. 98 * 99 * @param diagnosticListener a diagnostic listener for non-fatal 100 * diagnostics; if {@code null} use the compiler's default method 101 * for reporting diagnostics 102 * @param locale the locale to apply when formatting diagnostics; 103 * {@code null} means the {@linkplain Locale#getDefault() default locale}. 104 * @param charset the character set used for decoding bytes; if 105 * {@code null} use the platform default 106 * @return the standard file manager 107 */ 108 StandardJavaFileManager getStandardFileManager( 109 DiagnosticListener<? super JavaFileObject> diagnosticListener, 110 Locale locale, 111 Charset charset); 112 113 /** 114 * Interface representing a future for a disassembly task. The 115 * task has not yet started. To start the task, call 116 * the {@linkplain #call call} method. 117 * 118 * <p>Before calling the call method, additional aspects of the 119 * task can be configured, for example, by calling the 120 * {@linkplain #setLocale setLocale} method. 121 */ 122 interface DisassemblerTask extends Callable<Boolean> { 123 124 /** 125 * Set the locale to be applied when formatting diagnostics and 126 * other localized data. 127 * 128 * @param locale the locale to apply; {@code null} means apply no 129 * locale 130 * @throws IllegalStateException if the task has started 131 */ 132 void setLocale(Locale locale); 133 134 /** 135 * Performs this compilation task. The compilation may only 136 * be performed once. Subsequent calls to this method throw 137 * IllegalStateException. 138 * 139 * @return true if and only all the files compiled without errors; 140 * false otherwise 141 * 142 * @throws RuntimeException if an unrecoverable error occurred 143 * in a user-supplied component. The 144 * {@linkplain Throwable#getCause() cause} will be the error 145 * in user code. 146 * @throws IllegalStateException if called more than once 147 */ 148 Boolean call(); 149 } 150 }