Tue, 24 Dec 2013 09:17:37 -0800
8029230: Update copyright year to match last edit in jdk8 langtools repository for 2013
Reviewed-by: ksrini
Contributed-by: steve.sides@oracle.com
1 /*
2 * Copyright (c) 1998, 2013, 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 */
26 package com.sun.tools.doclets.formats.html;
28 import java.net.*;
29 import java.util.*;
31 import javax.tools.JavaFileManager;
33 import com.sun.javadoc.*;
34 import com.sun.tools.doclets.formats.html.markup.ContentBuilder;
35 import com.sun.tools.doclets.internal.toolkit.*;
36 import com.sun.tools.doclets.internal.toolkit.util.*;
37 import com.sun.tools.doclint.DocLint;
38 import com.sun.tools.javac.file.JavacFileManager;
39 import com.sun.tools.javac.util.Context;
40 import com.sun.tools.javadoc.RootDocImpl;
42 /**
43 * Configure the output based on the command line options.
44 * <p>
45 * Also determine the length of the command line option. For example,
46 * for a option "-header" there will be a string argument associated, then the
47 * the length of option "-header" is two. But for option "-nohelp" no argument
48 * is needed so it's length is 1.
49 * </p>
50 * <p>
51 * Also do the error checking on the options used. For example it is illegal to
52 * use "-helpfile" option when already "-nohelp" option is used.
53 * </p>
54 *
55 * <p><b>This is NOT part of any supported API.
56 * If you write code that depends on this, you do so at your own risk.
57 * This code and its internal interfaces are subject to change or
58 * deletion without notice.</b>
59 *
60 * @author Robert Field.
61 * @author Atul Dambalkar.
62 * @author Jamie Ho
63 * @author Bhavesh Patel (Modified)
64 */
65 public class ConfigurationImpl extends Configuration {
67 /**
68 * The build date. Note: For now, we will use
69 * a version number instead of a date.
70 */
71 public static final String BUILD_DATE = System.getProperty("java.version");
73 /**
74 * Argument for command line option "-header".
75 */
76 public String header = "";
78 /**
79 * Argument for command line option "-packagesheader".
80 */
81 public String packagesheader = "";
83 /**
84 * Argument for command line option "-footer".
85 */
86 public String footer = "";
88 /**
89 * Argument for command line option "-doctitle".
90 */
91 public String doctitle = "";
93 /**
94 * Argument for command line option "-windowtitle".
95 */
96 public String windowtitle = "";
98 /**
99 * Argument for command line option "-top".
100 */
101 public String top = "";
103 /**
104 * Argument for command line option "-bottom".
105 */
106 public String bottom = "";
108 /**
109 * Argument for command line option "-helpfile".
110 */
111 public String helpfile = "";
113 /**
114 * Argument for command line option "-stylesheetfile".
115 */
116 public String stylesheetfile = "";
118 /**
119 * Argument for command line option "-Xdocrootparent".
120 */
121 public String docrootparent = "";
123 /**
124 * True if command line option "-nohelp" is used. Default value is false.
125 */
126 public boolean nohelp = false;
128 /**
129 * True if command line option "-splitindex" is used. Default value is
130 * false.
131 */
132 public boolean splitindex = false;
134 /**
135 * False if command line option "-noindex" is used. Default value is true.
136 */
137 public boolean createindex = true;
139 /**
140 * True if command line option "-use" is used. Default value is false.
141 */
142 public boolean classuse = false;
144 /**
145 * False if command line option "-notree" is used. Default value is true.
146 */
147 public boolean createtree = true;
149 /**
150 * True if command line option "-nodeprecated" is used. Default value is
151 * false.
152 */
153 public boolean nodeprecatedlist = false;
155 /**
156 * True if command line option "-nonavbar" is used. Default value is false.
157 */
158 public boolean nonavbar = false;
160 /**
161 * True if command line option "-nooverview" is used. Default value is
162 * false
163 */
164 private boolean nooverview = false;
166 /**
167 * True if command line option "-overview" is used. Default value is false.
168 */
169 public boolean overview = false;
171 /**
172 * This is true if option "-overview" is used or option "-overview" is not
173 * used and number of packages is more than one.
174 */
175 public boolean createoverview = false;
177 /**
178 * Collected set of doclint options
179 */
180 public Set<String> doclintOpts = new LinkedHashSet<String>();
182 /**
183 * Unique Resource Handler for this package.
184 */
185 public final MessageRetriever standardmessage;
187 /**
188 * First file to appear in the right-hand frame in the generated
189 * documentation.
190 */
191 public DocPath topFile = DocPath.empty;
193 /**
194 * The classdoc for the class file getting generated.
195 */
196 public ClassDoc currentcd = null; // Set this classdoc in the ClassWriter.
198 /**
199 * Constructor. Initializes resource for the
200 * {@link com.sun.tools.doclets.internal.toolkit.util.MessageRetriever MessageRetriever}.
201 */
202 public ConfigurationImpl() {
203 standardmessage = new MessageRetriever(this,
204 "com.sun.tools.doclets.formats.html.resources.standard");
205 }
207 private final String versionRBName = "com.sun.tools.javadoc.resources.version";
208 private ResourceBundle versionRB;
210 /**
211 * Return the build date for the doclet.
212 */
213 @Override
214 public String getDocletSpecificBuildDate() {
215 if (versionRB == null) {
216 try {
217 versionRB = ResourceBundle.getBundle(versionRBName);
218 } catch (MissingResourceException e) {
219 return BUILD_DATE;
220 }
221 }
223 try {
224 return versionRB.getString("release");
225 } catch (MissingResourceException e) {
226 return BUILD_DATE;
227 }
228 }
230 /**
231 * Depending upon the command line options provided by the user, set
232 * configure the output generation environment.
233 *
234 * @param options The array of option names and values.
235 */
236 @Override
237 public void setSpecificDocletOptions(String[][] options) {
238 for (int oi = 0; oi < options.length; ++oi) {
239 String[] os = options[oi];
240 String opt = os[0].toLowerCase();
241 if (opt.equals("-footer")) {
242 footer = os[1];
243 } else if (opt.equals("-header")) {
244 header = os[1];
245 } else if (opt.equals("-packagesheader")) {
246 packagesheader = os[1];
247 } else if (opt.equals("-doctitle")) {
248 doctitle = os[1];
249 } else if (opt.equals("-windowtitle")) {
250 windowtitle = os[1];
251 } else if (opt.equals("-top")) {
252 top = os[1];
253 } else if (opt.equals("-bottom")) {
254 bottom = os[1];
255 } else if (opt.equals("-helpfile")) {
256 helpfile = os[1];
257 } else if (opt.equals("-stylesheetfile")) {
258 stylesheetfile = os[1];
259 } else if (opt.equals("-charset")) {
260 charset = os[1];
261 } else if (opt.equals("-xdocrootparent")) {
262 docrootparent = os[1];
263 } else if (opt.equals("-nohelp")) {
264 nohelp = true;
265 } else if (opt.equals("-splitindex")) {
266 splitindex = true;
267 } else if (opt.equals("-noindex")) {
268 createindex = false;
269 } else if (opt.equals("-use")) {
270 classuse = true;
271 } else if (opt.equals("-notree")) {
272 createtree = false;
273 } else if (opt.equals("-nodeprecatedlist")) {
274 nodeprecatedlist = true;
275 } else if (opt.equals("-nonavbar")) {
276 nonavbar = true;
277 } else if (opt.equals("-nooverview")) {
278 nooverview = true;
279 } else if (opt.equals("-overview")) {
280 overview = true;
281 } else if (opt.equals("-xdoclint")) {
282 doclintOpts.add(null);
283 } else if (opt.startsWith("-xdoclint:")) {
284 doclintOpts.add(opt.substring(opt.indexOf(":") + 1));
285 }
286 }
287 if (root.specifiedClasses().length > 0) {
288 Map<String,PackageDoc> map = new HashMap<String,PackageDoc>();
289 PackageDoc pd;
290 ClassDoc[] classes = root.classes();
291 for (int i = 0; i < classes.length; i++) {
292 pd = classes[i].containingPackage();
293 if(! map.containsKey(pd.name())) {
294 map.put(pd.name(), pd);
295 }
296 }
297 }
298 setCreateOverview();
299 setTopFile(root);
301 if (root instanceof RootDocImpl) {
302 ((RootDocImpl) root).initDocLint(doclintOpts, tagletManager.getCustomTagNames());
303 }
304 }
306 /**
307 * Returns the "length" of a given option. If an option takes no
308 * arguments, its length is one. If it takes one argument, it's
309 * length is two, and so on. This method is called by JavaDoc to
310 * parse the options it does not recognize. It then calls
311 * {@link #validOptions(String[][], DocErrorReporter)} to
312 * validate them.
313 * <b>Note:</b><br>
314 * The options arrive as case-sensitive strings. For options that
315 * are not case-sensitive, use toLowerCase() on the option string
316 * before comparing it.
317 * </blockquote>
318 *
319 * @return number of arguments + 1 for a option. Zero return means
320 * option not known. Negative value means error occurred.
321 */
322 public int optionLength(String option) {
323 int result = -1;
324 if ((result = super.optionLength(option)) > 0) {
325 return result;
326 }
327 // otherwise look for the options we have added
328 option = option.toLowerCase();
329 if (option.equals("-nodeprecatedlist") ||
330 option.equals("-noindex") ||
331 option.equals("-notree") ||
332 option.equals("-nohelp") ||
333 option.equals("-splitindex") ||
334 option.equals("-serialwarn") ||
335 option.equals("-use") ||
336 option.equals("-nonavbar") ||
337 option.equals("-nooverview") ||
338 option.equals("-xdoclint") ||
339 option.startsWith("-xdoclint:")) {
340 return 1;
341 } else if (option.equals("-help")) {
342 // Uugh: first, this should not be hidden inside optionLength,
343 // and second, we should not be writing directly to stdout.
344 // But we have no access to a DocErrorReporter, which would
345 // allow use of reporter.printNotice
346 System.out.println(getText("doclet.usage"));
347 return 1;
348 } else if (option.equals("-x")) {
349 // Uugh: first, this should not be hidden inside optionLength,
350 // and second, we should not be writing directly to stdout.
351 // But we have no access to a DocErrorReporter, which would
352 // allow use of reporter.printNotice
353 System.out.println(getText("doclet.X.usage"));
354 return 1;
355 } else if (option.equals("-footer") ||
356 option.equals("-header") ||
357 option.equals("-packagesheader") ||
358 option.equals("-doctitle") ||
359 option.equals("-windowtitle") ||
360 option.equals("-top") ||
361 option.equals("-bottom") ||
362 option.equals("-helpfile") ||
363 option.equals("-stylesheetfile") ||
364 option.equals("-charset") ||
365 option.equals("-overview") ||
366 option.equals("-xdocrootparent")) {
367 return 2;
368 } else {
369 return 0;
370 }
371 }
373 /**
374 * {@inheritDoc}
375 */
376 @Override
377 public boolean validOptions(String options[][],
378 DocErrorReporter reporter) {
379 boolean helpfile = false;
380 boolean nohelp = false;
381 boolean overview = false;
382 boolean nooverview = false;
383 boolean splitindex = false;
384 boolean noindex = false;
385 // check shared options
386 if (!generalValidOptions(options, reporter)) {
387 return false;
388 }
389 // otherwise look at our options
390 for (int oi = 0; oi < options.length; ++oi) {
391 String[] os = options[oi];
392 String opt = os[0].toLowerCase();
393 if (opt.equals("-helpfile")) {
394 if (nohelp == true) {
395 reporter.printError(getText("doclet.Option_conflict",
396 "-helpfile", "-nohelp"));
397 return false;
398 }
399 if (helpfile == true) {
400 reporter.printError(getText("doclet.Option_reuse",
401 "-helpfile"));
402 return false;
403 }
404 DocFile help = DocFile.createFileForInput(this, os[1]);
405 if (!help.exists()) {
406 reporter.printError(getText("doclet.File_not_found", os[1]));
407 return false;
408 }
409 helpfile = true;
410 } else if (opt.equals("-nohelp")) {
411 if (helpfile == true) {
412 reporter.printError(getText("doclet.Option_conflict",
413 "-nohelp", "-helpfile"));
414 return false;
415 }
416 nohelp = true;
417 } else if (opt.equals("-xdocrootparent")) {
418 try {
419 new URL(os[1]);
420 } catch (MalformedURLException e) {
421 reporter.printError(getText("doclet.MalformedURL", os[1]));
422 return false;
423 }
424 } else if (opt.equals("-overview")) {
425 if (nooverview == true) {
426 reporter.printError(getText("doclet.Option_conflict",
427 "-overview", "-nooverview"));
428 return false;
429 }
430 if (overview == true) {
431 reporter.printError(getText("doclet.Option_reuse",
432 "-overview"));
433 return false;
434 }
435 overview = true;
436 } else if (opt.equals("-nooverview")) {
437 if (overview == true) {
438 reporter.printError(getText("doclet.Option_conflict",
439 "-nooverview", "-overview"));
440 return false;
441 }
442 nooverview = true;
443 } else if (opt.equals("-splitindex")) {
444 if (noindex == true) {
445 reporter.printError(getText("doclet.Option_conflict",
446 "-splitindex", "-noindex"));
447 return false;
448 }
449 splitindex = true;
450 } else if (opt.equals("-noindex")) {
451 if (splitindex == true) {
452 reporter.printError(getText("doclet.Option_conflict",
453 "-noindex", "-splitindex"));
454 return false;
455 }
456 noindex = true;
457 } else if (opt.startsWith("-xdoclint:")) {
458 if (opt.contains("/")) {
459 reporter.printError(getText("doclet.Option_doclint_no_qualifiers"));
460 return false;
461 }
462 if (!DocLint.isValidOption(
463 opt.replace("-xdoclint:", DocLint.XMSGS_CUSTOM_PREFIX))) {
464 reporter.printError(getText("doclet.Option_doclint_invalid_arg"));
465 return false;
466 }
467 }
468 }
469 return true;
470 }
472 /**
473 * {@inheritDoc}
474 */
475 @Override
476 public MessageRetriever getDocletSpecificMsg() {
477 return standardmessage;
478 }
480 /**
481 * Decide the page which will appear first in the right-hand frame. It will
482 * be "overview-summary.html" if "-overview" option is used or no
483 * "-overview" but the number of packages is more than one. It will be
484 * "package-summary.html" of the respective package if there is only one
485 * package to document. It will be a class page(first in the sorted order),
486 * if only classes are provided on the command line.
487 *
488 * @param root Root of the program structure.
489 */
490 protected void setTopFile(RootDoc root) {
491 if (!checkForDeprecation(root)) {
492 return;
493 }
494 if (createoverview) {
495 topFile = DocPaths.OVERVIEW_SUMMARY;
496 } else {
497 if (packages.length == 1 && packages[0].name().equals("")) {
498 if (root.classes().length > 0) {
499 ClassDoc[] classarr = root.classes();
500 Arrays.sort(classarr);
501 ClassDoc cd = getValidClass(classarr);
502 topFile = DocPath.forClass(cd);
503 }
504 } else {
505 topFile = DocPath.forPackage(packages[0]).resolve(DocPaths.PACKAGE_SUMMARY);
506 }
507 }
508 }
510 protected ClassDoc getValidClass(ClassDoc[] classarr) {
511 if (!nodeprecated) {
512 return classarr[0];
513 }
514 for (int i = 0; i < classarr.length; i++) {
515 if (classarr[i].tags("deprecated").length == 0) {
516 return classarr[i];
517 }
518 }
519 return null;
520 }
522 protected boolean checkForDeprecation(RootDoc root) {
523 ClassDoc[] classarr = root.classes();
524 for (int i = 0; i < classarr.length; i++) {
525 if (isGeneratedDoc(classarr[i])) {
526 return true;
527 }
528 }
529 return false;
530 }
532 /**
533 * Generate "overview.html" page if option "-overview" is used or number of
534 * packages is more than one. Sets {@link #createoverview} field to true.
535 */
536 protected void setCreateOverview() {
537 if ((overview || packages.length > 1) && !nooverview) {
538 createoverview = true;
539 }
540 }
542 /**
543 * {@inheritDoc}
544 */
545 @Override
546 public WriterFactory getWriterFactory() {
547 return new WriterFactoryImpl(this);
548 }
550 /**
551 * {@inheritDoc}
552 */
553 @Override
554 public Comparator<ProgramElementDoc> getMemberComparator() {
555 return null;
556 }
558 /**
559 * {@inheritDoc}
560 */
561 @Override
562 public Locale getLocale() {
563 if (root instanceof RootDocImpl)
564 return ((RootDocImpl)root).getLocale();
565 else
566 return Locale.getDefault();
567 }
569 /**
570 * {@inheritDoc}
571 */
572 @Override
573 public JavaFileManager getFileManager() {
574 if (fileManager == null) {
575 if (root instanceof RootDocImpl)
576 fileManager = ((RootDocImpl) root).getFileManager();
577 else
578 fileManager = new JavacFileManager(new Context(), false, null);
579 }
580 return fileManager;
581 }
583 private JavaFileManager fileManager;
585 @Override
586 public boolean showMessage(SourcePosition pos, String key) {
587 if (root instanceof RootDocImpl) {
588 return pos == null || ((RootDocImpl) root).showTagMessages();
589 }
590 return true;
591 }
593 @Override
594 public Content newContent() {
595 return new ContentBuilder();
596 }
597 }