1 /*

     2  * Copyright (c) 1997, 2016, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  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.tool;

    27 

    28 import java.util.Collections;

    29 import java.util.LinkedHashSet;

    30 import java.util.List;

    31 import java.util.Set;

    32 import java.util.stream.Collectors;

    33 

    34 import javax.lang.model.SourceVersion;

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

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

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

    38 import javax.lang.model.util.Elements;

    39 import javax.lang.model.util.Types;

    40 import javax.tools.JavaFileManager;

    41 

    42 import com.sun.source.util.DocTrees;

    43 import com.sun.tools.javac.code.Source;

    44 import com.sun.tools.javac.tree.JCTree.JCClassDecl;

    45 import jdk.javadoc.doclet.DocletEnvironment;

    46 

    47 /**

    48  * This class holds the information from one run of javadoc.

    49  * Particularly the packages, classes and options specified

    50  * by the user.

    51  *

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

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

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

    55  *  deletion without notice.</b>

    56  *

    57  * @author Robert Field

    58  * @author Atul M Dambalkar

    59  * @author Neal Gafter (rewrite)

    60  */

    61 public class RootDocImpl implements DocletEnvironment {

    62 

    63     /**

    64      * list of classes specified on the command line.

    65      */

    66     private Set<TypeElement> cmdLineClasses;

    67 

    68     /**

    69      * list of packages specified on the command line.

    70      */

    71     private  Set<PackageElement> cmdLinePackages;

    72 

    73     public final DocEnv env;

    74 

    75     /**

    76      * Constructor used when reading source files.

    77      *

    78      * @param env the documentation environment, state for this javadoc run

    79      * @param classes list of classes specified on the commandline

    80      * @param packages list of package names specified on the commandline

    81      */

    82     public RootDocImpl(DocEnv env, List<JCClassDecl> classes, List<String> packages) {

    83         this.env = env;

    84         setPackages(env, packages);

    85         setClasses(env, classes);

    86     }

    87 

    88     /**

    89      * Constructor used when reading class files.

    90      *

    91      * @param env the documentation environment, state for this javadoc run

    92      * @param classes list of class names specified on the commandline

    93      */

    94     public RootDocImpl(DocEnv env, List<String> classes) {

    95         //super(env, null);

    96         this.env = env;

    97 

    98         Set<TypeElement> classList = new LinkedHashSet<>();

    99         for (String className : classes) {

   100             TypeElement c = env.loadClass(className);

   101             if (c == null)

   102                 env.error(null, "javadoc.class_not_found", className);

   103             else

   104                 classList.add(c);

   105         }

   106         cmdLineClasses = classList;

   107     }

   108 

   109     /**

   110      * Initialize classes information. Those classes are input from

   111      * command line.

   112      *

   113      * @param env the compilation environment

   114      * @param classes a list of ClassDeclaration

   115      */

   116     private void setClasses(DocEnv env, List<JCClassDecl> classes) {

   117         Set<TypeElement> result = new LinkedHashSet<>();

   118         classes.stream().filter((def) -> (env.shouldDocument(def.sym))).forEach((def) -> {

   119             TypeElement te = (TypeElement)def.sym;

   120             if (te != null) {

   121                 env.setIncluded((Element)def.sym);

   122                 result.add(te);

   123             }

   124         });

   125         cmdLineClasses = Collections.unmodifiableSet(result);

   126     }

   127 

   128     /**

   129      * Initialize packages information.

   130      *

   131      * @param env the compilation environment

   132      * @param packages a list of package names (String)

   133      */

   134     private void setPackages(DocEnv env, List<String> packages) {

   135         Set<PackageElement> packlist = new LinkedHashSet<>();

   136         packages.stream().forEach((name) -> {

   137             PackageElement pkg =  getElementUtils().getPackageElement(name);

   138             if (pkg != null) {

   139                 env.setIncluded(pkg);

   140                 packlist.add(pkg);

   141             } else {

   142                 env.warning("main.no_source_files_for_package", name);

   143             }

   144         });

   145         cmdLinePackages = Collections.unmodifiableSet(packlist);

   146     }

   147 

   148     /**

   149      * Packages specified on the command line.

   150      */

   151     public Set<PackageElement> specifiedPackages() {

   152         return cmdLinePackages;

   153     }

   154 

   155     /**

   156      * Classes and interfaces specified on the command line,

   157      * including their inner classes

   158      */

   159     public Set<TypeElement> specifiedClasses() {

   160        Set<TypeElement> out = new LinkedHashSet<>();

   161        cmdLineClasses.stream().forEach((te) -> {

   162             env.addAllClasses(out, te, true);

   163         });

   164        return out;

   165     }

   166 

   167     private Set<TypeElement> classesToDocument = null;

   168     /**

   169      * Return all classes and interfaces (including those inside

   170      * packages) to be documented.

   171      */

   172     public Set<TypeElement> getIncludedClasses() {

   173         if (classesToDocument == null) {

   174             Set<TypeElement> classes = new LinkedHashSet<>();

   175 

   176             cmdLineClasses.stream().forEach((te) -> {

   177                 env.addAllClasses(classes, te, true);

   178             });

   179             cmdLinePackages.stream().forEach((pkg) -> {

   180                 env.addAllClasses(classes, pkg);

   181             });

   182             classesToDocument = Collections.unmodifiableSet(classes);

   183         }

   184         return classesToDocument;

   185     }

   186 

   187     /**

   188      * Return the name of this  item.

   189      *

   190      * @return the string <code>"*RootDocImpl*"</code>.

   191      */

   192     public String name() {

   193         return "*RootDocImpl*";

   194     }

   195 

   196     /**

   197      * Return the name of this Doc item.

   198      *

   199      * @return the string <code>"*RootDocImpl*"</code>.

   200      */

   201     public String qualifiedName() {

   202         return "*RootDocImpl*";

   203     }

   204 

   205     /**

   206      * Return true if this Element is included in the active set.

   207      * RootDocImpl isn't even a program entity so it is always false.

   208      */

   209     @Override

   210     public boolean isIncluded(Element e) {

   211         return env.isIncluded(e);

   212     }

   213 

   214 //    Note: these reporting methods are no longer used.

   215 //    /**

   216 //     * Print error message, increment error count.

   217 //     *

   218 //     * @param msg message to print

   219 //     */

   220 //    public void printError(String msg) {

   221 //        env.printError(msg);

   222 //    }

   223 //

   224 //    /**

   225 //     * Print error message, increment error count.

   226 //     *

   227 //     * @param msg message to print

   228 //     */

   229 //    public void printError(DocTreePath path, String msg) {

   230 //        env.printError(path, msg);

   231 //    }

   232 //

   233 //    public void printError(Element e, String msg) {

   234 //        env.printError(e, msg);

   235 //    }

   236 //

   237 //    public void printWarning(Element e, String msg) {

   238 //        env.printWarning(e, msg);

   239 //    }

   240 //

   241 //    public void printNotice(Element e, String msg) {

   242 //       env.printNotice(e, msg);

   243 //    }

   244 //

   245 //    /**

   246 //     * Print warning message, increment warning count.

   247 //     *

   248 //     * @param msg message to print

   249 //     */

   250 //    public void printWarning(String msg) {

   251 //        env.printWarning(msg);

   252 //    }

   253 

   254     /**

   255      * Return the current file manager.

   256      */

   257     public JavaFileManager getFileManager() {

   258         return env.fileManager;

   259     }

   260 

   261     @Override

   262     public DocTrees getDocTrees() {

   263         return env.docTrees;

   264     }

   265 

   266     @Override

   267     public Elements getElementUtils() {

   268         return env.elements;

   269     }

   270 

   271     @Override

   272     public List<Element> getSelectedElements(List<? extends Element> elements) {

   273         return elements.stream()

   274                 .filter(e -> isIncluded(e))

   275                 .collect(Collectors.<Element>toList());

   276     }

   277 

   278     @Override

   279     public Set<Element> getSpecifiedElements() {

   280         Set<Element> out = new LinkedHashSet<>();

   281         specifiedPackages().stream().forEach((pe) -> {

   282             out.add(pe);

   283         });

   284         specifiedClasses().stream().forEach((e) -> {

   285             out.add(e);

   286         });

   287         return out;

   288     }

   289 

   290     @Override

   291     public Types getTypeUtils() {

   292         return env.typeutils;

   293     }

   294 

   295     @Override

   296     public JavaFileManager getJavaFileManager() {

   297         return env.fileManager;

   298     }

   299 

   300     @Override

   301     public SourceVersion getSourceVersion() {

   302         return Source.toSourceVersion(env.source);

   303     }

   304 }