2
* Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
3
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
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.
9
* This code is distributed in the hope that it will be useful, but WITHOUT
10
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12
* version 2 for more details (a copy is included in the LICENSE file that
13
* accompanied this code).
15
* You should have received a copy of the GNU General Public License version
16
* 2 along with this work; if not, write to the Free Software Foundation,
17
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20
* or visit www.oracle.com if you need additional information or have any
26
import java.io.IOException;
27
import java.io.PrintWriter;
28
import java.nio.file.Path;
29
import java.nio.file.Paths;
30
import java.util.ArrayList;
31
import java.util.Arrays;
32
import java.util.Collections;
33
import java.util.HashMap;
36
import java.util.stream.Collectors;
37
import java.util.stream.Stream;
39
import javax.tools.DocumentationTool.DocumentationTask;
40
import javax.tools.DocumentationTool;
41
import javax.tools.JavaFileManager;
42
import javax.tools.JavaFileManager.Location;
43
import javax.tools.JavaFileObject;
44
import javax.tools.StandardJavaFileManager;
45
import javax.tools.StandardLocation;
46
import javax.tools.ToolProvider;
48
import jdk.javadoc.internal.api.JavadocTool;
51
* A task to configure and run the documentation tool, javadoc.
53
public class JavadocTask extends AbstractTask<JavadocTask> {
54
private boolean includeStandardOptions;
55
private List<Path> classpath;
56
private List<Path> sourcepath;
58
private List<String> options;
59
private List<String> classes;
60
private List<String> files;
61
private List<JavaFileObject> fileObjects;
62
private JavaFileManager fileManager;
64
private JavadocTool jdtool;
65
private StandardJavaFileManager internalFileManager;
66
private Class<?> docletClass = null; // use the standard doclet by default
69
* Creates a task to execute {@code javadoc} using API mode.
70
* @param toolBox the {@code ToolBox} to use
72
public JavadocTask(ToolBox toolBox) {
73
super(toolBox, Task.Mode.API);
77
* Creates a task to execute {@code javadoc} in a specified mode.
78
* @param toolBox the {@code ToolBox} to use
79
* @param mode the mode to be used
81
public JavadocTask(ToolBox toolBox, Task.Mode mode) {
87
* @param classpath the classpath
88
* @return this task object
90
public JavadocTask classpath(String classpath) {
91
this.classpath = Stream.of(classpath.split(ToolBox.pathSeparator))
92
.filter(s -> !s.isEmpty())
93
.map(s -> Paths.get(s))
94
.collect(Collectors.toList());
100
* @param classpath the classpath
101
* @return this task object
103
public JavadocTask classpath(Path... classpath) {
104
this.classpath = Arrays.asList(classpath);
109
* Sets the classpath.
110
* @param classpath the classpath
111
* @return this task object
113
public JavadocTask classpath(List<Path> classpath) {
114
this.classpath = classpath;
119
* Sets the sourcepath.
120
* @param sourcepath the sourcepath
121
* @return this task object
123
public JavadocTask sourcepath(String sourcepath) {
124
this.sourcepath = Stream.of(sourcepath.split(ToolBox.pathSeparator))
125
.filter(s -> !s.isEmpty())
126
.map(s -> Paths.get(s))
127
.collect(Collectors.toList());
132
* Sets the sourcepath.
133
* @param sourcepath the sourcepath
134
* @return this task object
136
public JavadocTask sourcepath(Path... sourcepath) {
137
this.sourcepath = Arrays.asList(sourcepath);
142
* Sets the sourcepath.
143
* @param sourcepath the sourcepath
144
* @return this task object
146
public JavadocTask sourcepath(List<Path> sourcepath) {
147
this.sourcepath = sourcepath;
152
* Sets the output directory.
153
* @param outdir the output directory
154
* @return this task object
156
public JavadocTask outdir(String outdir) {
157
this.outdir = Paths.get(outdir);
162
* Sets the output directory.
163
* @param outdir the output directory
164
* @return this task object
166
public JavadocTask outdir(Path outdir) {
167
this.outdir = outdir;
173
* @param options the options
174
* @return this task object
176
public JavadocTask options(String... options) {
177
this.options = Arrays.asList(options);
183
* @param options the options
184
* @return this task object
186
public JavadocTask options(List<String> options) {
187
this.options = options;
192
* Sets the files to be documented.
193
* @param files the files
194
* @return this task object
196
public JavadocTask files(String... files) {
197
this.files = Arrays.asList(files);
202
* Sets the files to be documented.
203
* @param files the files
204
* @return this task object
206
public JavadocTask files(Path... files) {
207
this.files = Stream.of(files)
209
.collect(Collectors.toList());
214
* Sets the files to be documented.
215
* @param files the files
216
* @return this task object
218
public JavadocTask files(List<Path> files) {
219
this.files = files.stream()
221
.collect(Collectors.toList());
226
* Sets the sources to be documented.
227
* Each source string is converted into an in-memory object that
228
* can be passed directly to the tool.
229
* @param sources the sources
230
* @return this task object
232
public JavadocTask sources(String... sources) {
233
fileObjects = Stream.of(sources)
234
.map(s -> new ToolBox.JavaSource(s))
235
.collect(Collectors.toList());
240
* Sets the file manager to be used by this task.
241
* @param fileManager the file manager
242
* @return this task object
244
public JavadocTask fileManager(JavaFileManager fileManager) {
245
this.fileManager = fileManager;
250
* Sets the doclet class to be invoked by javadoc.
251
* Note: this is applicable only in API mode.
252
* @param docletClass the user specified doclet
253
* @return this task object
255
public JavadocTask docletClass(Class<?> docletClass) {
256
this.docletClass = docletClass;
262
* @return the name "javadoc"
265
public String name() {
270
* Calls the javadoc tool with the arguments as currently configured.
271
* @return a Result object indicating the outcome of the execution
272
* and the content of any output written to stdout, stderr, or the
273
* main stream by the tool.
276
public Task.Result run() {
277
if (mode == Task.Mode.EXEC)
280
AbstractTask.WriterOutput direct = new AbstractTask.WriterOutput();
281
// The following are to catch output to System.out and System.err,
282
// in case these are used instead of the primary (main) stream
283
AbstractTask.StreamOutput sysOut = new AbstractTask.StreamOutput(System.out, System::setOut);
284
AbstractTask.StreamOutput sysErr = new AbstractTask.StreamOutput(System.err, System::setErr);
286
Map<Task.OutputKind, String> outputMap = new HashMap<>();
288
switch (mode == null ? Task.Mode.API : mode) {
290
rc = runAPI(direct.pw);
293
rc = runCommand(direct.pw);
296
throw new IllegalStateException();
298
} catch (IOException e) {
299
toolBox.out.println("Exception occurred: " + e);
302
outputMap.put(Task.OutputKind.STDOUT, sysOut.close());
303
outputMap.put(Task.OutputKind.STDERR, sysErr.close());
304
outputMap.put(Task.OutputKind.DIRECT, direct.close());
306
return checkExit(new Task.Result(toolBox, this, rc, outputMap));
309
private int runAPI(PrintWriter pw) throws IOException {
311
jdtool = (JavadocTool) ToolProvider.getSystemDocumentationTool();
312
jdtool = new JavadocTool();
314
if (fileManager == null)
315
fileManager = internalFileManager = jdtool.getStandardFileManager(null, null, null);
317
setLocationFromPaths(DocumentationTool.Location.DOCUMENTATION_OUTPUT,
318
Collections.singletonList(outdir));
319
if (classpath != null)
320
setLocationFromPaths(StandardLocation.CLASS_PATH, classpath);
321
if (sourcepath != null)
322
setLocationFromPaths(StandardLocation.SOURCE_PATH, sourcepath);
323
List<String> allOpts = new ArrayList<>();
325
allOpts.addAll(options);
327
Iterable<? extends JavaFileObject> allFiles = joinFiles(files, fileObjects);
328
DocumentationTask task = jdtool.getTask(pw,
330
null, // diagnostic listener; should optionally collect diags
334
return ((DocumentationTask) task).call() ? 0 : 1;
336
if (internalFileManager != null)
337
internalFileManager.close();
341
private void setLocationFromPaths(Location location, List<Path> files) throws IOException {
342
if (!(fileManager instanceof StandardJavaFileManager))
343
throw new IllegalStateException("not a StandardJavaFileManager");
344
((StandardJavaFileManager) fileManager).setLocationFromPaths(location, files);
347
private int runCommand(PrintWriter pw) {
348
List<String> args = getAllArgs();
349
String[] argsArray = args.toArray(new String[args.size()]);
350
return jdk.javadoc.internal.tool.Main.execute(argsArray, pw);
353
private Task.Result runExec() {
354
List<String> args = new ArrayList<>();
355
Path javadoc = toolBox.getJDKTool("javadoc");
356
args.add(javadoc.toString());
357
if (includeStandardOptions) {
358
args.addAll(toolBox.split(System.getProperty("test.tool.vm.opts"), " +"));
360
args.addAll(getAllArgs());
362
String[] argsArray = args.toArray(new String[args.size()]);
363
ProcessBuilder pb = getProcessBuilder();
364
pb.command(argsArray);
366
return runProcess(toolBox, this, pb.start());
367
} catch (IOException | InterruptedException e) {
372
private List<String> getAllArgs() {
373
List<String> args = new ArrayList<>();
375
args.addAll(options);
376
if (outdir != null) {
378
args.add(outdir.toString());
380
if (classpath != null) {
381
args.add("-classpath");
382
args.add(toSearchPath(classpath));
384
if (sourcepath != null) {
385
args.add("-sourcepath");
386
args.add(toSearchPath(sourcepath));
389
args.addAll(classes);
396
private String toSearchPath(List<Path> files) {
397
return files.stream()
399
.collect(Collectors.joining(ToolBox.pathSeparator));
402
private Iterable<? extends JavaFileObject> joinFiles(
403
List<String> files, List<JavaFileObject> fileObjects) {
406
if (internalFileManager == null)
407
internalFileManager = jdtool.getStandardFileManager(null, null, null);
408
Iterable<? extends JavaFileObject> filesAsFileObjects =
409
internalFileManager.getJavaFileObjectsFromStrings(files);
410
if (fileObjects == null)
411
return filesAsFileObjects;
412
List<JavaFileObject> combinedList = new ArrayList<>();
413
for (JavaFileObject o : filesAsFileObjects)
415
combinedList.addAll(fileObjects);