1 /* 2 * Copyright (c) 2005, 2017, 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 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 33 /** 34 * Interface to invoke Java™ programming language documentation tools from 35 * programs. 36 * 37 * @since 1.8 38 */ 39 public interface DocumentationTool extends Tool, OptionChecker { 40 /** 41 * Creates a future for a documentation task with the given 42 * components and arguments. The task might not have 43 * completed as described in the DocumentationTask interface. 44 * 45 * <p>If a file manager is provided, it must be able to handle all 46 * locations defined in {@link DocumentationTool.Location}, 47 * as well as 48 * {@link StandardLocation#SOURCE_PATH}, 49 * {@link StandardLocation#CLASS_PATH}, and 50 * {@link StandardLocation#PLATFORM_CLASS_PATH}. 51 * 52 * @param out a Writer for additional output from the tool; 53 * use {@code System.err} if {@code null} 54 * 55 * @param fileManager a file manager; if {@code null} use the 56 * tool's standard file manager 57 * 58 * @param diagnosticListener a diagnostic listener; if {@code null} 59 * use the tool's default method for reporting diagnostics 60 * 61 * @param docletClass a class providing the necessary methods required 62 * of a doclet; a value of {@code null} means to use the standard doclet. 63 * 64 * @param options documentation tool options and doclet options, 65 * {@code null} means no options 66 * 67 * @param compilationUnits the compilation units to compile, {@code 68 * null} means no compilation units 69 * 70 * @return an object representing the compilation 71 * 72 * @throws RuntimeException if an unrecoverable error 73 * occurred in a user supplied component. The 74 * {@linkplain Throwable#getCause() cause} will be the error in 75 * user code. 76 * 77 * @throws IllegalArgumentException if any of the given 78 * compilation units are of other kind than 79 * {@linkplain JavaFileObject.Kind#SOURCE source} 80 */ 81 DocumentationTask getTask(Writer out, 82 JavaFileManager fileManager, 83 DiagnosticListener<? super JavaFileObject> diagnosticListener, 84 Class<?> docletClass, 85 Iterable<String> options, 86 Iterable<? extends JavaFileObject> compilationUnits); 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 signaled 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 compiler's default method 100 * for reporting diagnostics 101 * 102 * @param locale the locale to apply when formatting diagnostics; 103 * {@code null} means the {@linkplain Locale#getDefault() default locale}. 104 * 105 * @param charset the character set used for decoding bytes; if 106 * {@code null} use the platform default 107 * 108 * @return the standard file manager 109 */ 110 StandardJavaFileManager getStandardFileManager( 111 DiagnosticListener<? super JavaFileObject> diagnosticListener, 112 Locale locale, 113 Charset charset); 114 115 /** 116 * Interface representing a future for a documentation task. 117 * To start the task, call the {@linkplain #call call} method. 118 * 119 * <p>Before calling the {@code call} method, additional aspects of the 120 * task can be configured, for example, by calling the 121 * {@linkplain #setLocale setLocale} method. 122 */ 123 interface DocumentationTask extends Callable<Boolean> { 124 /** 125 * Adds root modules to be taken into account during module 126 * resolution. 127 * Invalid module names may cause either 128 * {@code IllegalArgumentException} to be thrown, 129 * or diagnostics to be reported when the task is started. 130 * @param moduleNames the names of the root modules 131 * @throws IllegalArgumentException may be thrown for some 132 * invalid module names 133 * @throws IllegalStateException if the task has started 134 * @since 9 135 */ 136 void addModules(Iterable<String> moduleNames); 137 138 /** 139 * Sets the locale to be applied when formatting diagnostics and 140 * other localized data. 141 * 142 * @param locale the locale to apply; {@code null} means apply no 143 * locale 144 * @throws IllegalStateException if the task has started 145 */ 146 void setLocale(Locale locale); 147 148 /** 149 * Performs this documentation task. The task may only 150 * be performed once. Subsequent calls to this method throw 151 * IllegalStateException. 152 * 153 * @return true if and only all the files were processed without errors; 154 * false otherwise 155 * 156 * @throws RuntimeException if an unrecoverable error occurred 157 * in a user-supplied component. The 158 * {@linkplain Throwable#getCause() cause} will be the error 159 * in user code. 160 * 161 * @throws IllegalStateException if called more than once 162 */ 163 Boolean call(); 164 } 165 166 /** 167 * Locations specific to {@link DocumentationTool}. 168 * 169 * @see StandardLocation 170 */ 171 enum Location implements JavaFileManager.Location { 172 /** 173 * Location of new documentation files. 174 */ 175 DOCUMENTATION_OUTPUT, 176 177 /** 178 * Location to search for doclets. 179 */ 180 DOCLET_PATH, 181 182 /** 183 * Location to search for taglets. 184 */ 185 TAGLET_PATH; 186 187 public String getName() { return name(); } 188 189 public boolean isOutputLocation() { 190 switch (this) { 191 case DOCUMENTATION_OUTPUT: 192 return true; 193 default: 194 return false; 195 } 196 } 197 } 198 199 }