jdk

1
/*
2
 * Copyright (c) 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.
8
 *
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).
14
 *
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.
18
 *
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
21
 * questions.
22
 */
23

24
package toolbox;
25

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;
34
import java.util.List;
35
import java.util.Map;
36
import java.util.stream.Collectors;
37
import java.util.stream.Stream;
38

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;
47

48
import jdk.javadoc.internal.api.JavadocTool;
49

50
/**
51
 * A task to configure and run the documentation tool, javadoc.
52
 */
53
public class JavadocTask extends AbstractTask<JavadocTask> {
54
    private boolean includeStandardOptions;
55
    private List<Path> classpath;
56
    private List<Path> sourcepath;
57
    private Path outdir;
58
    private List<String> options;
59
    private List<String> classes;
60
    private List<String> files;
61
    private List<JavaFileObject> fileObjects;
62
    private JavaFileManager fileManager;
63

64
    private JavadocTool jdtool;
65
    private StandardJavaFileManager internalFileManager;
66
    private Class<?> docletClass = null; // use the standard doclet by default
67

68
    /**
69
     * Creates a task to execute {@code javadoc} using API mode.
70
     * @param toolBox the {@code ToolBox} to use
71
     */
72
    public JavadocTask(ToolBox toolBox) {
73
        super(toolBox, Task.Mode.API);
74
    }
75

76
    /**
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
80
     */
81
    public JavadocTask(ToolBox toolBox, Task.Mode mode) {
82
        super(toolBox, mode);
83
    }
84

85
    /**
86
     * Sets the classpath.
87
     * @param classpath the classpath
88
     * @return this task object
89
     */
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());
95
        return this;
96
    }
97

98
    /**
99
     * Sets the classpath.
100
     * @param classpath the classpath
101
     * @return this task object
102
     */
103
    public JavadocTask classpath(Path... classpath) {
104
        this.classpath = Arrays.asList(classpath);
105
        return this;
106
    }
107

108
    /**
109
     * Sets the classpath.
110
     * @param classpath the classpath
111
     * @return this task object
112
     */
113
    public JavadocTask classpath(List<Path> classpath) {
114
        this.classpath = classpath;
115
        return this;
116
    }
117

118
    /**
119
     * Sets the sourcepath.
120
     * @param sourcepath the sourcepath
121
     * @return this task object
122
     */
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());
128
        return this;
129
    }
130

131
    /**
132
     * Sets the sourcepath.
133
     * @param sourcepath the sourcepath
134
     * @return this task object
135
     */
136
    public JavadocTask sourcepath(Path... sourcepath) {
137
        this.sourcepath = Arrays.asList(sourcepath);
138
        return this;
139
    }
140

141
    /**
142
     * Sets the sourcepath.
143
     * @param sourcepath the sourcepath
144
     * @return this task object
145
     */
146
    public JavadocTask sourcepath(List<Path> sourcepath) {
147
        this.sourcepath = sourcepath;
148
        return this;
149
    }
150

151
    /**
152
     * Sets the output directory.
153
     * @param outdir the output directory
154
     * @return this task object
155
     */
156
    public JavadocTask outdir(String outdir) {
157
        this.outdir = Paths.get(outdir);
158
        return this;
159
    }
160

161
    /**
162
     * Sets the output directory.
163
     * @param outdir the output directory
164
     * @return this task object
165
     */
166
    public JavadocTask outdir(Path outdir) {
167
        this.outdir = outdir;
168
        return this;
169
    }
170

171
    /**
172
     * Sets the options.
173
     * @param options the options
174
     * @return this task object
175
     */
176
    public JavadocTask options(String... options) {
177
        this.options = Arrays.asList(options);
178
        return this;
179
    }
180

181
    /**
182
     * Sets the options.
183
     * @param options the options
184
     * @return this task object
185
     */
186
    public JavadocTask options(List<String> options) {
187
        this.options = options;
188
        return this;
189
    }
190

191
    /**
192
     * Sets the files to be documented.
193
     * @param files the files
194
     * @return this task object
195
     */
196
    public JavadocTask files(String... files) {
197
        this.files = Arrays.asList(files);
198
        return this;
199
    }
200

201
    /**
202
     * Sets the files to be documented.
203
     * @param files the files
204
     * @return this task object
205
     */
206
    public JavadocTask files(Path... files) {
207
        this.files = Stream.of(files)
208
                .map(Path::toString)
209
                .collect(Collectors.toList());
210
        return this;
211
    }
212

213
    /**
214
     * Sets the files to be documented.
215
     * @param files the files
216
     * @return this task object
217
     */
218
    public JavadocTask files(List<Path> files) {
219
        this.files = files.stream()
220
                .map(Path::toString)
221
                .collect(Collectors.toList());
222
        return this;
223
    }
