View Javadoc
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   */
25  
26  package com.sun.tools.doclets.formats.html;
27  
28  import java.net.*;
29  import java.util.*;
30  
31  import javax.tools.JavaFileManager;
32  
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;
41  
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 {
66  
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");
72  
73      /**
74       * Argument for command line option "-header".
75       */
76      public String header = "";
77  
78      /**
79       * Argument for command line option "-packagesheader".
80       */
81      public String packagesheader = "";
82  
83      /**
84       * Argument for command line option "-footer".
85       */
86      public String footer = "";
87  
88      /**
89       * Argument for command line option "-doctitle".
90       */
91      public String doctitle = "";
92  
93      /**
94       * Argument for command line option "-windowtitle".
95       */
96      public String windowtitle = "";
97  
98      /**
99       * Argument for command line option "-top".
100      */
101     public String top = "";
102 
103     /**
104      * Argument for command line option "-bottom".
105      */
106     public String bottom = "";
107 
108     /**
109      * Argument for command line option "-helpfile".
110      */
111     public String helpfile = "";
112 
113     /**
114      * Argument for command line option "-stylesheetfile".
115      */
116     public String stylesheetfile = "";
117 
118     /**
119      * Argument for command line option "-Xdocrootparent".
120      */
121     public String docrootparent = "";
122 
123     /**
124      * True if command line option "-nohelp" is used. Default value is false.
125      */
126     public boolean nohelp = false;
127 
128     /**
129      * True if command line option "-splitindex" is used. Default value is
130      * false.
131      */
132     public boolean splitindex = false;
133 
134     /**
135      * False if command line option "-noindex" is used. Default value is true.
136      */
137     public boolean createindex = true;
138 
139     /**
140      * True if command line option "-use" is used. Default value is false.
141      */
142     public boolean classuse = false;
143 
144     /**
145      * False if command line option "-notree" is used. Default value is true.
146      */
147     public boolean createtree = true;
148 
149     /**
150      * True if command line option "-nodeprecated" is used. Default value is
151      * false.
152      */
153     public boolean nodeprecatedlist = false;
154 
155     /**
156      * True if command line option "-nonavbar" is used. Default value is false.
157      */
158     public boolean nonavbar = false;
159 
160     /**
161      * True if command line option "-nooverview" is used. Default value is
162      * false
163      */
164     private boolean nooverview = false;
165 
166     /**
167      * True if command line option "-overview" is used. Default value is false.
168      */
169     public boolean overview = false;
170 
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;
176 
177     /**
178      * Collected set of doclint options
179      */
180     public Set<String> doclintOpts = new LinkedHashSet<String>();
181 
182     /**
183      * Unique Resource Handler for this package.
184      */
185     public final MessageRetriever standardmessage;
186 
187     /**
188      * First file to appear in the right-hand frame in the generated
189      * documentation.
190      */
191     public DocPath topFile = DocPath.empty;
192 
193     /**
194      * The classdoc for the class file getting generated.
195      */
196     public ClassDoc currentcd = null;  // Set this classdoc in the ClassWriter.
197 
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     }
206 
207     private final String versionRBName = "com.sun.tools.javadoc.resources.version";
208     private ResourceBundle versionRB;
209 
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         }
222 
223         try {
224             return versionRB.getString("release");
225         } catch (MissingResourceException e) {
226             return BUILD_DATE;
227         }
228     }
229 
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);
300 
301         if (root instanceof RootDocImpl) {
302             ((RootDocImpl) root).initDocLint(doclintOpts, tagletManager.getCustomTagNames());
303         }
304     }
305 
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     }
372 
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     }
471 
472     /**
473      * {@inheritDoc}
474      */
475     @Override
476     public MessageRetriever getDocletSpecificMsg() {
477         return standardmessage;
478     }
479 
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     }
509 
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     }
521 
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     }
531 
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     }
541 
542     /**
543      * {@inheritDoc}
544      */
545     @Override
546     public WriterFactory getWriterFactory() {
547         return new WriterFactoryImpl(this);
548     }
549 
550     /**
551      * {@inheritDoc}
552      */
553     @Override
554     public Comparator<ProgramElementDoc> getMemberComparator() {
555         return null;
556     }
557 
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     }
568 
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     }
582 
583     private JavaFileManager fileManager;
584 
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     }
592 
593     @Override
594     public Content newContent() {
595         return new ContentBuilder();
596     }
597 }