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.javah; //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 NativeHeaderTool extends Tool, OptionChecker { 55 56 /** 57 * Creates a future for a native header task with the given 58 * components and arguments. The task might not have 59 * completed as described in the NativeHeaderTask 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 task; 65 * use {@code System.err} if {@code null} 66 * @param fileManager a file manager; if {@code null} use the 67 * task'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 task options, {@code null} means no options 72 * @param classes class names for which native headers should be generated 73 * @return an object representing the task to be done 74 * @throws RuntimeException if an unrecoverable error 75 * occurred in a user supplied component. The 76 * {@linkplain Throwable#getCause() cause} will be the error in 77 * user code. 78 * @throws IllegalArgumentException if any of the given 79 * compilation units are of other kind than 80 * {@linkplain JavaFileObject.Kind#SOURCE source} 81 */ 82 NativeHeaderTask getTask(Writer out, 83 JavaFileManager fileManager, 84 DiagnosticListener<? super JavaFileObject> diagnosticListener, 85 Iterable<String> options, 86 Iterable<String> classes); 87 88 /** 89 * Returns a new instance of the standard file manager implementation 90 * for this tool. The file manager will use the given diagnostic 91 * listener for producing any non-fatal diagnostics. Fatal errors 92 * will be signalled with the appropriate exceptions. 93 * 94 * <p>The standard file manager will be automatically reopened if 95 * it is accessed after calls to {@code flush} or {@code close}. 96 * The standard file manager must be usable with other tools. 97 * 98 * @param diagnosticListener a diagnostic listener for non-fatal 99 * diagnostics; if {@code null} use the tool's default method 100 * for reporting diagnostics 101 * @param locale the locale to apply when formatting diagnostics; 102 * {@code null} means the {@linkplain Locale#getDefault() default locale}. 103 * @param charset the character set used for decoding bytes; if 104 * {@code null} use the platform default 105 * @return the standard file manager 106 */ 107 StandardJavaFileManager getStandardFileManager( 108 DiagnosticListener<? super JavaFileObject> diagnosticListener, 109 Locale locale, 110 Charset charset); 111 112 /** 113 * Interface representing a future for a native header task. The 114 * task has not yet started. To start the task, call 115 * the {@linkplain #call call} method. 116 * 117 * <p>Before calling the call method, additional aspects of the 118 * task can be configured, for example, by calling the 119 * {@linkplain #setLocale setLocale} method. 120 */ 121 interface NativeHeaderTask extends Callable<Boolean> { 122 123 /** 124 * Set the locale to be applied when formatting diagnostics and 125 * other localized data. 126 * 127 * @param locale the locale to apply; {@code null} means apply no 128 * locale 129 * @throws IllegalStateException if the task has started 130 */ 131 void setLocale(Locale locale); 132 133 /** 134 * Performs this native header task. The task may only 135 * be performed once. Subsequent calls to this method throw 136 * IllegalStateException. 137 * 138 * @return true if and only all the files were processed without errors; 139 * false otherwise 140 * 141 * @throws RuntimeException if an unrecoverable error occurred 142 * in a user-supplied component. The 143 * {@linkplain Throwable#getCause() cause} will be the error 144 * in user code. 145 * @throws IllegalStateException if called more than once 146 */ 147 Boolean call(); 148 } 149 }