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 26package javax.tools; 27 28import java.io.Writer; 29import java.nio.charset.Charset; 30import java.util.Locale; 31import java.util.concurrent.Callable; 32 33/** 34 * Interface to invoke Java™ programming language documentation tools from 35 * programs. 36 * 37 * @since 1.8 38 */ 39public 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 filemanager 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. The 117 * task has not yet started. To start the task, call 118 * the {@linkplain #call call} method. 119 * 120 * <p>Before calling the call method, additional aspects of the 121 * task can be configured, for example, by calling the 122 * {@linkplain #setLocale setLocale} method. 123 */ 124 interface DocumentationTask extends Callable<Boolean> { 125 /** 126 * Adds root modules to be taken into account during module 127 * resolution. 128 * Invalid module names may cause either 129 * {@code IllegalArgumentException} to be thrown, 130 * or diagnostics to be reported when the task is started. 131 * @param moduleNames the names of the root modules 132 * @throws IllegalArgumentException may be thrown for some 133 * invalid module names 134 * @throws IllegalStateException if the task has started 135 * @since 9 136 */ 137 void addModules(Iterable<String> moduleNames); 138 139 /** 140 * Sets the locale to be applied when formatting diagnostics and 141 * other localized data. 142 * 143 * @param locale the locale to apply; {@code null} means apply no 144 * locale 145 * @throws IllegalStateException if the task has started 146 */ 147 void setLocale(Locale locale); 148 149 /** 150 * Performs this documentation task. The task may only 151 * be performed once. Subsequent calls to this method throw 152 * IllegalStateException. 153 * 154 * @return true if and only all the files were processed without errors; 155 * false otherwise 156 * 157 * @throws RuntimeException if an unrecoverable error occurred 158 * in a user-supplied component. The 159 * {@linkplain Throwable#getCause() cause} will be the error 160 * in user code. 161 * 162 * @throws IllegalStateException if called more than once 163 */ 164 Boolean call(); 165 } 166 167 /** 168 * Locations specific to {@link DocumentationTool}. 169 * 170 * @see StandardLocation 171 */ 172 enum Location implements JavaFileManager.Location { 173 /** 174 * Location of new documentation files. 175 */ 176 DOCUMENTATION_OUTPUT, 177 178 /** 179 * Location to search for doclets. 180 */ 181 DOCLET_PATH, 182 183 /** 184 * Location to search for taglets. 185 */ 186 TAGLET_PATH; 187 188 public String getName() { return name(); } 189 190 public boolean isOutputLocation() { 191 switch (this) { 192 case DOCUMENTATION_OUTPUT: 193 return true; 194 default: 195 return false; 196 } 197 } 198 } 199 200} 201