| /* |
| * Copyright (c) 2001, 2017, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| package jdk.javadoc.internal.tool; |
| |
| import java.io.IOException; |
| import java.util.ArrayList; |
| import java.util.Collection; |
| import java.util.Collections; |
| import java.util.EnumMap; |
| import java.util.EnumSet; |
| import java.util.HashMap; |
| import java.util.HashSet; |
| import java.util.LinkedHashMap; |
| import java.util.LinkedHashSet; |
| import java.util.List; |
| import java.util.Map; |
| import java.util.Set; |
| |
| import javax.lang.model.element.Element; |
| import javax.lang.model.element.ElementKind; |
| import javax.lang.model.element.Modifier; |
| import javax.lang.model.element.ModuleElement; |
| import javax.lang.model.element.ModuleElement.ExportsDirective; |
| import javax.lang.model.element.ModuleElement.RequiresDirective; |
| import javax.lang.model.element.PackageElement; |
| import javax.lang.model.element.TypeElement; |
| import javax.lang.model.util.ElementFilter; |
| import javax.lang.model.util.SimpleElementVisitor9; |
| import javax.tools.JavaFileManager; |
| import javax.tools.JavaFileManager.Location; |
| import javax.tools.JavaFileObject; |
| import javax.tools.StandardLocation; |
| |
| import com.sun.tools.javac.code.Kinds.Kind; |
| import com.sun.tools.javac.code.Source; |
| import com.sun.tools.javac.code.Source.Feature; |
| import com.sun.tools.javac.code.Symbol; |
| import com.sun.tools.javac.code.Symbol.ClassSymbol; |
| import com.sun.tools.javac.code.Symbol.CompletionFailure; |
| import com.sun.tools.javac.code.Symbol.ModuleSymbol; |
| import com.sun.tools.javac.code.Symbol.PackageSymbol; |
| import com.sun.tools.javac.code.Symtab; |
| import com.sun.tools.javac.comp.Modules; |
| import com.sun.tools.javac.main.JavaCompiler; |
| import com.sun.tools.javac.tree.JCTree.JCClassDecl; |
| import com.sun.tools.javac.tree.JCTree.JCCompilationUnit; |
| import com.sun.tools.javac.tree.JCTree.JCModuleDecl; |
| import com.sun.tools.javac.tree.TreeInfo; |
| import com.sun.tools.javac.util.Context; |
| import com.sun.tools.javac.util.ListBuffer; |
| import com.sun.tools.javac.util.Name; |
| import com.sun.tools.javac.util.Names; |
| import jdk.javadoc.doclet.DocletEnvironment; |
| import jdk.javadoc.doclet.DocletEnvironment.ModuleMode; |
| |
| import static com.sun.tools.javac.code.Scope.LookupKind.NON_RECURSIVE; |
| |
| import static javax.lang.model.util.Elements.Origin.*; |
| import static javax.tools.JavaFileObject.Kind.*; |
| |
| import static jdk.javadoc.internal.tool.Main.Result.*; |
| import static jdk.javadoc.internal.tool.JavadocTool.isValidClassName; |
| |
| |
| /** |
| * This class manages elements specified on the command line, and |
| * produces "specified" and "included" data sets, needed by the |
| * doclet environment, as well as querying an elements' visibility |
| * or inclusion. |
| * |
| * A. Initialization phase: the class is initialized with the |
| * options table by the caller. Some program elements may not |
| * be specified via specific options, such as packages, classes, |
| * these are set with the use of setter methods, such setClassArgList |
| * and setClassDeclList. |
| * |
| * B. Scan and decode phase: this is performed by scanSpecifiedItems, |
| * to identify the modules specified on the command line, modules |
| * specified with qualified packages and qualified subpackages, the |
| * modules so identified are used to initialize the module system. |
| * |
| * C. Intermediate phase: before the final analysis can be done, |
| * intermediate methods can be used to get specified elements from |
| * the initialization phase, typically used to parse sources or packages |
| * specified on the command line. |
| * |
| * D. Analysis phase: the final analysis is performed to determine |
| * the packages that ought to be included, as follows: |
| * |
| * 1. computes the specified modules, by considering the option |
| * "expand-requires", this must be done exhaustively, as the package |
| * computation phase expects a completed module graph, in order to |
| * check the target of a qualified export is in the included set. |
| * |
| * 2. computes the packages that must be documented, by considering |
| * the option "show-packages", also if only exported packages are |
| * to be considered, then also check for qualified packages, and |
| * include only those packages whose target is in the included set. |
| * |
| * 3. compute the specified packages, as part of this, first compute |
| * the subpackages and exclude any packages, if required. |
| * |
| * 4. Finally, compute the types found by previous parsing steps, |
| * noting that, all enclosed types (nested types) must also be |
| * considered. |
| * |
| * E. Finally, this class provides methods to obtain the specified sets, |
| * which are frozen and cached in the analysis phase, the included |
| * sets, are computed lazily and cached for future use. An element |
| * can be checked if it should be documented, in which case, the |
| * element is checked against the included set and the result is |
| * cached, for performance reasons. |
| * |
| * Definitions: |
| * Fully included: an element is included and some or parts |
| * of it components are included implicitly, subject to a |
| * selection criteria of its enclosed children. |
| * |
| * Included: if the item should be documented. |
| * |
| * Rules for processing: |
| * |
| * 1. A specified element, meaning an element given on the |
| * command-line, and exposed via specified elements collections. |
| * 2. Expand-contents, an internal pseudo term, meaning |
| * it is part of the recursive expansion of specified |
| * elements, meaning, the modules are expanded first, then |
| * the packages contained in the expanded modules, and then |
| * the types contained within the packages, to produce the |
| * collections returned by the methods |
| * getInclude{Module|Package|Type}Elements(), this is a |
| * downward expansion. |
| * 3. An included element, meaning it should be documented, and |
| * exposed via isIncluded, this enclosing element (module, package) |
| * is recursively included. |
| */ |
| public class ElementsTable { |
| |
| private final ToolEnvironment toolEnv; |
| private final Symtab syms; |
| private final Names names; |
| private final JavaFileManager fm; |
| private final List<Location> locations; |
| private final Modules modules; |
| private final Map<ToolOption, Object> opts; |
| private final Messager messager; |
| private final JavaCompiler compiler; |
| |
| private final Map<String, Entry> entries = new LinkedHashMap<>(); |
| |
| // specified elements |
| private Set<ModuleElement> specifiedModuleElements = new LinkedHashSet<>(); |
| private Set<PackageElement> specifiedPackageElements = new LinkedHashSet<>(); |
| private Set<TypeElement> specifiedTypeElements =new LinkedHashSet<>(); |
| |
| // included elements |
| private Set<ModuleElement> includedModuleElements = null; |
| private Set<PackageElement> includedPackageElements = null; |
| private Set<TypeElement> includedTypeElements = null; |
| |
| // cmdline specifiers |
| private Set<ModulePackage> cmdLinePackages = new LinkedHashSet<>(); |
| private Set<ModulePackage> excludePackages = new LinkedHashSet<>(); |
| private Set<ModulePackage> subPackages = new LinkedHashSet<>(); |
| |
| private List<JCClassDecl> classDecList = Collections.emptyList(); |
| private List<String> classArgList = Collections.emptyList(); |
| private com.sun.tools.javac.util.List<JCCompilationUnit> classTreeList = null; |
| |
| private final Set<JavaFileObject.Kind> sourceKinds = EnumSet.of(JavaFileObject.Kind.SOURCE); |
| |
| private final ModifierFilter accessFilter; |
| |
| private final AccessKind expandRequires; |
| |
| final boolean xclasses; |
| |
| /** |
| * Creates the table to manage included and excluded elements. |
| * |
| * @param context the context to locate commonly used objects |
| * @param location the location used to locate source files |
| */ |
| ElementsTable(Context context, Map<ToolOption, Object> opts) { |
| this.toolEnv = ToolEnvironment.instance(context); |
| this.syms = Symtab.instance(context); |
| this.names = Names.instance(context); |
| this.fm = toolEnv.fileManager; |
| this.modules = Modules.instance(context); |
| this.opts = opts; |
| this.messager = Messager.instance0(context); |
| this.compiler = JavaCompiler.instance(context); |
| Source source = Source.instance(context); |
| |
| List<Location> locs = new ArrayList<>(); |
| if (modules.multiModuleMode) { |
| locs.add(StandardLocation.MODULE_SOURCE_PATH); |
| } else { |
| if (toolEnv.fileManager.hasLocation(StandardLocation.SOURCE_PATH)) |
| locs.add(StandardLocation.SOURCE_PATH); |
| else |
| locs.add(StandardLocation.CLASS_PATH); |
| } |
| if (Feature.MODULES.allowedInSource(source) && toolEnv.fileManager.hasLocation(StandardLocation.PATCH_MODULE_PATH)) |
| locs.add(StandardLocation.PATCH_MODULE_PATH); |
| this.locations = Collections.unmodifiableList(locs); |
| |
| getEntry("").excluded = false; |
| |
| accessFilter = new ModifierFilter(opts); |
| xclasses = (boolean)opts.getOrDefault(ToolOption.XCLASSES, false); |
| expandRequires = (AccessKind)opts.get(ToolOption.EXPAND_REQUIRES); |
| } |
| |
| /** |
| * Returns the module documentation level mode. |
| * @return the module documentation level mode |
| */ |
| public ModuleMode getModuleMode() { |
| switch(accessFilter.getAccessValue(ElementKind.MODULE)) { |
| case PACKAGE: case PRIVATE: |
| return DocletEnvironment.ModuleMode.ALL; |
| default: |
| return DocletEnvironment.ModuleMode.API; |
| } |
| } |
| |
| private Set<Element> specifiedElements = null; |
| /** |
| * Returns a set of elements specified on the |
| * command line, including any inner classes. |
| * |
| * @return the set of elements specified on the command line |
| */ |
| public Set<? extends Element> getSpecifiedElements() { |
| if (specifiedElements == null) { |
| Set<Element> result = new LinkedHashSet<>(); |
| result.addAll(specifiedModuleElements); |
| result.addAll(specifiedPackageElements); |
| result.addAll(specifiedTypeElements); |
| specifiedElements = Collections.unmodifiableSet(result); |
| } |
| return specifiedElements; |
| } |
| |
| private Set<Element> includedElements = null; |
| /** |
| * Returns a set of elements included elements. The inclusion is as |
| * follows: |
| * A module is fully included, |
| * - is specified on the command line --module |
| * - is derived from the module graph, that is, by expanding the |
| * requires directive, based on --expand-requires |
| * |
| * A module is included if an enclosed package or type is |
| * specified on the command line. |
| * |
| * A package is fully included, |
| * - is specified on the command line |
| * - is derived from expanding -subpackages |
| * - can be documented in a fully included module based on --show-packages |
| * |
| * A package is included, if an enclosed package or a type is specified on |
| * the command line. |
| * |
| * Included type elements (including those within specified or included packages) |
| * to be documented. |
| * |
| * A type is fully included if |
| * - is specified on the command line with -sourcepath |
| * - is visible with --show-types filter |
| * A nested type is fully included if |
| * - is visible with --show-types filter |
| * - is enclosed in a fully included type |
| * @return the set of elements specified on the command line |
| */ |
| public Set<? extends Element> getIncludedElements() { |
| if (includedElements == null) { |
| Set<Element> result = new LinkedHashSet<>(); |
| result.addAll(includedModuleElements); |
| result.addAll(includedPackageElements); |
| result.addAll(includedTypeElements); |
| includedElements = Collections.unmodifiableSet(result); |
| } |
| return includedElements; |
| } |
| |
| private IncludedVisitor includedVisitor = null; |
| |
| /** |
| * Returns true if the given element is included for consideration. |
| * This method accumulates elements in the cache as enclosed elements of |
| * fully included elements are tested. |
| * A member (constructor, method, field) is included if |
| * - it is visible in a fully included type (--show-members) |
| * |
| * @param e the element in question |
| * |
| * @see getIncludedModuleElements |
| * @see getIncludedPackageElements |
| * @see getIncludedTypeElements |
| * |
| * @return true if included |
| */ |
| public boolean isIncluded(Element e) { |
| if (e == null) { |
| return false; |
| } |
| if (includedVisitor == null) { |
| includedVisitor = new IncludedVisitor(); |
| } |
| return includedVisitor.visit(e); |
| } |
| |
| /** |
| * Performs the final computation and freezes the collections. |
| * This is a terminal operation, thus no further modifications |
| * are allowed to the specified data sets. |
| * |
| * @throws ToolException if an error occurs |
| */ |
| void analyze() throws ToolException { |
| // compute the specified element, by expanding module dependencies |
| computeSpecifiedModules(); |
| |
| // compute all specified packages and subpackages |
| computeSpecifiedPackages(); |
| |
| // compute the specified types |
| computeSpecifiedTypes(); |
| |
| // compute the packages belonging to all the specified modules |
| Set<PackageElement> expandedModulePackages = computeModulePackages(); |
| initializeIncludedSets(expandedModulePackages); |
| } |
| |
| ElementsTable classTrees(com.sun.tools.javac.util.List<JCCompilationUnit> classTrees) { |
| this.classTreeList = classTrees; |
| return this; |
| } |
| |
| /* |
| * This method sanity checks the following cases: |
| * a. a source-path containing a single module and many modules specified with --module |
| * b. no modules on source-path |
| * c. mismatched source-path and many modules specified with --module |
| */ |
| void sanityCheckSourcePathModules(List<String> moduleNames) throws ToolException { |
| if (!haveSourceLocationWithModule) |
| return; |
| |
| if (moduleNames.size() > 1) { |
| String text = messager.getText("main.cannot_use_sourcepath_for_modules", |
| String.join(", ", moduleNames)); |
| throw new ToolException(CMDERR, text); |
| } |
| |
| String foundModule = getModuleName(StandardLocation.SOURCE_PATH); |
| if (foundModule == null) { |
| String text = messager.getText("main.module_not_found_on_sourcepath", moduleNames.get(0)); |
| throw new ToolException(CMDERR, text); |
| } |
| |
| if (!moduleNames.get(0).equals(foundModule)) { |
| String text = messager.getText("main.sourcepath_does_not_contain_module", moduleNames.get(0)); |
| throw new ToolException(CMDERR, text); |
| } |
| } |
| |
| private String getModuleName(Location location) throws ToolException { |
| try { |
| JavaFileObject jfo = fm.getJavaFileForInput(location, |
| "module-info", JavaFileObject.Kind.SOURCE); |
| if (jfo != null) { |
| JCCompilationUnit jcu = compiler.parse(jfo); |
| JCModuleDecl module = TreeInfo.getModule(jcu); |
| if (module != null) { |
| return module.getName().toString(); |
| } |
| } |
| } catch (IOException ioe) { |
| String text = messager.getText("main.file.manager.list", location); |
| throw new ToolException(SYSERR, text, ioe); |
| } |
| return null; |
| } |
| |
| @SuppressWarnings("unchecked") |
| ElementsTable scanSpecifiedItems() throws ToolException { |
| |
| // scan modules specified on the command line |
| List<String> moduleNames = (List<String>) opts.computeIfAbsent(ToolOption.MODULE, |
| s -> Collections.EMPTY_LIST); |
| List<String> mlist = new ArrayList<>(); |
| for (String m : moduleNames) { |
| List<Location> moduleLocations = getModuleLocation(locations, m); |
| if (moduleLocations.isEmpty()) { |
| String text = messager.getText("main.module_not_found", m); |
| throw new ToolException(CMDERR, text); |
| } |
| if (moduleLocations.contains(StandardLocation.SOURCE_PATH)) { |
| sanityCheckSourcePathModules(moduleNames); |
| } |
| mlist.add(m); |
| ModuleSymbol msym = syms.enterModule(names.fromString(m)); |
| specifiedModuleElements.add((ModuleElement) msym); |
| } |
| |
| // scan for modules with qualified packages |
| cmdLinePackages.stream() |
| .filter((mpkg) -> (mpkg.hasModule())) |
| .forEachOrdered((mpkg) -> { |
| mlist.add(mpkg.moduleName); |
| }); |
| |
| // scan for modules with qualified subpackages |
| ((List<String>)opts.computeIfAbsent(ToolOption.SUBPACKAGES, v -> Collections.EMPTY_LIST)) |
| .stream() |
| .map(ModulePackage::new) |
| .forEachOrdered((mpkg) -> { |
| subPackages.add(mpkg); |
| if (mpkg.hasModule()) { |
| mlist.add(mpkg.moduleName); |
| } |
| }); |
| |
| // all the modules specified on the command line have been scraped |
| // init the module systems |
| modules.addExtraAddModules(mlist.toArray(new String[mlist.size()])); |
| modules.initModules(this.classTreeList); |
| |
| return this; |
| } |
| |
| /** |
| * Returns the includes table after setting a class names specified on the command line. |
| * |
| * @param classList |
| * @return the include table |
| */ |
| ElementsTable setClassArgList(List<String> classList) { |
| classArgList = classList; |
| return this; |
| } |
| |
| /** |
| * Returns the includes table after setting the parsed class names. |
| * |
| * @param classesDecList |
| * @return the include table |
| */ |
| ElementsTable setClassDeclList(List<JCClassDecl> classesDecList) { |
| this.classDecList = classesDecList; |
| return this; |
| } |
| |
| /** |
| * Returns an includes table after setting the specified package |
| * names. |
| * @param packageNames packages on the command line |
| * @return the includes table after setting the specified package |
| * names |
| */ |
| ElementsTable packages(Collection<String> packageNames) { |
| packageNames.stream() |
| .map(ModulePackage::new) |
| .forEachOrdered((mpkg) -> cmdLinePackages.add(mpkg)); |
| return this; |
| } |
| |
| /** |
| * Returns the aggregate set of included packages and specified |
| * sub packages. |
| * |
| * @return the aggregate set of included packages and specified |
| * sub packages |
| */ |
| Iterable<ModulePackage> getPackagesToParse() throws IOException { |
| List<ModulePackage> result = new ArrayList<>(); |
| result.addAll(cmdLinePackages); |
| result.addAll(subPackages); |
| return result; |
| } |
| |
| @SuppressWarnings("unchecked") |
| private void computeSubpackages() throws ToolException { |
| ((List<String>) opts.computeIfAbsent(ToolOption.EXCLUDE, v -> Collections.EMPTY_LIST)) |
| .stream() |
| .map(ModulePackage::new) |
| .forEachOrdered((mpkg) -> excludePackages.add(mpkg)); |
| |
| excludePackages.forEach((p) -> { |
| getEntry(p).excluded = true; |
| }); |
| |
| for (ModulePackage modpkg : subPackages) { |
| List<Location> locs = getLocation(modpkg); |
| for (Location loc : locs) { |
| addPackagesFromLocations(loc, modpkg); |
| } |
| } |
| } |
| |
| /* Call fm.list and wrap any IOException that occurs in a ToolException */ |
| private Iterable<JavaFileObject> fmList(Location location, |
| String packagename, |
| Set<JavaFileObject.Kind> kinds, |
| boolean recurse) throws ToolException { |
| try { |
| return fm.list(location, packagename, kinds, recurse); |
| } catch (IOException ioe) { |
| String text = messager.getText("main.file.manager.list", packagename); |
| throw new ToolException(SYSERR, text, ioe); |
| } |
| } |
| |
| private void addPackagesFromLocations(Location packageLocn, ModulePackage modpkg) throws ToolException { |
| for (JavaFileObject fo : fmList(packageLocn, modpkg.packageName, sourceKinds, true)) { |
| String binaryName = fm.inferBinaryName(packageLocn, fo); |
| String pn = getPackageName(binaryName); |
| String simpleName = getSimpleName(binaryName); |
| Entry e = getEntry(pn); |
| if (!e.isExcluded() && isValidClassName(simpleName)) { |
| ModuleSymbol msym = (modpkg.hasModule()) |
| ? syms.getModule(names.fromString(modpkg.moduleName)) |
| : findModuleOfPackageName(modpkg.packageName); |
| |
| if (msym != null && !msym.isUnnamed()) { |
| syms.enterPackage(msym, names.fromString(pn)); |
| ModulePackage npkg = new ModulePackage(msym.toString(), pn); |
| cmdLinePackages.add(npkg); |
| } else { |
| cmdLinePackages.add(e.modpkg); |
| } |
| e.files = (e.files == null |
| ? com.sun.tools.javac.util.List.of(fo) |
| : e.files.prepend(fo)); |
| } |
| } |
| } |
| |
| /** |
| * Returns the "requires" modules for the target module. |
| * @param mdle the target module element |
| * @param onlyTransitive true gets all the requires transitive, otherwise |
| * gets all the non-transitive requires |
| * |
| * @return a set of modules |
| */ |
| private Set<ModuleElement> getModuleRequires(ModuleElement mdle, boolean onlyTransitive) throws ToolException { |
| Set<ModuleElement> result = new HashSet<>(); |
| for (RequiresDirective rd : ElementFilter.requiresIn(mdle.getDirectives())) { |
| ModuleElement dep = rd.getDependency(); |
| if (result.contains(dep)) |
| continue; |
| if (!isMandated(mdle, rd) && onlyTransitive == rd.isTransitive()) { |
| if (!haveModuleSources(dep)) { |
| messager.printWarning(dep, "main.module_not_found", dep.getSimpleName()); |
| } |
| result.add(dep); |
| } else if (isMandated(mdle, rd) && haveModuleSources(dep)) { |
| result.add(dep); |
| } |
| } |
| return result; |
| } |
| |
| private boolean isMandated(ModuleElement mdle, RequiresDirective rd) { |
| return toolEnv.elements.getOrigin(mdle, rd) == MANDATED; |
| } |
| |
| Map<ModuleSymbol, Boolean> haveModuleSourcesCache = new HashMap<>(); |
| private boolean haveModuleSources(ModuleElement mdle) throws ToolException { |
| ModuleSymbol msym = (ModuleSymbol)mdle; |
| if (msym.sourceLocation != null) { |
| return true; |
| } |
| if (msym.patchLocation != null) { |
| Boolean value = haveModuleSourcesCache.get(msym); |
| if (value == null) { |
| value = fmList(msym.patchLocation, "", sourceKinds, true).iterator().hasNext(); |
| haveModuleSourcesCache.put(msym, value); |
| } |
| return value; |
| } |
| return false; |
| } |
| |
| private void computeSpecifiedModules() throws ToolException { |
| if (expandRequires == null) { // no expansion requested |
| specifiedModuleElements = Collections.unmodifiableSet(specifiedModuleElements); |
| return; |
| } |
| |
| final boolean expandAll = expandRequires.equals(AccessKind.PRIVATE) |
| || expandRequires.equals(AccessKind.PACKAGE); |
| |
| Set<ModuleElement> result = new LinkedHashSet<>(); |
| ListBuffer<ModuleElement> queue = new ListBuffer<>(); |
| |
| // expand each specified module |
| for (ModuleElement mdle : specifiedModuleElements) { |
| result.add(mdle); // a specified module is included |
| queue.append(mdle); |
| Set<ModuleElement> publicRequires = getModuleRequires(mdle, true); |
| result.addAll(publicRequires); |
| // add all requires public |
| queue.addAll(publicRequires); |
| |
| if (expandAll) { |
| // add non-public requires if needed |
| result.addAll(getModuleRequires(mdle, !expandAll)); |
| } |
| } |
| |
| // compute the transitive closure of all the requires public |
| for (ModuleElement m = queue.poll() ; m != null ; m = queue.poll()) { |
| for (ModuleElement mdle : getModuleRequires(m, true)) { |
| if (!result.contains(mdle)) { |
| result.add(mdle); |
| queue.append(mdle); |
| } |
| } |
| } |
| specifiedModuleElements = Collections.unmodifiableSet(result); |
| } |
| |
| private Set<PackageElement> getAllModulePackages(ModuleElement mdle) throws ToolException { |
| Set<PackageElement> result = new HashSet<>(); |
| ModuleSymbol msym = (ModuleSymbol) mdle; |
| List<Location> msymlocs = getModuleLocation(locations, msym.name.toString()); |
| for (Location msymloc : msymlocs) { |
| for (JavaFileObject fo : fmList(msymloc, "", sourceKinds, true)) { |
| if (fo.getName().endsWith("module-info.java")) { |
| continue; |
| } |
| String binaryName = fm.inferBinaryName(msymloc, fo); |
| String pn = getPackageName(binaryName); |
| PackageSymbol psym = syms.enterPackage(msym, names.fromString(pn)); |
| result.add((PackageElement) psym); |
| } |
| } |
| return result; |
| } |
| |
| private Set<PackageElement> computeModulePackages() throws ToolException { |
| AccessKind accessValue = accessFilter.getAccessValue(ElementKind.PACKAGE); |
| final boolean documentAllModulePackages = (accessValue == AccessKind.PACKAGE || |
| accessValue == AccessKind.PRIVATE); |
| |
| accessValue = accessFilter.getAccessValue(ElementKind.MODULE); |
| final boolean moduleDetailedMode = (accessValue == AccessKind.PACKAGE || |
| accessValue == AccessKind.PRIVATE); |
| Set<PackageElement> expandedModulePackages = new LinkedHashSet<>(); |
| |
| for (ModuleElement mdle : specifiedModuleElements) { |
| if (documentAllModulePackages) { // include all packages |
| List<PackageElement> packages = ElementFilter.packagesIn(mdle.getEnclosedElements()); |
| expandedModulePackages.addAll(packages); |
| expandedModulePackages.addAll(getAllModulePackages(mdle)); |
| } else { // selectively include required packages |
| List<ExportsDirective> exports = ElementFilter.exportsIn(mdle.getDirectives()); |
| for (ExportsDirective export : exports) { |
| // add if fully exported or add qualified exports only if desired |
| if (export.getTargetModules() == null |
| || documentAllModulePackages || moduleDetailedMode) { |
| expandedModulePackages.add(export.getPackage()); |
| } |
| } |
| } |
| |
| // add all packages specified on the command line |
| // belonging to this module |
| if (!cmdLinePackages.isEmpty()) { |
| for (ModulePackage modpkg : cmdLinePackages) { |
| PackageElement pkg = toolEnv.elements.getPackageElement(mdle, |
| modpkg.packageName); |
| if (pkg != null) { |
| expandedModulePackages.add(pkg); |
| } |
| } |
| } |
| } |
| return expandedModulePackages; |
| } |
| |
| private void initializeIncludedSets(Set<PackageElement> expandedModulePackages) { |
| |
| // process modules |
| Set<ModuleElement> imodules = new LinkedHashSet<>(); |
| // add all the expanded modules |
| imodules.addAll(specifiedModuleElements); |
| |
| // process packages |
| Set<PackageElement> ipackages = new LinkedHashSet<>(); |
| // add all packages belonging to expanded modules |
| ipackages.addAll(expandedModulePackages); |
| // add all specified packages |
| specifiedPackageElements.forEach(pkg -> { |
| ModuleElement mdle = toolEnv.elements.getModuleOf(pkg); |
| if (mdle != null) |
| imodules.add(mdle); |
| ipackages.add(pkg); |
| }); |
| |
| // process types |
| Set<TypeElement> iclasses = new LinkedHashSet<>(); |
| // add all types enclosed in expanded modules and packages |
| ipackages.forEach((pkg) -> { |
| addAllClasses(iclasses, pkg); |
| }); |
| // add all types and its nested types |
| specifiedTypeElements.forEach((klass) -> { |
| ModuleElement mdle = toolEnv.elements.getModuleOf(klass); |
| if (mdle != null && !mdle.isUnnamed()) |
| imodules.add(mdle); |
| PackageElement pkg = toolEnv.elements.getPackageOf(klass); |
| ipackages.add(pkg); |
| addAllClasses(iclasses, klass, true); |
| }); |
| |
| // all done, freeze the collections |
| includedModuleElements = Collections.unmodifiableSet(imodules); |
| includedPackageElements = Collections.unmodifiableSet(ipackages); |
| includedTypeElements = Collections.unmodifiableSet(iclasses); |
| } |
| |
| /* |
| * Computes the included packages and freezes the specified packages list. |
| */ |
| private void computeSpecifiedPackages() throws ToolException { |
| |
| computeSubpackages(); |
| |
| Set<PackageElement> packlist = new LinkedHashSet<>(); |
| cmdLinePackages.forEach((modpkg) -> { |
| PackageElement pkg; |
| if (modpkg.hasModule()) { |
| ModuleElement mdle = toolEnv.elements.getModuleElement(modpkg.moduleName); |
| pkg = toolEnv.elements.getPackageElement(mdle, modpkg.packageName); |
| } else { |
| pkg = toolEnv.elements.getPackageElement(modpkg.toString()); |
| } |
| |
| if (pkg != null) { |
| packlist.add(pkg); |
| } else { |
| messager.printWarningUsingKey("main.package_not_found", modpkg.toString()); |
| } |
| }); |
| specifiedPackageElements = Collections.unmodifiableSet(packlist); |
| } |
| |
| /** |
| * Adds all classes as well as inner classes, to the specified |
| * list. |
| */ |
| private void computeSpecifiedTypes() throws ToolException { |
| Set<TypeElement> classes = new LinkedHashSet<>(); |
| classDecList.forEach((def) -> { |
| TypeElement te = (TypeElement) def.sym; |
| if (te != null) { |
| addAllClasses(classes, te, true); |
| } |
| }); |
| for (String className : classArgList) { |
| TypeElement te = toolEnv.loadClass(className); |
| if (te == null) { |
| String text = messager.getText("javadoc.class_not_found", className); |
| throw new ToolException(CMDERR, text); |
| } else { |
| addAllClasses(classes, te, true); |
| } |
| } |
| specifiedTypeElements = Collections.unmodifiableSet(classes); |
| } |
| |
| private void addFilesForParser(Collection<JavaFileObject> result, |
| Collection<ModulePackage> collection, |
| boolean recurse) throws ToolException { |
| for (ModulePackage modpkg : collection) { |
| toolEnv.notice("main.Loading_source_files_for_package", modpkg.toString()); |
| List<JavaFileObject> files = getFiles(modpkg, recurse); |
| if (files.isEmpty()) { |
| String text = messager.getText("main.no_source_files_for_package", |
| modpkg.toString()); |
| throw new ToolException(CMDERR, text); |
| } else { |
| result.addAll(files); |
| } |
| } |
| } |
| |
| /** |
| * Returns an aggregated list of java file objects from the items |
| * specified on the command line. The packages specified should not |
| * recurse, however sub-packages should recurse into the sub directories. |
| * @return a list of java file objects |
| * @throws IOException if an error occurs |
| */ |
| List<JavaFileObject> getFilesToParse() throws ToolException { |
| List<JavaFileObject> result = new ArrayList<>(); |
| addFilesForParser(result, cmdLinePackages, false); |
| addFilesForParser(result, subPackages, true); |
| return result; |
| } |
| |
| /** |
| * Returns the set of source files for a package. |
| * |
| * @param packageName the specified package |
| * @return the set of file objects for the specified package |
| * @throws ToolException if an error occurs while accessing the files |
| */ |
| private List<JavaFileObject> getFiles(ModulePackage modpkg, |
| boolean recurse) throws ToolException { |
| Entry e = getEntry(modpkg); |
| // The files may have been found as a side effect of searching for subpackages |
| if (e.files != null) { |
| return e.files; |
| } |
| |
| ListBuffer<JavaFileObject> lb = new ListBuffer<>(); |
| List<Location> locs = getLocation(modpkg); |
| if (locs.isEmpty()) { |
| return Collections.emptyList(); |
| } |
| String pname = modpkg.packageName; |
| for (Location packageLocn : locs) { |
| for (JavaFileObject fo : fmList(packageLocn, pname, sourceKinds, recurse)) { |
| String binaryName = fm.inferBinaryName(packageLocn, fo); |
| String simpleName = getSimpleName(binaryName); |
| if (isValidClassName(simpleName)) { |
| lb.append(fo); |
| } |
| } |
| } |
| return lb.toList(); |
| } |
| |
| private ModuleSymbol findModuleOfPackageName(String packageName) { |
| Name pack = names.fromString(packageName); |
| for (ModuleSymbol msym : modules.allModules()) { |
| PackageSymbol p = syms.getPackage(msym, pack); |
| if (p != null && !p.members().isEmpty()) { |
| return msym; |
| } |
| } |
| return null; |
| } |
| |
| private List<Location> getLocation(ModulePackage modpkg) throws ToolException { |
| if (locations.size() == 1 && !locations.contains(StandardLocation.MODULE_SOURCE_PATH)) { |
| return Collections.singletonList(locations.get(0)); |
| } |
| |
| if (modpkg.hasModule()) { |
| return getModuleLocation(locations, modpkg.moduleName); |
| } |
| // TODO: handle invalid results better. |
| ModuleSymbol msym = findModuleOfPackageName(modpkg.packageName); |
| if (msym == null) { |
| return Collections.emptyList(); |
| } |
| return getModuleLocation(locations, msym.name.toString()); |
| } |
| |
| boolean haveSourceLocationWithModule = false; |
| |
| private List<Location> getModuleLocation(List<Location> locations, String msymName) throws ToolException { |
| List<Location> out = new ArrayList<>(); |
| // search in the patch module first, this overrides others |
| if (locations.contains(StandardLocation.PATCH_MODULE_PATH)) { |
| Location loc = getModuleLocation(StandardLocation.PATCH_MODULE_PATH, msymName); |
| if (loc != null) |
| out.add(loc); |
| } |
| for (Location location : locations) { |
| // skip patch module, already done |
| if (location == StandardLocation.PATCH_MODULE_PATH) { |
| continue; |
| } else if (location == StandardLocation.MODULE_SOURCE_PATH) { |
| Location loc = getModuleLocation(location, msymName); |
| if (loc != null) |
| out.add(loc); |
| } else if (location == StandardLocation.SOURCE_PATH) { |
| haveSourceLocationWithModule = true; |
| out.add(StandardLocation.SOURCE_PATH); |
| } |
| } |
| return out; |
| } |
| |
| private Location getModuleLocation(Location location, String msymName) throws ToolException { |
| try { |
| return fm.getLocationForModule(location, msymName); |
| } catch (IOException ioe) { |
| String text = messager.getText("main.doclet_could_not_get_location", msymName); |
| throw new ToolException(ERROR, text, ioe); |
| } |
| } |
| |
| private Entry getEntry(String name) { |
| return getEntry(new ModulePackage(name)); |
| } |
| |
| private Entry getEntry(ModulePackage modpkg) { |
| Entry e = entries.get(modpkg.packageName); |
| if (e == null) { |
| entries.put(modpkg.packageName, e = new Entry(modpkg)); |
| } |
| return e; |
| } |
| |
| private String getPackageName(String name) { |
| int lastDot = name.lastIndexOf("."); |
| return (lastDot == -1 ? "" : name.substring(0, lastDot)); |
| } |
| |
| private String getSimpleName(String name) { |
| int lastDot = name.lastIndexOf("."); |
| return (lastDot == -1 ? name : name.substring(lastDot + 1)); |
| } |
| |
| /** |
| * Adds all inner classes of this class, and their inner classes recursively, to the list |
| */ |
| private void addAllClasses(Collection<TypeElement> list, TypeElement typeElement, boolean filtered) { |
| ClassSymbol klass = (ClassSymbol)typeElement; |
| try { |
| // eliminate needless checking, do this first. |
| if (list.contains(klass)) return; |
| // ignore classes with invalid Java class names |
| if (!JavadocTool.isValidClassName(klass.name.toString())) return; |
| if (filtered && !isTypeElementSelected(klass)) return; |
| list.add(klass); |
| for (Symbol sym : klass.members().getSymbols(NON_RECURSIVE)) { |
| if (sym != null && sym.kind == Kind.TYP) { |
| ClassSymbol s = (ClassSymbol)sym; |
| addAllClasses(list, s, filtered); |
| } |
| } |
| } catch (CompletionFailure e) { |
| if (e.getMessage() != null) |
| messager.printWarning(e.getMessage()); |
| else |
| messager.printWarningUsingKey("main.unexpected.exception", e); |
| } |
| } |
| |
| /** |
| * Returns a list of all classes contained in this package, including |
| * member classes of those classes, and their member classes, etc. |
| */ |
| private void addAllClasses(Collection<TypeElement> list, PackageElement pkg) { |
| boolean filtered = true; |
| for (Element isym : pkg.getEnclosedElements()) { |
| addAllClasses(list, (TypeElement)isym, filtered); |
| } |
| } |
| |
| private boolean isTypeElementSelected(TypeElement te) { |
| return (xclasses || toolEnv.getFileKind(te) == SOURCE) && isSelected(te); |
| } |
| |
| SimpleElementVisitor9<Boolean, Void> visibleElementVisitor = null; |
| /** |
| * Returns true if the element is selected, by applying |
| * the access filter checks. Special treatment is applied to |
| * types, for a top level type the access filter applies completely, |
| * however if is a nested type then it is allowed either if |
| * the enclosing is a static or the enclosing is also selected. |
| * |
| * @param e the element to be checked |
| * @return true if the element is visible |
| */ |
| public boolean isSelected(Element e) { |
| if (toolEnv.isSynthetic((Symbol) e)) { |
| return false; |
| } |
| if (visibleElementVisitor == null) { |
| visibleElementVisitor = new SimpleElementVisitor9<Boolean, Void>() { |
| @Override |
| public Boolean visitType(TypeElement e, Void p) { |
| if (!accessFilter.checkModifier(e)) { |
| return false; // it is not allowed |
| } |
| Element encl = e.getEnclosingElement(); |
| |
| // check if nested |
| if (encl.getKind() == ElementKind.PACKAGE) |
| return true; // top-level class, allow it |
| |
| // is enclosed static |
| if (encl.getModifiers().contains(Modifier.STATIC)) |
| return true; // allowed |
| |
| // check the enclosing |
| return visit(encl); |
| } |
| |
| @Override |
| protected Boolean defaultAction(Element e, Void p) { |
| return accessFilter.checkModifier(e); |
| } |
| |
| @Override |
| public Boolean visitUnknown(Element e, Void p) { |
| throw new AssertionError("unkown element: " + p); |
| } |
| }; |
| } |
| return visibleElementVisitor.visit(e); |
| } |
| |
| private class IncludedVisitor extends SimpleElementVisitor9<Boolean, Void> { |
| final private Set<Element> includedCache; |
| |
| public IncludedVisitor() { |
| includedCache = new LinkedHashSet<>(); |
| } |
| |
| @Override |
| public Boolean visitModule(ModuleElement e, Void p) { |
| // deduced by specified and/or requires expansion |
| return includedModuleElements.contains(e); |
| } |
| |
| @Override |
| public Boolean visitPackage(PackageElement e, Void p) { |
| // deduced by specified or downward expansions |
| return includedPackageElements.contains(e); |
| } |
| |
| @Override |
| public Boolean visitType(TypeElement e, Void p) { |
| if (includedTypeElements.contains(e)) { |
| return true; |
| } |
| if (isTypeElementSelected(e)) { |
| // Class is nameable from top-level and |
| // the class and all enclosing classes |
| // pass the modifier filter. |
| PackageElement pkg = toolEnv.elements.getPackageOf(e); |
| if (specifiedPackageElements.contains(pkg)) { |
| return true; |
| } |
| Element enclosing = e.getEnclosingElement(); |
| if (enclosing != null) { |
| switch(enclosing.getKind()) { |
| case PACKAGE: |
| return specifiedPackageElements.contains((PackageElement)enclosing); |
| case CLASS: case INTERFACE: case ENUM: case ANNOTATION_TYPE: |
| return visit((TypeElement) enclosing); |
| default: |
| throw new AssertionError("unknown element: " + enclosing); |
| } |
| } |
| } |
| return false; |
| } |
| |
| // members |
| @Override |
| public Boolean defaultAction(Element e, Void p) { |
| if (includedCache.contains(e)) |
| return true; |
| if (visit(e.getEnclosingElement()) && isSelected(e)) { |
| switch(e.getKind()) { |
| case ANNOTATION_TYPE: case CLASS: case ENUM: case INTERFACE: |
| case MODULE: case OTHER: case PACKAGE: |
| throw new AssertionError("invalid element for this operation: " + e); |
| default: |
| // the only allowed kinds in the cache are "members" |
| includedCache.add(e); |
| return true; |
| } |
| } |
| return false; |
| } |
| |
| @Override |
| public Boolean visitUnknown(Element e, Void p) { |
| throw new AssertionError("unknown element: " + e); |
| } |
| |
| } |
| |
| class Entry { |
| final ModulePackage modpkg; |
| Boolean excluded = false; |
| com.sun.tools.javac.util.List<JavaFileObject> files; |
| |
| Entry(ModulePackage modpkg) { |
| this.modpkg = modpkg; |
| } |
| |
| Entry(String name) { |
| modpkg = new ModulePackage(name); |
| } |
| |
| boolean isExcluded() { |
| return excluded; |
| } |
| |
| @Override |
| public String toString() { |
| return "Entry{" + "modpkg=" + modpkg + ", excluded=" + excluded + ", files=" + files + '}'; |
| } |
| } |
| |
| /** |
| * A container class to retrieve the module and package pair |
| * from a parsed qualified package name. |
| */ |
| static class ModulePackage { |
| |
| public final String moduleName; |
| public final String packageName; |
| |
| ModulePackage(String modulename, String packagename) { |
| this.moduleName = modulename; |
| this.packageName = packagename; |
| } |
| |
| ModulePackage(ModuleElement msym, String packagename) { |
| this.moduleName = msym.toString(); |
| this.packageName = packagename; |
| } |
| |
| ModulePackage(String name) { |
| String a[] = name.split("/"); |
| if (a.length == 2) { |
| this.moduleName = a[0]; |
| this.packageName = a[1]; |
| } else { |
| moduleName = null; |
| packageName = name; |
| } |
| } |
| |
| boolean hasModule() { |
| return this.moduleName != null; |
| } |
| |
| @Override |
| public boolean equals(Object obj) { |
| if (obj instanceof ModulePackage) { |
| ModulePackage that = (ModulePackage)obj; |
| return this.toString().equals(that.toString()); |
| } |
| return false; |
| } |
| |
| @Override |
| public int hashCode() { |
| return toString().hashCode(); |
| } |
| |
| @Override |
| public String toString() { |
| return moduleName == null ? packageName : moduleName + "/" + packageName; |
| } |
| } |
| |
| /** |
| * A class which filters the access flags on classes, fields, methods, etc. |
| * |
| * @see javax.lang.model.element.Modifier |
| */ |
| |
| static class ModifierFilter { |
| /** |
| * The allowed ElementKind that can be stored. |
| */ |
| static final EnumSet<ElementKind> ALLOWED_KINDS = EnumSet.of(ElementKind.METHOD, |
| ElementKind.CLASS, |
| ElementKind.PACKAGE, |
| ElementKind.MODULE); |
| |
| // all possible accesss levels allowed for each element |
| private final EnumMap<ElementKind, EnumSet<AccessKind>> filterMap = |
| new EnumMap<>(ElementKind.class); |
| |
| // the specified access level for each element |
| private final EnumMap<ElementKind, AccessKind> accessMap = |
| new EnumMap<>(ElementKind.class); |
| |
| /** |
| * Constructor - Specify a filter. |
| * |
| * @param accessSet an Access filter. |
| */ |
| ModifierFilter(Map<ToolOption, Object> opts) { |
| |
| AccessKind accessValue = null; |
| for (ElementKind kind : ALLOWED_KINDS) { |
| switch (kind) { |
| case METHOD: |
| accessValue = (AccessKind)opts.get(ToolOption.SHOW_MEMBERS); |
| break; |
| case CLASS: |
| accessValue = (AccessKind)opts.get(ToolOption.SHOW_TYPES); |
| break; |
| case PACKAGE: |
| accessValue = (AccessKind)opts.get(ToolOption.SHOW_PACKAGES); |
| break; |
| case MODULE: |
| accessValue = (AccessKind)opts.get(ToolOption.SHOW_MODULE_CONTENTS); |
| break; |
| default: |
| throw new AssertionError("unknown element: " + kind); |
| |
| } |
| accessMap.put(kind, accessValue); |
| filterMap.put(kind, getFilterSet(accessValue)); |
| } |
| } |
| |
| static EnumSet<AccessKind> getFilterSet(AccessKind acccessValue) { |
| switch (acccessValue) { |
| case PUBLIC: |
| return EnumSet.of(AccessKind.PUBLIC); |
| case PROTECTED: |
| default: |
| return EnumSet.of(AccessKind.PUBLIC, AccessKind.PROTECTED); |
| case PACKAGE: |
| return EnumSet.of(AccessKind.PUBLIC, AccessKind.PROTECTED, AccessKind.PACKAGE); |
| case PRIVATE: |
| return EnumSet.allOf(AccessKind.class); |
| } |
| } |
| |
| public AccessKind getAccessValue(ElementKind kind) { |
| if (!ALLOWED_KINDS.contains(kind)) { |
| throw new IllegalArgumentException("not allowed: " + kind); |
| } |
| return accessMap.getOrDefault(kind, AccessKind.PROTECTED); |
| } |
| |
| /** |
| * Returns true if access is allowed. |
| * |
| * @param e the element in question |
| * @return whether the modifiers pass this filter |
| */ |
| public boolean checkModifier(Element e) { |
| Set<Modifier> modifiers = e.getModifiers(); |
| AccessKind fflag = AccessKind.PACKAGE; |
| if (modifiers.contains(Modifier.PUBLIC)) { |
| fflag = AccessKind.PUBLIC; |
| } else if (modifiers.contains(Modifier.PROTECTED)) { |
| fflag = AccessKind.PROTECTED; |
| } else if (modifiers.contains(Modifier.PRIVATE)) { |
| fflag = AccessKind.PRIVATE; |
| } |
| EnumSet<AccessKind> filterSet = filterMap.get(getAllowedKind(e.getKind())); |
| return filterSet.contains(fflag); |
| } |
| |
| // convert a requested element kind to an allowed access kind |
| private ElementKind getAllowedKind(ElementKind kind) { |
| switch (kind) { |
| case CLASS: case METHOD: case MODULE: case PACKAGE: |
| return kind; |
| case ANNOTATION_TYPE: case ENUM: case INTERFACE: |
| return ElementKind.CLASS; |
| case CONSTRUCTOR: case ENUM_CONSTANT: case EXCEPTION_PARAMETER: |
| case FIELD: case INSTANCE_INIT: case LOCAL_VARIABLE: case PARAMETER: |
| case RESOURCE_VARIABLE: case STATIC_INIT: case TYPE_PARAMETER: |
| return ElementKind.METHOD; |
| default: |
| throw new AssertionError("unsupported kind: " + kind); |
| } |
| } |
| } // end ModifierFilter |
| } |
