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