Thu, 15 Nov 2012 23:07:24 -0800
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
Reviewed-by: darcy
1 /*
2 * Copyright (c) 2005, 2012, 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 package javax.tools;
27 import java.io.Writer;
28 import java.nio.charset.Charset;
29 import java.util.Locale;
30 import java.util.concurrent.Callable;
32 /**
33 * Interface to invoke Java™ programming language documentation tools from
34 * programs.
35 */
36 public interface DocumentationTool extends Tool, OptionChecker {
37 /**
38 * Creates a future for a documentation task with the given
39 * components and arguments. The task might not have
40 * completed as described in the DocumentationTask interface.
41 *
42 * <p>If a file manager is provided, it must be able to handle all
43 * locations defined in {@link DocumentationTool.Location},
44 * as well as
45 * {@link StandardLocation#SOURCE_PATH},
46 * {@link StandardLocation#CLASS_PATH}, and
47 * {@link StandardLocation#PLATFORM_CLASS_PATH}.
48 *
49 * @param out a Writer for additional output from the tool;
50 * use {@code System.err} if {@code null}
51 *
52 * @param fileManager a file manager; if {@code null} use the
53 * tool's standard filemanager
54 *
55 * @param diagnosticListener a diagnostic listener; if {@code null}
56 * use the tool's default method for reporting diagnostics
57 *
58 * @param docletClass a class providing the necessary methods required
59 * of a doclet
60 *
61 * @param options documentation tool options and doclet options,
62 * {@code null} means no options
63 *
64 * @param compilationUnits the compilation units to compile, {@code
65 * null} means no compilation units
66 *
67 * @return an object representing the compilation
68 *
69 * @throws RuntimeException if an unrecoverable error
70 * occurred in a user supplied component. The
71 * {@linkplain Throwable#getCause() cause} will be the error in
72 * user code.
73 *
74 * @throws IllegalArgumentException if any of the given
75 * compilation units are of other kind than
76 * {@linkplain JavaFileObject.Kind#SOURCE source}
77 */
78 DocumentationTask getTask(Writer out,
79 JavaFileManager fileManager,
80 DiagnosticListener<? super JavaFileObject> diagnosticListener,
81 Class<?> docletClass,
82 Iterable<String> options,
83 Iterable<? extends JavaFileObject> compilationUnits);
85 /**
86 * Gets a new instance of the standard file manager implementation
87 * for this tool. The file manager will use the given diagnostic
88 * listener for producing any non-fatal diagnostics. Fatal errors
89 * will be signaled with the appropriate exceptions.
90 *
91 * <p>The standard file manager will be automatically reopened if
92 * it is accessed after calls to {@code flush} or {@code close}.
93 * The standard file manager must be usable with other tools.
94 *
95 * @param diagnosticListener a diagnostic listener for non-fatal
96 * diagnostics; if {@code null} use the compiler's default method
97 * for reporting diagnostics
98 *
99 * @param locale the locale to apply when formatting diagnostics;
100 * {@code null} means the {@linkplain Locale#getDefault() default locale}.
101 *
102 * @param charset the character set used for decoding bytes; if
103 * {@code null} use the platform default
104 *
105 * @return the standard file manager
106 */
107 StandardJavaFileManager getStandardFileManager(
108 DiagnosticListener<? super JavaFileObject> diagnosticListener,
109 Locale locale,
110 Charset charset);
112 /**
113 * Interface representing a future for a documentation 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 DocumentationTask extends Callable<Boolean> {
122 /**
123 * Set the locale to be applied when formatting diagnostics and
124 * other localized data.
125 *
126 * @param locale the locale to apply; {@code null} means apply no
127 * locale
128 * @throws IllegalStateException if the task has started
129 */
130 void setLocale(Locale locale);
132 /**
133 * Performs this documentation task. The task may only
134 * be performed once. Subsequent calls to this method throw
135 * IllegalStateException.
136 *
137 * @return true if and only all the files were processed without errors;
138 * false otherwise
139 *
140 * @throws RuntimeException if an unrecoverable error occurred
141 * in a user-supplied component. The
142 * {@linkplain Throwable#getCause() cause} will be the error
143 * in user code.
144 *
145 * @throws IllegalStateException if called more than once
146 */
147 Boolean call();
148 }
150 /**
151 * Locations specific to {@link DocumentationTool}.
152 *
153 * @see StandardLocation
154 */
155 enum Location implements JavaFileManager.Location {
156 /**
157 * Location of new documentation files.
158 */
159 DOCUMENTATION_OUTPUT,
161 /**
162 * Location to search for doclets.
163 */
164 DOCLET_PATH,
166 /**
167 * Location to search for taglets.
168 */
169 TAGLET_PATH;
171 public String getName() { return name(); }
173 public boolean isOutputLocation() {
174 switch (this) {
175 case DOCUMENTATION_OUTPUT:
176 return true;
177 default:
178 return false;
179 }
180 }
181 }
183 }