DocumentationTool.java revision 3566:0f8b6aba6279
1/* 2 * Copyright (c) 2005, 2016, 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 * 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 documentation 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 * 146 * @throws IllegalStateException if called more than once 147 */ 148 Boolean call(); 149 } 150 151 /** 152 * Locations specific to {@link DocumentationTool}. 153 * 154 * @see StandardLocation 155 */ 156 enum Location implements JavaFileManager.Location { 157 /** 158 * Location of new documentation files. 159 */ 160 DOCUMENTATION_OUTPUT, 161 162 /** 163 * Location to search for doclets. 164 */ 165 DOCLET_PATH, 166 167 /** 168 * Location to search for taglets. 169 */ 170 TAGLET_PATH; 171 172 public String getName() { return name(); } 173 174 public boolean isOutputLocation() { 175 switch (this) { 176 case DOCUMENTATION_OUTPUT: 177 return true; 178 default: 179 return false; 180 } 181 } 182 } 183 184} 185