1 /*
2 * Copyright (c) 1997, 2014, 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
26 package com.sun.tools.javadoc;
27
28 import java.io.File;
29 import java.io.FileNotFoundException;
30 import java.io.IOException;
31 import java.io.PrintWriter;
32 import java.nio.file.Path;
33 import java.util.ArrayList;
34 import java.util.Collection;
35 import java.util.Collections;
36 import java.util.Objects;
37
38 import javax.tools.JavaFileManager;
39 import javax.tools.JavaFileObject;
40 import javax.tools.StandardJavaFileManager;
41 import javax.tools.StandardLocation;
42
43 import com.sun.javadoc.*;
44 import com.sun.tools.javac.file.JavacFileManager;
45 import com.sun.tools.javac.main.CommandLine;
46 import com.sun.tools.javac.main.Option;
47 import com.sun.tools.javac.file.BaseFileManager;
48 import com.sun.tools.javac.platform.PlatformDescription;
49 import com.sun.tools.javac.platform.PlatformUtils;
50 import com.sun.tools.javac.util.ClientCodeException;
51 import com.sun.tools.javac.util.Context;
52 import com.sun.tools.javac.util.List;
53 import com.sun.tools.javac.util.ListBuffer;
54 import com.sun.tools.javac.util.Log;
55 import com.sun.tools.javac.util.Options;
56
57 import static com.sun.tools.javac.code.Flags.*;
58
59 /**
60 * Main program of Javadoc.
61 * Previously named "Main".
62 *
63 * <p><b>This is NOT part of any supported API.
64 * If you write code that depends on this, you do so at your own risk.
65 * This code and its internal interfaces are subject to change or
66 * deletion without notice.</b>
67 *
68 * @since 1.2
69 * @author Robert Field
70 * @author Neal Gafter (rewrite)
71 */
72 public class Start extends ToolOption.Helper {
73 /** Context for this invocation. */
74 private final Context context;
75
76 private final String defaultDocletClassName;
77 private final ClassLoader docletParentClassLoader;
78
79 private static final String javadocName = "javadoc";
80
81 private static final String standardDocletClassName =
82 "com.sun.tools.doclets.standard.Standard";
83
84 private final long defaultFilter = PUBLIC | PROTECTED;
85
86 private final Messager messager;
87
88 private DocletInvoker docletInvoker;
89
90 /**
91 * In API mode, exceptions thrown while calling the doclet are
92 * propagated using ClientCodeException.
93 */
94 private boolean apiMode;
95
96 private JavaFileManager fileManager;
97
98 Start(String programName,
99 PrintWriter errWriter,
100 PrintWriter warnWriter,
101 PrintWriter noticeWriter,
102 String defaultDocletClassName) {
103 this(programName, errWriter, warnWriter, noticeWriter, defaultDocletClassName, null);
104 }
105
106 Start(String programName,
107 PrintWriter errWriter,
108 PrintWriter warnWriter,
109 PrintWriter noticeWriter,
110 String defaultDocletClassName,
111 ClassLoader docletParentClassLoader) {
112 context = new Context();
113 messager = new Messager(context, programName, errWriter, warnWriter, noticeWriter);
114 this.defaultDocletClassName = defaultDocletClassName;
115 this.docletParentClassLoader = docletParentClassLoader;
116 }
117
118 Start(String programName, String defaultDocletClassName) {
119 this(programName, defaultDocletClassName, null);
120 }
121
122 Start(String programName, String defaultDocletClassName,
123 ClassLoader docletParentClassLoader) {
124 context = new Context();
125 messager = new Messager(context, programName);
126 this.defaultDocletClassName = defaultDocletClassName;
127 this.docletParentClassLoader = docletParentClassLoader;
128 }
129
130 Start(String programName, ClassLoader docletParentClassLoader) {
131 this(programName, standardDocletClassName, docletParentClassLoader);
132 }
133
134 Start(String programName) {
135 this(programName, standardDocletClassName);
136 }
137
138 Start(ClassLoader docletParentClassLoader) {
139 this(javadocName, docletParentClassLoader);
140 }
141
142 Start() {
143 this(javadocName);
144 }
145
146 public Start(Context context) {
147 this.context = Objects.requireNonNull(context);
148 apiMode = true;
149 defaultDocletClassName = standardDocletClassName;
150 docletParentClassLoader = null;
151
152 Log log = context.get(Log.logKey);
153 if (log instanceof Messager)
154 messager = (Messager) log;
155 else {
156 PrintWriter out = context.get(Log.outKey);
157 messager = (out == null) ? new Messager(context, javadocName)
158 : new Messager(context, javadocName, out, out, out);
159 }
160 }
161
162 /**
163 * Usage
164 */
165 @Override
166 void usage() {
167 usage(true);
168 }
169
170 void usage(boolean exit) {
171 usage("main.usage", "-help", null, exit);
172 }
173
174 @Override
175 void Xusage() {
176 Xusage(true);
177 }
178
179 void Xusage(boolean exit) {
180 usage("main.Xusage", "-X", "main.Xusage.foot", exit);
181 }
182
183 private void usage(String main, String doclet, String foot, boolean exit) {
184 // RFE: it would be better to replace the following with code to
185 // write a header, then help for each option, then a footer.
186 messager.notice(main);
187
188 // let doclet print usage information (does nothing on error)
189 if (docletInvoker != null) {
190 // RFE: this is a pretty bad way to get the doclet to show
191 // help info. Moreover, the output appears on stdout,
192 // and <i>not</i> on any of the standard streams passed
193 // to javadoc, and in particular, not to the noticeWriter
194 // But, to fix this, we need to fix the Doclet API.
195 docletInvoker.optionLength(doclet);
196 }
197
198 if (foot != null)
199 messager.notice(foot);
200
201 if (exit) exit();
202 }
203
204 /**
205 * Exit
206 */
207 private void exit() {
208 messager.exit();
209 }
210
211
212 /**
213 * Main program - external wrapper
214 */
215 int begin(String... argv) {
216 boolean ok = begin(null, argv, Collections.<JavaFileObject> emptySet());
217 return ok ? 0 : 1;
218 }
219
220 public boolean begin(Class<?> docletClass, Iterable<String> options, Iterable<? extends JavaFileObject> fileObjects) {
221 Collection<String> opts = new ArrayList<>();
222 for (String opt: options) opts.add(opt);
223 return begin(docletClass, opts.toArray(new String[opts.size()]), fileObjects);
224 }
225
226 private boolean begin(Class<?> docletClass, String[] options, Iterable<? extends JavaFileObject> fileObjects) {
227 boolean failed = false;
228
229 try {
230 failed = !parseAndExecute(docletClass, options, fileObjects);
231 } catch (Messager.ExitJavadoc exc) {
232 // ignore, we just exit this way
233 } catch (OutOfMemoryError ee) {
234 messager.error(Messager.NOPOS, "main.out.of.memory");
235 failed = true;
236 } catch (ClientCodeException e) {
237 // simply rethrow these exceptions, to be caught and handled by JavadocTaskImpl
238 throw e;
239 } catch (Error ee) {
240 ee.printStackTrace(System.err);
241 messager.error(Messager.NOPOS, "main.fatal.error");
242 failed = true;
243 } catch (Exception ee) {
244 ee.printStackTrace(System.err);
245 messager.error(Messager.NOPOS, "main.fatal.exception");
246 failed = true;
247 } finally {
248 if (fileManager != null
249 && fileManager instanceof BaseFileManager
250 && ((BaseFileManager) fileManager).autoClose) {
251 try {
252 fileManager.close();
253 } catch (IOException ignore) {
254 }
255 }
256 messager.exitNotice();
257 messager.flush();
258 }
259 failed |= messager.nerrors() > 0;
260 failed |= rejectWarnings && messager.nwarnings() > 0;
261 return !failed;
262 }
263
264 /**
265 * Main program - internal
266 */
267 private boolean parseAndExecute(
268 Class<?> docletClass,
269 String[] argv,
270 Iterable<? extends JavaFileObject> fileObjects) throws IOException {
271 long tm = System.currentTimeMillis();
272
273 ListBuffer<String> javaNames = new ListBuffer<>();
274
275 // Preprocess @file arguments
276 try {
277 argv = CommandLine.parse(argv);
278 } catch (FileNotFoundException e) {
279 messager.error(Messager.NOPOS, "main.cant.read", e.getMessage());
280 exit();
281 } catch (IOException e) {
282 e.printStackTrace(System.err);
283 exit();
284 }
285
286
287 fileManager = context.get(JavaFileManager.class);
288
289 setDocletInvoker(docletClass, fileManager, argv);
290
291 compOpts = Options.instance(context);
292 // Make sure no obsolete source/target messages are reported
293 compOpts.put("-Xlint:-options", "-Xlint:-options");
294
295 // Parse arguments
296 for (int i = 0 ; i < argv.length ; i++) {
297 String arg = argv[i];
298
299 ToolOption o = ToolOption.get(arg);
300 if (o != null) {
301 // hack: this restriction should be removed
302 if (o == ToolOption.LOCALE && i > 0)
303 usageError("main.locale_first");
304
305 if (o.hasArg) {
306 oneArg(argv, i++);
307 o.process(this, argv[i]);
308 } else {
309 setOption(arg);
310 o.process(this);
311 }
312
313 } else if (arg.startsWith("-XD")) {
314 // hidden javac options
315 String s = arg.substring("-XD".length());
316 int eq = s.indexOf('=');
317 String key = (eq < 0) ? s : s.substring(0, eq);
318 String value = (eq < 0) ? s : s.substring(eq+1);
319 compOpts.put(key, value);
320 }
321 // call doclet for its options
322 // other arg starts with - is invalid
323 else if (arg.startsWith("-")) {
324 int optionLength;
325 optionLength = docletInvoker.optionLength(arg);
326 if (optionLength < 0) {
327 // error already displayed
328 exit();
329 } else if (optionLength == 0) {
330 // option not found
331 usageError("main.invalid_flag", arg);
332 } else {
333 // doclet added option
334 if ((i + optionLength) > argv.length) {
335 usageError("main.requires_argument", arg);
336 }
337 ListBuffer<String> args = new ListBuffer<>();
338 for (int j = 0; j < optionLength-1; ++j) {
339 args.append(argv[++i]);
340 }
341 setOption(arg, args.toList());
342 }
343 } else {
344 javaNames.append(arg);
345 }
346 }
347
348 if (fileManager == null) {
349 JavacFileManager.preRegister(context);
350 fileManager = context.get(JavaFileManager.class);
351 if (fileManager instanceof BaseFileManager) {
352 ((BaseFileManager) fileManager).autoClose = true;
353 }
354 }
355 if (fileManager instanceof BaseFileManager) {
356 ((BaseFileManager) fileManager).handleOptions(fileManagerOpts);
357 }
358
359 String platformString = compOpts.get("-release");
360
361 if (platformString != null) {
362 if (compOpts.isSet("-source")) {
363 usageError("main.release.bootclasspath.conflict", "-source");
364 }
365 if (fileManagerOpts.containsKey(Option.BOOTCLASSPATH)) {
366 usageError("main.release.bootclasspath.conflict", Option.BOOTCLASSPATH.getText());
367 }
368
369 PlatformDescription platformDescription =
370 PlatformUtils.lookupPlatformDescription(platformString);
371
372 if (platformDescription == null) {
373 usageError("main.unsupported.release.version", platformString);
374 }
375
376 compOpts.put(Option.SOURCE, platformDescription.getSourceVersion());
377
378 context.put(PlatformDescription.class, platformDescription);
379
380 Collection<Path> platformCP = platformDescription.getPlatformPath();
381
382 if (platformCP != null) {
383 if (fileManager instanceof StandardJavaFileManager) {
384 StandardJavaFileManager sfm = (StandardJavaFileManager) fileManager;
385
386 sfm.setLocationFromPaths(StandardLocation.PLATFORM_CLASS_PATH, platformCP);
387 } else {
388 usageError("main.release.not.standard.file.manager", platformString);
389 }
390 }
391 }
392
393 compOpts.notifyListeners();
394
395 if (javaNames.isEmpty() && subPackages.isEmpty() && isEmpty(fileObjects)) {
396 usageError("main.No_packages_or_classes_specified");
397 }
398
399 if (!docletInvoker.validOptions(options.toList())) {
400 // error message already displayed
401 exit();
402 }
403
404 JavadocTool comp = JavadocTool.make0(context);
405 if (comp == null) return false;
406
407 if (showAccess == null) {
408 setFilter(defaultFilter);
409 }
410
411 LanguageVersion languageVersion = docletInvoker.languageVersion();
412 RootDocImpl root = comp.getRootDocImpl(
413 docLocale,
414 encoding,
415 showAccess,
416 javaNames.toList(),
417 options.toList(),
418 fileObjects,
419 breakiterator,
420 subPackages.toList(),
421 excludedPackages.toList(),
422 docClasses,
423 // legacy?
424 languageVersion == null || languageVersion == LanguageVersion.JAVA_1_1,
425 quiet);
426
427 // release resources
428 comp = null;
429
430 // pass off control to the doclet
431 boolean ok = root != null;
432 if (ok) ok = docletInvoker.start(root);
433
434 // We're done.
435 if (compOpts.get("-verbose") != null) {
436 tm = System.currentTimeMillis() - tm;
437 messager.notice("main.done_in", Long.toString(tm));
438 }
439
440 return ok;
441 }
442
443 private <T> boolean isEmpty(Iterable<T> iter) {
444 return !iter.iterator().hasNext();
445 }
446
447 /**
448 * Init the doclet invoker.
449 * The doclet class may be given explicitly, or via the -doclet option in
450 * argv.
451 * If the doclet class is not given explicitly, it will be loaded from
452 * the file manager's DOCLET_PATH location, if available, or via the
453 * -doclet path option in argv.
454 * @param docletClass The doclet class. May be null.
455 * @param fileManager The file manager used to get the class loader to load
456 * the doclet class if required. May be null.
457 * @param argv Args containing -doclet and -docletpath, in case they are required.
458 */
459 private void setDocletInvoker(Class<?> docletClass, JavaFileManager fileManager, String[] argv) {
460 if (docletClass != null) {
461 docletInvoker = new DocletInvoker(messager, docletClass, apiMode);
462 // TODO, check no -doclet, -docletpath
463 return;
464 }
465
466 String docletClassName = null;
467 String docletPath = null;
468
469 // Parse doclet specifying arguments
470 for (int i = 0 ; i < argv.length ; i++) {
471 String arg = argv[i];
472 if (arg.equals(ToolOption.DOCLET.opt)) {
473 oneArg(argv, i++);
474 if (docletClassName != null) {
475 usageError("main.more_than_one_doclet_specified_0_and_1",
476 docletClassName, argv[i]);
477 }
478 docletClassName = argv[i];
479 } else if (arg.equals(ToolOption.DOCLETPATH.opt)) {
480 oneArg(argv, i++);
481 if (docletPath == null) {
482 docletPath = argv[i];
483 } else {
484 docletPath += File.pathSeparator + argv[i];
485 }
486 }
487 }
488
489 if (docletClassName == null) {
490 docletClassName = defaultDocletClassName;
491 }
492
493 // attempt to find doclet
494 docletInvoker = new DocletInvoker(messager, fileManager,
495 docletClassName, docletPath,
496 docletParentClassLoader,
497 apiMode);
498 }
499
500 /**
501 * Set one arg option.
502 * Error and exit if one argument is not provided.
503 */
504 private void oneArg(String[] args, int index) {
505 if ((index + 1) < args.length) {
506 setOption(args[index], args[index+1]);
507 } else {
508 usageError("main.requires_argument", args[index]);
509 }
510 }
511
512 @Override
513 void usageError(String key, Object... args) {
514 messager.error(Messager.NOPOS, key, args);
515 usage(true);
516 }
517
518 /**
519 * indicate an option with no arguments was given.
520 */
521 private void setOption(String opt) {
522 String[] option = { opt };
523 options.append(option);
524 }
525
526 /**
527 * indicate an option with one argument was given.
528 */
529 private void setOption(String opt, String argument) {
530 String[] option = { opt, argument };
531 options.append(option);
532 }
533
534 /**
535 * indicate an option with the specified list of arguments was given.
536 */
537 private void setOption(String opt, List<String> arguments) {
538 String[] args = new String[arguments.length() + 1];
539 int k = 0;
540 args[k++] = opt;
541 for (List<String> i = arguments; i.nonEmpty(); i=i.tail) {
542 args[k++] = i.head;
543 }
544 options.append(args);
545 }
546 }