1 /*

     2  * Copyright (c) 1997, 2017, 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 jdk.javadoc.internal.doclets.toolkit;

    27 

    28 import java.io.*;

    29 import java.lang.ref.*;

    30 import java.util.*;

    31 

    32 import javax.lang.model.element.Element;

    33 import javax.lang.model.element.ModuleElement;

    34 import javax.lang.model.element.PackageElement;

    35 import javax.lang.model.element.TypeElement;

    36 import javax.lang.model.util.SimpleElementVisitor9;

    37 import javax.tools.JavaFileManager;

    38 import javax.tools.JavaFileObject;

    39 

    40 import com.sun.source.util.DocTreePath;

    41 import com.sun.tools.javac.util.DefinedBy;

    42 import com.sun.tools.javac.util.DefinedBy.Api;

    43 import jdk.javadoc.doclet.Doclet;

    44 import jdk.javadoc.doclet.DocletEnvironment;

    45 import jdk.javadoc.doclet.Reporter;

    46 import jdk.javadoc.internal.doclets.toolkit.builders.BuilderFactory;

    47 import jdk.javadoc.internal.doclets.toolkit.taglets.TagletManager;

    48 import jdk.javadoc.internal.doclets.toolkit.util.DocFile;

    49 import jdk.javadoc.internal.doclets.toolkit.util.DocFileFactory;

    50 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;

    51 import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants;

    52 import jdk.javadoc.internal.doclets.toolkit.util.Extern;

    53 import jdk.javadoc.internal.doclets.toolkit.util.Group;

    54 import jdk.javadoc.internal.doclets.toolkit.util.MetaKeywords;

    55 import jdk.javadoc.internal.doclets.toolkit.util.SimpleDocletException;

    56 import jdk.javadoc.internal.doclets.toolkit.util.TypeElementCatalog;

    57 import jdk.javadoc.internal.doclets.toolkit.util.Utils;

    58 import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap;

    59 import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap.GetterSetter;

    60 import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap.Kind;

    61 

    62 import static javax.tools.Diagnostic.Kind.*;

    63 

    64 /**

    65  * Configure the output based on the options. Doclets should sub-class

    66  * Configuration, to configure and add their own options. This class contains

    67  * all user options which are supported by the 1.1 doclet and the standard

    68  * doclet.

    69  *

    70  *  <p><b>This is NOT part of any supported API.

    71  *  If you write code that depends on this, you do so at your own risk.

    72  *  This code and its internal interfaces are subject to change or

    73  *  deletion without notice.</b>

    74  *

    75  * @author Robert Field.

    76  * @author Atul Dambalkar.

    77  * @author Jamie Ho

    78  */

    79 public abstract class Configuration {

    80     /**

    81      * The doclet that created this configuration.

    82      */

    83     public final Doclet doclet;

    84 

    85     /**

    86      * The factory for builders.

    87      */

    88     protected BuilderFactory builderFactory;

    89 

    90     /**

    91      * The taglet manager.

    92      */

    93     public TagletManager tagletManager;

    94 

    95     /**

    96      * The path to the builder XML input file.

    97      */

    98     public String builderXMLPath;

    99 

   100     /**

   101      * The default path to the builder XML.

   102      */

   103     public static final String DEFAULT_BUILDER_XML = "resources/doclet.xml";

   104 

   105     /**

   106      * The path to Taglets

   107      */

   108     public String tagletpath = null;

   109 

   110     /**

   111      * This is true if option "-serialwarn" is used. Defualt value is false to

   112      * suppress excessive warnings about serial tag.

   113      */

   114     public boolean serialwarn = false;

   115 

   116     /**

   117      * The specified amount of space between tab stops.

   118      */

   119     public int sourcetab;

   120 

   121     public String tabSpaces;

   122 

   123     /**

   124      * True if we should generate browsable sources.

   125      */

   126     public boolean linksource = false;

   127 

   128     /**

   129      * True if command line option "-nosince" is used. Default value is

   130      * false.

   131      */

   132     public boolean nosince = false;

   133 

   134     /**

   135      * True if we should recursively copy the doc-file subdirectories

   136      */

   137     public boolean copydocfilesubdirs = false;

   138 

   139     /**

   140      * Maintain backward compatibility with previous javadoc version

   141      */

   142     public boolean backwardCompatibility = true;

   143 

   144     /**

   145      * The META charset tag used for cross-platform viewing.

   146      */

   147     public String charset = "";

   148 

   149     /**

   150      * True if user wants to add member names as meta keywords.

   151      * Set to false because meta keywords are ignored in general

   152      * by most Internet search engines.

   153      */

   154     public boolean keywords = false;

   155 

   156     /**

   157      * The meta tag keywords instance.

   158      */

   159     public final MetaKeywords metakeywords;

   160 

   161     /**

   162      * The set of doc-file subdirectories to exclude

   163      */

   164     protected Set<String> excludedDocFileDirs;

   165 

   166     /**

   167      * The set of qualifiers to exclude

   168      */

   169     protected Set<String> excludedQualifiers;

   170 

   171     /**

   172      * The doclet environment.

   173      */

   174     public DocletEnvironment docEnv;

   175 

   176     /**

   177      * An utility class for commonly used helpers

   178      */

   179     public Utils utils;

   180 

   181     /**

   182      * All the temporary accessors to javac internals.

   183      */

   184     public WorkArounds workArounds;

   185 

   186     /**

   187      * Destination directory name, in which doclet will generate the entire

   188      * documentation. Default is current directory.

   189      */

   190     public String destDirName = "";

   191 

   192     /**

   193      * Destination directory name, in which doclet will copy the doc-files to.

   194      */

   195     public String docFileDestDirName = "";

   196 

   197     /**

   198      * Encoding for this document. Default is default encoding for this

   199      * platform.

   200      */

   201     public String docencoding = null;

   202 

   203     /**

   204      * True if user wants to suppress descriptions and tags.

   205      */

   206     public boolean nocomment = false;

   207 

   208     /**

   209      * Encoding for this document. Default is default encoding for this

   210      * platform.

   211      */

   212     public String encoding = null;

   213 

   214     /**

   215      * Generate author specific information for all the classes if @author

   216      * tag is used in the doc comment and if -author option is used.

   217      * <code>showauthor</code> is set to true if -author option is used.

   218      * Default is don't show author information.

   219      */

   220     public boolean showauthor = false;

   221 

   222     /**

   223      * Generate documentation for JavaFX getters and setters automatically

   224      * by copying it from the appropriate property definition.

   225      */

   226     public boolean javafx = false;

   227 

   228     /**

   229      * Generate version specific information for the all the classes

   230      * if @version tag is used in the doc comment and if -version option is

   231      * used. <code>showversion</code> is set to true if -version option is

   232      * used.Default is don't show version information.

   233      */

   234     public boolean showversion = false;

   235 

   236     /**

   237      * Allow JavaScript in doc comments.

   238      */

   239     private boolean allowScriptInComments = false;

   240 

   241     /**

   242      * Sourcepath from where to read the source files. Default is classpath.

   243      *

   244      */

   245     public String sourcepath = "";

   246 

   247     /**

   248      * Generate modules documentation if more than one module is present.

   249      */

   250     public boolean showModules = false;

   251 

   252     /**

   253      * Don't generate deprecated API information at all, if -nodeprecated

   254      * option is used. <code>nodepracted</code> is set to true if

   255      * -nodeprecated option is used. Default is generate deprected API

   256      * information.

   257      */

   258     public boolean nodeprecated = false;

   259 

   260     /**

   261      * The catalog of classes specified on the command-line

   262      */

   263     public TypeElementCatalog typeElementCatalog;

   264 

   265     /**

   266      * True if user wants to suppress time stamp in output.

   267      * Default is false.

   268      */

   269     public boolean notimestamp= false;

   270 

   271     /**

   272      * The package grouping instance.

   273      */

   274     public final Group group = new Group(this);

   275 

   276     /**

   277      * The tracker of external package links.

   278      */

   279     public final Extern extern = new Extern(this);

   280 

   281     public  Reporter reporter;

   282 

   283     public Locale locale;

   284 

   285     /**

   286      * Suppress all messages

   287      */

   288     public boolean quiet = false;

   289 

   290     private String urlForLink;

   291 

   292     private String pkglistUrlForLink;

   293 

   294     private String urlForLinkOffline;

   295 

   296     private String pkglistUrlForLinkOffline;

   297 

   298     public boolean dumpOnError = false;

   299 

   300     private List<GroupContainer> groups;

   301 

   302     private final Map<TypeElement, EnumMap<Kind, Reference<VisibleMemberMap>>> typeElementMemberCache;

   303 

   304     public abstract Messages getMessages();

   305     public abstract Resources getResources();

   306 

   307     /**

   308      * Return the build date for the doclet.

   309      *

   310      * @return the build date

   311      */

   312     public abstract String getDocletSpecificBuildDate();

   313 

   314     /**

   315      * This method should be defined in all those doclets (configurations),

   316      * which want to derive themselves from this Configuration. This method

   317      * can be used to finish up the options setup.

   318      *

   319      * @return true if successful and false otherwise

   320      */

   321 

   322     public abstract boolean finishOptionSettings();

   323 

   324     public CommentUtils cmtUtils;

   325 

   326     /**

   327      * A sorted set of included packages.

   328      */

   329     public SortedSet<PackageElement> packages = null;

   330 

   331     public OverviewElement overviewElement;

   332 

   333     // The following three fields provide caches for use by all instances of VisibleMemberMap.

   334     public final Map<TypeElement, List<Element>> propertiesCache = new HashMap<>();

   335     public final Map<Element, Element> classPropertiesMap = new HashMap<>();

   336     public final Map<Element, GetterSetter> getterSetterMap = new HashMap<>();

   337 

   338     public DocFileFactory docFileFactory;

   339 

   340     /**

   341      * A sorted map, giving the (specified|included|other) packages for each module.

   342      */

   343     public SortedMap<ModuleElement, Set<PackageElement>> modulePackages;

   344 

   345    /**

   346     * The list of known modules, that should be documented.

   347     */

   348     public SortedSet<ModuleElement> modules;

   349 

   350     protected static final String sharedResourceBundleName =

   351             "jdk.javadoc.internal.doclets.toolkit.resources.doclets";

   352     /**

   353      * Constructs the configurations needed by the doclet.

   354      * @param doclet the doclet that created this configuration

   355      */

   356     public Configuration(Doclet doclet) {

   357         this.doclet = doclet;

   358         excludedDocFileDirs = new HashSet<>();

   359         excludedQualifiers = new HashSet<>();

   360         setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);

   361         metakeywords = new MetaKeywords(this);

   362         groups = new ArrayList<>(0);

   363         typeElementMemberCache = new HashMap<>();

   364     }

   365 

   366     private boolean initialized = false;

   367 

   368     protected void initConfiguration(DocletEnvironment docEnv) {

   369         if (initialized) {

   370             throw new IllegalStateException("configuration previously initialized");

   371         }

   372         initialized = true;

   373         this.docEnv = docEnv;

   374         overviewElement = new OverviewElement(docEnv);

   375         Splitter specifiedSplitter = new Splitter(docEnv, false);

   376         specifiedModuleElements = Collections.unmodifiableSet(specifiedSplitter.mset);

   377         specifiedPackageElements = Collections.unmodifiableSet(specifiedSplitter.pset);

   378         specifiedTypeElements = Collections.unmodifiableSet(specifiedSplitter.tset);

   379 

   380         Splitter includedSplitter = new Splitter(docEnv, true);

   381         includedModuleElements = Collections.unmodifiableSet(includedSplitter.mset);

   382         includedPackageElements = Collections.unmodifiableSet(includedSplitter.pset);

   383         includedTypeElements = Collections.unmodifiableSet(includedSplitter.tset);

   384     }

   385 

   386     /**

   387      * Return the builder factory for this doclet.

   388      *

   389      * @return the builder factory for this doclet.

   390      */

   391     public BuilderFactory getBuilderFactory() {

   392         if (builderFactory == null) {

   393             builderFactory = new BuilderFactory(this);

   394         }

   395         return builderFactory;

   396     }

   397 

   398     public Reporter getReporter() {

   399         return this.reporter;

   400     }

   401 

   402     private Set<ModuleElement> specifiedModuleElements;

   403     public Set<ModuleElement> getSpecifiedModuleElements() {

   404         return specifiedModuleElements;

   405     }

   406 

   407     private Set<PackageElement> specifiedPackageElements;

   408     public Set<PackageElement> getSpecifiedPackageElements() {

   409         return specifiedPackageElements;

   410     }

   411 

   412     private Set<TypeElement> specifiedTypeElements;

   413     public Set<TypeElement> getSpecifiedTypeElements() {

   414         return specifiedTypeElements;

   415     }

   416 

   417     private Set<ModuleElement> includedModuleElements;

   418     public Set<ModuleElement> getIncludedModuleElements() {

   419         return includedModuleElements;

   420     }

   421 

   422     private Set<PackageElement> includedPackageElements;

   423     public Set<PackageElement> getIncludedPackageElements() {

   424         return includedPackageElements;

   425     }

   426 

   427     private Set<TypeElement> includedTypeElements;

   428     public Set<TypeElement> getIncludedTypeElements() {

   429         return includedTypeElements;

   430     }

   431 

   432     private void initModules() {

   433         // Build the modules structure used by the doclet

   434         modules = new TreeSet<>(utils.makeModuleComparator());

   435         modules.addAll(getSpecifiedModuleElements());

   436 

   437         modulePackages = new TreeMap<>(utils.makeModuleComparator());

   438         for (PackageElement p: packages) {

   439             ModuleElement mdle = docEnv.getElementUtils().getModuleOf(p);

   440             if (mdle != null && !mdle.isUnnamed()) {

   441                 Set<PackageElement> s = modulePackages

   442                         .computeIfAbsent(mdle, m -> new TreeSet<>(utils.makePackageComparator()));

   443                 s.add(p);

   444             }

   445         }

   446 

   447         for (PackageElement p: getIncludedPackageElements()) {

   448             ModuleElement mdle = docEnv.getElementUtils().getModuleOf(p);

   449             if (mdle != null && !mdle.isUnnamed()) {

   450                 Set<PackageElement> s = modulePackages

   451                         .computeIfAbsent(mdle, m -> new TreeSet<>(utils.makePackageComparator()));

   452                 s.add(p);

   453             }

   454         }

   455 

   456         // add entries for modules which may not have exported packages

   457         modules.forEach((ModuleElement mdle) -> {

   458             modulePackages.computeIfAbsent(mdle, m -> Collections.emptySet());

   459         });

   460 

   461         modules.addAll(modulePackages.keySet());

   462         showModules = !modules.isEmpty();

   463         for (Set<PackageElement> pkgs : modulePackages.values()) {

   464             packages.addAll(pkgs);

   465         }

   466     }

   467 

   468     private void initPackages() {

   469         packages = new TreeSet<>(utils.makePackageComparator());

   470         // add all the included packages

   471         packages.addAll(includedPackageElements);

   472     }

   473 

   474     public Set<Doclet.Option> getSupportedOptions() {

   475         Resources resources = getResources();

   476         Doclet.Option[] options = {

   477             new Option(resources, "-author") {

   478                 @Override

   479                 public boolean process(String opt, List<String> args) {

   480                     showauthor = true;

   481                     return true;

   482                 }

   483             },

   484             new Option(resources, "-d", 1) {

   485                 @Override

   486                 public boolean process(String opt, List<String> args) {

   487                     destDirName = addTrailingFileSep(args.get(0));

   488                     return true;

   489                 }

   490             },

   491             new Option(resources, "-docencoding", 1) {

   492                 @Override

   493                 public boolean process(String opt, List<String> args) {

   494                     docencoding = args.get(0);

   495                     return true;

   496                 }

   497             },

   498             new Option(resources, "-docfilessubdirs") {

   499                 @Override

   500                 public boolean process(String opt, List<String> args) {

   501                     copydocfilesubdirs = true;

   502                     return true;

   503                 }

   504             },

   505             new Hidden(resources, "-encoding", 1) {

   506                 @Override

   507                 public boolean process(String opt, List<String> args) {

   508                     encoding = args.get(0);

   509                     return true;

   510                 }

   511             },

   512             new Option(resources, "-excludedocfilessubdir", 1) {

   513                 @Override

   514                 public boolean process(String opt, List<String> args) {

   515                     addToSet(excludedDocFileDirs, args.get(0));

   516                     return true;

   517                 }

   518             },

   519             new Option(resources, "-group", 2) {

   520                 @Override

   521                 public boolean process(String opt, List<String> args) {

   522                     groups.add(new GroupContainer(args.get(0), args.get(1)));

   523                     return true;

   524                 }

   525             },

   526             new Option(resources, "--javafx -javafx") {

   527                 @Override

   528                 public boolean process(String opt, List<String> args) {

   529                     javafx = true;

   530                     return true;

   531                 }

   532             },

   533             new Option(resources, "-keywords") {

   534                 @Override

   535                 public boolean process(String opt, List<String> args) {

   536                     keywords = true;

   537                     return true;

   538                 }

   539             },

   540             new Option(resources, "-link", 1) {

   541                 @Override

   542                 public boolean process(String opt, List<String> args) {

   543                     urlForLink = args.get(0);

   544                     pkglistUrlForLink = urlForLink;

   545                     return true;

   546                 }

   547             },

   548             new Option(resources, "-linksource") {

   549                 @Override

   550                 public boolean process(String opt, List<String> args) {

   551                     linksource = true;

   552                     return true;

   553                 }

   554             },

   555             new Option(resources, "-linkoffline", 2) {

   556                 @Override

   557                 public boolean process(String opt, List<String> args) {

   558                     urlForLinkOffline = args.get(0);

   559                     pkglistUrlForLinkOffline = args.get(1);

   560                     return true;

   561                 }

   562             },

   563             new Option(resources, "-nocomment") {

   564                 @Override

   565                 public boolean process(String opt, List<String> args) {

   566                     nocomment = true;

   567                     return true;

   568                 }

   569             },

   570             new Option(resources, "-nodeprecated") {

   571                 @Override

   572                 public boolean process(String opt, List<String> args) {

   573                     nodeprecated = true;

   574                     return true;

   575                 }

   576             },

   577             new Option(resources, "-nosince") {

   578                 @Override

   579                 public boolean process(String opt, List<String> args) {

   580                     nosince = true;

   581                     return true;

   582                 }

   583             },

   584             new Option(resources, "-notimestamp") {

   585                 @Override

   586                 public boolean process(String opt, List<String> args) {

   587                     notimestamp = true;

   588                     return true;

   589                 }

   590             },

   591             new Option(resources, "-noqualifier", 1) {

   592                 @Override

   593                 public boolean process(String opt, List<String> args) {

   594                     addToSet(excludedQualifiers, args.get(0));

   595                     return true;

   596                 }

   597             },

   598             new Hidden(resources, "-quiet") {

   599                 @Override

   600                 public boolean process(String opt, List<String> args) {

   601                     quiet = true;

   602                     return true;

   603                 }

   604             },

   605             new Option(resources, "-serialwarn") {

   606                 @Override

   607                 public boolean process(String opt, List<String> args) {

   608                     serialwarn = true;

   609                     return true;

   610                 }

   611             },

   612             new Option(resources, "-sourcetab", 1) {

   613                 @Override

   614                 public boolean process(String opt, List<String> args) {

   615                     linksource = true;

   616                     try {

   617                         setTabWidth(Integer.parseInt(args.get(0)));

   618                     } catch (NumberFormatException e) {

   619                              //Set to -1 so that warning will be printed

   620                         //to indicate what is valid argument.

   621                         sourcetab = -1;

   622                     }

   623                     if (sourcetab <= 0) {

   624                         getMessages().warning("doclet.sourcetab_warning");

   625                         setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);

   626                     }

   627                     return true;

   628                 }

   629             },

   630             new Option(resources, "-tag", 1) {

   631                 @Override

   632                 public boolean process(String opt, List<String> args) {

   633                     ArrayList<String> list = new ArrayList<>();

   634                     list.add(opt);

   635                     list.add(args.get(0));

   636                     customTagStrs.add(list);

   637                     return true;

   638                 }

   639             },

   640              new Option(resources, "-taglet", 1) {

   641                 @Override

   642                 public boolean process(String opt, List<String> args) {

   643                     ArrayList<String> list = new ArrayList<>();

   644                     list.add(opt);

   645                     list.add(args.get(0));

   646                     customTagStrs.add(list);

   647                     return true;

   648                 }

   649             },

   650             new Option(resources, "-tagletpath", 1) {

   651                 @Override

   652                 public boolean process(String opt, List<String> args) {

   653                     tagletpath = args.get(0);

   654                     return true;

   655                 }

   656             },

   657             new Option(resources, "-version") {

   658                 @Override

   659                 public boolean process(String opt, List<String> args) {

   660                     showversion = true;

   661                     return true;

   662                 }

   663             },

   664             new Hidden(resources, "--dump-on-error") {

   665                 @Override

   666                 public boolean process(String opt, List<String> args) {

   667                     dumpOnError = true;

   668                     return true;

   669                 }

   670             },

   671             new Option(resources, "--allow-script-in-comments") {

   672                 @Override

   673                 public boolean process(String opt, List<String> args) {

   674                     allowScriptInComments = true;

   675                     return true;

   676                 }

   677             }

   678         };

   679         Set<Doclet.Option> set = new TreeSet<>();

   680         set.addAll(Arrays.asList(options));

   681         return set;

   682     }

   683 

   684     final LinkedHashSet<List<String>> customTagStrs = new LinkedHashSet<>();

   685 

   686     /*

   687      * when this is called all the option have been set, this method,

   688      * initializes certain components before anything else is started.

   689      */

   690     private void finishOptionSettings0() throws DocletException {

   691         initDestDirectory();

   692         if (urlForLink != null && pkglistUrlForLink != null)

   693             extern.link(urlForLink, pkglistUrlForLink, reporter, false);

   694         if (urlForLinkOffline != null && pkglistUrlForLinkOffline != null)

   695             extern.link(urlForLinkOffline, pkglistUrlForLinkOffline, reporter, true);

   696         if (docencoding == null) {

   697             docencoding = encoding;

   698         }

   699         typeElementCatalog = new TypeElementCatalog(includedTypeElements, this);

   700         initTagletManager(customTagStrs);

   701         groups.stream().forEach((grp) -> {

   702             if (showModules) {

   703                 group.checkModuleGroups(grp.value1, grp.value2);

   704             } else {

   705                 group.checkPackageGroups(grp.value1, grp.value2);

   706             }

   707         });

   708     }

   709 

   710     /**

   711      * Set the command line options supported by this configuration.

   712      *

   713      * @return true if the options are set successfully

   714      * @throws DocletException if there is a problem while setting the options

   715      */

   716     public boolean setOptions() throws DocletException {

   717         initPackages();

   718         initModules();

   719         finishOptionSettings0();

   720         if (!finishOptionSettings())

   721             return false;

   722 

   723         return true;

   724     }

   725 

   726     private void initDestDirectory() throws DocletException {

   727         if (!destDirName.isEmpty()) {

   728             DocFile destDir = DocFile.createFileForDirectory(this, destDirName);

   729             if (!destDir.exists()) {

   730                 //Create the output directory (in case it doesn't exist yet)

   731                 reporter.print(NOTE, getText("doclet.dest_dir_create", destDirName));

   732                 destDir.mkdirs();

   733             } else if (!destDir.isDirectory()) {

   734                 throw new SimpleDocletException(getText(

   735                         "doclet.destination_directory_not_directory_0",

   736                         destDir.getPath()));

   737             } else if (!destDir.canWrite()) {

   738                 throw new SimpleDocletException(getText(

   739                         "doclet.destination_directory_not_writable_0",

   740                         destDir.getPath()));

   741             }

   742         }

   743         DocFileFactory.getFactory(this).setDestDir(destDirName);

   744     }

   745 

   746     /**

   747      * Initialize the taglet manager.  The strings to initialize the simple custom tags should

   748      * be in the following format:  "[tag name]:[location str]:[heading]".

   749      *

   750      * @param customTagStrs the set two dimensional arrays of strings.  These arrays contain

   751      * either -tag or -taglet arguments.

   752      */

   753     private void initTagletManager(Set<List<String>> customTagStrs) {

   754         tagletManager = tagletManager == null ?

   755             new TagletManager(nosince, showversion, showauthor, javafx, this) :

   756             tagletManager;

   757         for (List<String> args : customTagStrs) {

   758             if (args.get(0).equals("-taglet")) {

   759                 tagletManager.addCustomTag(args.get(1), getFileManager(), tagletpath);

   760                 continue;

   761             }

   762             List<String> tokens = tokenize(args.get(1), TagletManager.SIMPLE_TAGLET_OPT_SEPARATOR, 3);

   763             if (tokens.size() == 1) {

   764                 String tagName = args.get(1);

   765                 if (tagletManager.isKnownCustomTag(tagName)) {

   766                     //reorder a standard tag

   767                     tagletManager.addNewSimpleCustomTag(tagName, null, "");

   768                 } else {

   769                     //Create a simple tag with the heading that has the same name as the tag.

   770                     StringBuilder heading = new StringBuilder(tagName + ":");

   771                     heading.setCharAt(0, Character.toUpperCase(tagName.charAt(0)));

   772                     tagletManager.addNewSimpleCustomTag(tagName, heading.toString(), "a");

   773                 }

   774             } else if (tokens.size() == 2) {

   775                 //Add simple taglet without heading, probably to excluding it in the output.

   776                 tagletManager.addNewSimpleCustomTag(tokens.get(0), tokens.get(1), "");

   777             } else if (tokens.size() >= 3) {

   778                 tagletManager.addNewSimpleCustomTag(tokens.get(0), tokens.get(2), tokens.get(1));

   779             } else {

   780                 Messages messages = getMessages();

   781                 messages.error("doclet.Error_invalid_custom_tag_argument", args.get(1));

   782             }

   783         }

   784     }

   785 

   786     /**

   787      * Given a string, return an array of tokens.  The separator can be escaped

   788      * with the '\' character.  The '\' character may also be escaped by the

   789      * '\' character.

   790      *

   791      * @param s         the string to tokenize.

   792      * @param separator the separator char.

   793      * @param maxTokens the maximum number of tokens returned.  If the

   794      *                  max is reached, the remaining part of s is appended

   795      *                  to the end of the last token.

   796      *

   797      * @return an array of tokens.

   798      */

   799     private List<String> tokenize(String s, char separator, int maxTokens) {

   800         List<String> tokens = new ArrayList<>();

   801         StringBuilder  token = new StringBuilder ();

   802         boolean prevIsEscapeChar = false;

   803         for (int i = 0; i < s.length(); i += Character.charCount(i)) {

   804             int currentChar = s.codePointAt(i);

   805             if (prevIsEscapeChar) {

   806                 // Case 1:  escaped character

   807                 token.appendCodePoint(currentChar);

   808                 prevIsEscapeChar = false;

   809             } else if (currentChar == separator && tokens.size() < maxTokens-1) {

   810                 // Case 2:  separator

   811                 tokens.add(token.toString());

   812                 token = new StringBuilder();

   813             } else if (currentChar == '\\') {

   814                 // Case 3:  escape character

   815                 prevIsEscapeChar = true;

   816             } else {

   817                 // Case 4:  regular character

   818                 token.appendCodePoint(currentChar);

   819             }

   820         }

   821         if (token.length() > 0) {

   822             tokens.add(token.toString());

   823         }

   824         return tokens;

   825     }

   826 

   827     private void addToSet(Set<String> s, String str){

   828         StringTokenizer st = new StringTokenizer(str, ":");

   829         String current;

   830         while(st.hasMoreTokens()){

   831             current = st.nextToken();

   832             s.add(current);

   833         }

   834     }

   835 

   836     /**

   837      * Add a trailing file separator, if not found. Remove superfluous

   838      * file separators if any. Preserve the front double file separator for

   839      * UNC paths.

   840      *

   841      * @param path Path under consideration.

   842      * @return String Properly constructed path string.

   843      */

   844     public static String addTrailingFileSep(String path) {

   845         String fs = System.getProperty("file.separator");

   846         String dblfs = fs + fs;

   847         int indexDblfs;

   848         while ((indexDblfs = path.indexOf(dblfs, 1)) >= 0) {

   849             path = path.substring(0, indexDblfs) +

   850                 path.substring(indexDblfs + fs.length());

   851         }

   852         if (!path.endsWith(fs))

   853             path += fs;

   854         return path;

   855     }

   856 

   857     /**

   858      *

   859      * This checks for the validity of the options used by the user.

   860      * As of this writing, this checks only docencoding.

   861      *

   862      * @return true if all the options are valid.

   863      */

   864     public boolean generalValidOptions() {

   865         if (docencoding != null) {

   866             if (!checkOutputFileEncoding(docencoding)) {

   867                 return false;

   868             }

   869         }

   870         if (docencoding == null && (encoding != null && !encoding.isEmpty())) {

   871             if (!checkOutputFileEncoding(encoding)) {

   872                 return false;

   873             }

   874         }

   875         return true;

   876     }

   877 

   878     /**

   879      * Check the validity of the given Source or Output File encoding on this

   880      * platform.

   881      *

   882      * @param docencoding output file encoding.

   883      * @param reporter    used to report errors.

   884      */

   885     private boolean checkOutputFileEncoding(String docencoding) {

   886         OutputStream ost= new ByteArrayOutputStream();

   887         OutputStreamWriter osw = null;

   888         try {

   889             osw = new OutputStreamWriter(ost, docencoding);

   890         } catch (UnsupportedEncodingException exc) {

   891             reporter.print(ERROR, getText("doclet.Encoding_not_supported", docencoding));

   892             return false;

   893         } finally {

   894             try {

   895                 if (osw != null) {

   896                     osw.close();

   897                 }

   898             } catch (IOException exc) {

   899             }

   900         }

   901         return true;

   902     }

   903 

   904     /**

   905      * Return true if the given doc-file subdirectory should be excluded and

   906      * false otherwise.

   907      *

   908      * @param docfilesubdir the doc-files subdirectory to check.

   909      * @return true if the directory is excluded.

   910      */

   911     public boolean shouldExcludeDocFileDir(String docfilesubdir){

   912         return excludedDocFileDirs.contains(docfilesubdir);

   913     }

   914 

   915     /**

   916      * Return true if the given qualifier should be excluded and false otherwise.

   917      *

   918      * @param qualifier the qualifier to check.

   919      * @return true if the qualifier should be excluded

   920      */

   921     public boolean shouldExcludeQualifier(String qualifier){

   922         if (excludedQualifiers.contains("all") ||

   923             excludedQualifiers.contains(qualifier) ||

   924             excludedQualifiers.contains(qualifier + ".*")) {

   925             return true;

   926         } else {

   927             int index = -1;

   928             while ((index = qualifier.indexOf(".", index + 1)) != -1) {

   929                 if (excludedQualifiers.contains(qualifier.substring(0, index + 1) + "*")) {

   930                     return true;

   931                 }

   932             }

   933             return false;

   934         }

   935     }

   936 

   937     /**

   938      * Return the qualified name of the Element if its qualifier is not excluded.

   939      * Otherwise return the unqualified Element name.

   940      *

   941      * @param te the TypeElement to check.

   942      * @return the class name

   943      */

   944     public String getClassName(TypeElement te) {

   945         PackageElement pkg = utils.containingPackage(te);

   946         return shouldExcludeQualifier(utils.getPackageName(pkg))

   947                 ? utils.getSimpleName(te)

   948                 : utils.getFullyQualifiedName(te);

   949     }

   950 

   951     /**

   952      * Convenience method to obtain a resource from the doclet's

   953      * {@link Resources resources}.

   954      * Equivalent to <code>getResources.getText(key);</code>.

   955      *

   956      * @param key the key for the desired string

   957      * @return the string for the given key

   958      * @throws MissingResourceException if the key is not found in either

   959      *  bundle.

   960      */

   961     public abstract String getText(String key);

   962 

   963     /**

   964      * Convenience method to obtain a resource from the doclet's

   965      * {@link Resources resources}.

   966      * Equivalent to <code>getResources.getText(key, args);</code>.

   967      *

   968      * @param key the key for the desired string

   969      * @param args values to be substituted into the resulting string

   970      * @return the string for the given key

   971      * @throws MissingResourceException if the key is not found in either

   972      *  bundle.

   973      */

   974     public abstract String getText(String key, String... args);

   975 

   976     /**

   977      * Convenience method to obtain a resource from the doclet's

   978      * {@link Resources resources} as a {@code Content} object.

   979      *

   980      * @param key the key for the desired string

   981      * @return a content tree for the text

   982      */

   983     public abstract Content getContent(String key);

   984 

   985     /**

   986      * Convenience method to obtain a resource from the doclet's

   987      * {@link Resources resources} as a {@code Content} object.

   988      *

   989      * @param key the key for the desired string

   990      * @param o   string or content argument added to configuration text

   991      * @return a content tree for the text

   992      */

   993     public abstract Content getContent(String key, Object o);

   994 

   995     /**

   996      * Convenience method to obtain a resource from the doclet's

   997      * {@link Resources resources} as a {@code Content} object.

   998      *

   999      * @param key the key for the desired string

  1000      * @param o1 resource argument

  1001      * @param o2 resource argument

  1002      * @return a content tree for the text

  1003      */

  1004     public abstract Content getContent(String key, Object o1, Object o2);

  1005 

  1006     /**

  1007      * Get the configuration string as a content.

  1008      *

  1009      * @param key the key for the desired string

  1010      * @param o0  string or content argument added to configuration text

  1011      * @param o1  string or content argument added to configuration text

  1012      * @param o2  string or content argument added to configuration text

  1013      * @return a content tree for the text

  1014      */

  1015     public abstract Content getContent(String key, Object o0, Object o1, Object o2);

  1016 

  1017     /**

  1018      * Return true if the TypeElement element is getting documented, depending upon

  1019      * -nodeprecated option and the deprecation information. Return true if

  1020      * -nodeprecated is not used. Return false if -nodeprecated is used and if

  1021      * either TypeElement element is deprecated or the containing package is deprecated.

  1022      *

  1023      * @param te the TypeElement for which the page generation is checked

  1024      * @return true if it is a generated doc.

  1025      */

  1026     public boolean isGeneratedDoc(TypeElement te) {

  1027         if (!nodeprecated) {

  1028             return true;

  1029         }

  1030         return !(utils.isDeprecated(te) || utils.isDeprecated(utils.containingPackage(te)));

  1031     }

  1032 

  1033     /**

  1034      * Return the doclet specific instance of a writer factory.

  1035      *

  1036      * @return the {@link WriterFactory} for the doclet.

  1037      */

  1038     public abstract WriterFactory getWriterFactory();

  1039 

  1040     /**

  1041      * Return the input stream to the builder XML.

  1042      *

  1043      * @return the input steam to the builder XML.

  1044      * @throws DocFileIOException when the given XML file cannot be found or opened.

  1045      */

  1046     public InputStream getBuilderXML() throws DocFileIOException {

  1047         return builderXMLPath == null ?

  1048             Configuration.class.getResourceAsStream(DEFAULT_BUILDER_XML) :

  1049             DocFile.createFileForInput(this, builderXMLPath).openInputStream();

  1050     }

  1051 

  1052     /**

  1053      * Return the Locale for this document.

  1054      *

  1055      * @return the current locale

  1056      */

  1057     public abstract Locale getLocale();

  1058 

  1059     /**

  1060      * Return the path of the overview file and null if it does not exist.

  1061      *

  1062      * @return the path of the overview file.

  1063      */

  1064     public abstract JavaFileObject getOverviewPath();

  1065 

  1066     /**

  1067      * Return the current file manager.

  1068      *

  1069      * @return JavaFileManager

  1070      */

  1071     public abstract JavaFileManager getFileManager();

  1072 

  1073     private void setTabWidth(int n) {

  1074         sourcetab = n;

  1075         tabSpaces = String.format("%" + n + "s", "");

  1076     }

  1077 

  1078     public abstract boolean showMessage(DocTreePath path, String key);

  1079 

  1080     public abstract boolean showMessage(Element e, String key);

  1081 

  1082     public static abstract class Option implements Doclet.Option, Comparable<Option> {

  1083         private final String[] names;

  1084         private final String parameters;

  1085         private final String description;

  1086         private final int argCount;

  1087 

  1088         protected Option(Resources resources, String name, int argCount) {

  1089             this(resources, null, name, argCount);

  1090         }

  1091 

  1092         protected Option(Resources resources, String keyBase, String name, int argCount) {

  1093             this.names = name.trim().split("\\s+");

  1094             if (keyBase == null) {

  1095                 keyBase = "doclet.usage." + names[0].toLowerCase().replaceAll("^-+", "");

  1096             }

  1097             String desc = getOptionsMessage(resources, keyBase + ".description");

  1098             if (desc.isEmpty()) {

  1099                 this.description = "<MISSING KEY>";

  1100                 this.parameters = "<MISSING KEY>";

  1101             } else {

  1102                 this.description = desc;

  1103                 this.parameters = getOptionsMessage(resources, keyBase + ".parameters");

  1104             }

  1105             this.argCount = argCount;

  1106         }

  1107 

  1108         protected Option(Resources resources, String name) {

  1109             this(resources, name, 0);

  1110         }

  1111 

  1112         private String getOptionsMessage(Resources resources, String key) {

  1113             try {

  1114                 return resources.getText(key);

  1115             } catch (MissingResourceException ignore) {

  1116                 return "";

  1117             }

  1118         }

  1119 

  1120         @Override

  1121         public String getDescription() {

  1122             return description;

  1123         }

  1124 

  1125         @Override

  1126         public Option.Kind getKind() {

  1127             return Doclet.Option.Kind.STANDARD;

  1128         }

  1129 

  1130         @Override

  1131         public List<String> getNames() {

  1132             return Arrays.asList(names);

  1133         }

  1134 

  1135         @Override