224

225
    /**
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
231
     */
232
    public JavadocTask sources(String... sources) {
233
        fileObjects = Stream.of(sources)
234
                .map(s -> new ToolBox.JavaSource(s))
235
                .collect(Collectors.toList());
236
        return this;
237
    }
238

239
    /**
240
     * Sets the file manager to be used by this task.
241
     * @param fileManager the file manager
242
     * @return this task object
243
     */
244
    public JavadocTask fileManager(JavaFileManager fileManager) {
245
        this.fileManager = fileManager;
246
        return this;
247
    }
248

249
    /**
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
254
     */
255
    public JavadocTask docletClass(Class<?> docletClass) {
256
        this.docletClass = docletClass;
257
        return this;
258
    }
259

260
    /**
261
     * {@inheritDoc}
262
     * @return the name "javadoc"
263
     */
264
    @Override
265
    public String name() {
266
        return "javadoc";
267
    }
268

269
    /**
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.
274
     */
275
    @Override
276
    public Task.Result run() {
277
        if (mode == Task.Mode.EXEC)
278
            return runExec();
279

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);
285
        int rc;
286
        Map<Task.OutputKind, String> outputMap = new HashMap<>();
287
        try {
288
            switch (mode == null ? Task.Mode.API : mode) {
289
                case API:
290
                    rc = runAPI(direct.pw);
291
                    break;
292
                case CMDLINE:
293
                    rc = runCommand(direct.pw);
294
                    break;
295
                default:
296
                    throw new IllegalStateException();
297
            }
298
        } catch (IOException e) {
299
            toolBox.out.println("Exception occurred: " + e);
300
            rc = 99;
301
        } finally {
302
            outputMap.put(Task.OutputKind.STDOUT, sysOut.close());
303
            outputMap.put(Task.OutputKind.STDERR, sysErr.close());
304
            outputMap.put(Task.OutputKind.DIRECT, direct.close());
305
        }
306
        return checkExit(new Task.Result(toolBox, this, rc, outputMap));
307
    }
308

309
    private int runAPI(PrintWriter pw) throws IOException {
310
        try {
311
            jdtool = (JavadocTool) ToolProvider.getSystemDocumentationTool();
312
            jdtool = new JavadocTool();
313

314
            if (fileManager == null)
315
                fileManager = internalFileManager = jdtool.getStandardFileManager(null, null, null);
316
            if (outdir != 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<>();
324
            if (options != null)
325
                allOpts.addAll(options);
326

327
            Iterable<? extends JavaFileObject> allFiles = joinFiles(files, fileObjects);
328
            DocumentationTask task = jdtool.getTask(pw,
329
                    fileManager,
330
                    null,  // diagnostic listener; should optionally collect diags
331
                    docletClass,
332
                    allOpts,
333
                    allFiles);
334
            return ((DocumentationTask) task).call() ? 0 : 1;
335
        } finally {
336
            if (internalFileManager != null)
337
                internalFileManager.close();
338
        }
339
    }
340

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);
345
    }
346

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);
351
    }
352

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"), " +"));
359
        }
360
        args.addAll(getAllArgs());
361

362
        String[] argsArray = args.toArray(new String[args.size()]);
363
        ProcessBuilder pb = getProcessBuilder();
364
        pb.command(argsArray);
365
        try {
366
            return runProcess(toolBox, this, pb.start());
367
        } catch (IOException | InterruptedException e) {
368
            throw new Error(e);
369
        }
370
    }
371

372
    private List<String> getAllArgs() {
373
        List<String> args = new ArrayList<>();
374
        if (options != null)
375
            args.addAll(options);
376
        if (outdir != null) {
377
            args.add("-d");
378
            args.add(outdir.toString());
379
        }
380
        if (classpath != null) {
381
            args.add("-classpath");
382
            args.add(toSearchPath(classpath));
383
        }
384
        if (sourcepath != null) {
385
            args.add("-sourcepath");
386
            args.add(toSearchPath(sourcepath));
387
        }
388
        if (classes != null)
389
            args.addAll(classes);
390
        if (files != null)
391
            args.addAll(files);
392

393
        return args;
394
    }
395

396
    private String toSearchPath(List<Path> files) {
397
        return files.stream()
398
            .map(Path::toString)
399
            .collect(Collectors.joining(ToolBox.pathSeparator));
400
    }
401

402
    private Iterable<? extends JavaFileObject> joinFiles(
403
            List<String> files, List<JavaFileObject> fileObjects) {
404
        if (files == null)
405
            return 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)
414
            combinedList.add(o);
415
        combinedList.addAll(fileObjects);
416
        return combinedList;
417
    }
418
}
419