jdk8-mips64-public/langtools: src/share/classes/com/sun/tools/javadoc/JavadocTool.java@467f4f754368

     1 /*

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

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

     4  *

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

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

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    26 package com.sun.tools.javadoc;

    28 import java.io.File;

    29 import java.io.IOException;

    30 import java.util.Collection;

    31 import java.util.EnumSet;

    32 import java.util.HashMap;

    33 import java.util.Map;

    34 import java.util.Set;

    35 import javax.tools.JavaFileManager.Location;

    36 import javax.tools.JavaFileObject;

    37 import javax.tools.StandardJavaFileManager;

    38 import javax.tools.StandardLocation;

    40 import com.sun.tools.javac.code.Symbol.CompletionFailure;

    41 import com.sun.tools.javac.tree.JCTree;

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

    43 import com.sun.tools.javac.tree.JCTree.JCCompilationUnit;

    44 import com.sun.tools.javac.util.Abort;

    45 import com.sun.tools.javac.util.Context;

    46 import com.sun.tools.javac.util.List;

    47 import com.sun.tools.javac.util.ListBuffer;

    48 import com.sun.tools.javac.util.Position;

    51 /**

    52  *  This class could be the main entry point for Javadoc when Javadoc is used as a

    53  *  component in a larger software system. It provides operations to

    54  *  construct a new javadoc processor, and to run it on a set of source

    55  *  files.

    56  *

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

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

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

    60  *  deletion without notice.</b>

    61  *

    62  *  @author Neal Gafter

    63  */

    64 public class JavadocTool extends com.sun.tools.javac.main.JavaCompiler {

    65     DocEnv docenv;

    67     final Messager messager;

    68     final JavadocClassReader javadocReader;

    69     final JavadocEnter javadocEnter;

    71     /**

    72      * Construct a new JavaCompiler processor, using appropriately

    73      * extended phases of the underlying compiler.

    74      */

    75     protected JavadocTool(Context context) {

    76         super(context);

    77         messager = Messager.instance0(context);

    78         javadocReader = JavadocClassReader.instance0(context);

    79         javadocEnter = JavadocEnter.instance0(context);

    80     }

    82     /**

    83      * For javadoc, the parser needs to keep comments. Overrides method from JavaCompiler.

    84      */

    85     protected boolean keepComments() {

    86         return true;

    87     }

    89     /**

    90      *  Construct a new javadoc tool.

    91      */

    92     public static JavadocTool make0(Context context) {

    93         Messager messager = null;

    94         try {

    95             // force the use of Javadoc's class reader

    96             JavadocClassReader.preRegister(context);

    98             // force the use of Javadoc's own enter phase

    99             JavadocEnter.preRegister(context);

   101             // force the use of Javadoc's own member enter phase

   102             JavadocMemberEnter.preRegister(context);

   104             // force the use of Javadoc's own todo phase

   105             JavadocTodo.preRegister(context);

   107             // force the use of Messager as a Log

   108             messager = Messager.instance0(context);

   110             return new JavadocTool(context);

   111         } catch (CompletionFailure ex) {

   112             messager.error(Position.NOPOS, ex.getMessage());

   113             return null;

   114         }

   115     }

   117     public RootDocImpl getRootDocImpl(String doclocale,

   118                                       String encoding,

   119                                       ModifierFilter filter,

   120                                       List<String> javaNames,

   121                                       List<String[]> options,

   122                                       boolean breakiterator,

   123                                       List<String> subPackages,

   124                                       List<String> excludedPackages,

   125                                       boolean docClasses,

   126                                       boolean legacyDoclet,

   127                       boolean quiet) throws IOException {

   128         docenv = DocEnv.instance(context);

   129         docenv.showAccess = filter;

   130         docenv.quiet = quiet;

   131         docenv.breakiterator = breakiterator;

   132         docenv.setLocale(doclocale);

   133         docenv.setEncoding(encoding);

   134         docenv.docClasses = docClasses;

   135         docenv.legacyDoclet = legacyDoclet;

   136         javadocReader.sourceCompleter = docClasses ? null : this;

   138         ListBuffer<String> names = new ListBuffer<String>();

   139         ListBuffer<JCCompilationUnit> classTrees = new ListBuffer<JCCompilationUnit>();

   140         ListBuffer<JCCompilationUnit> packTrees = new ListBuffer<JCCompilationUnit>();

   142         try {

   143             StandardJavaFileManager fm = (StandardJavaFileManager) docenv.fileManager;

   144             for (List<String> it = javaNames; it.nonEmpty(); it = it.tail) {

   145                 String name = it.head;

   146                 if (!docClasses && name.endsWith(".java") && new File(name).exists()) {

   147                     JavaFileObject fo = fm.getJavaFileObjects(name).iterator().next();

   148                     docenv.notice("main.Loading_source_file", name);

   149                     JCCompilationUnit tree = parse(fo);

   150                     classTrees.append(tree);

   151                 } else if (isValidPackageName(name)) {

   152                     names = names.append(name);

   153                 } else if (name.endsWith(".java")) {

   154                         docenv.error(null, "main.file_not_found", name);

   155                 } else {

   156                     docenv.error(null, "main.illegal_package_name", name);

   157                 }

   158             }

   160             if (!docClasses) {

   161                 // Recursively search given subpackages.  If any packages

   162                 //are found, add them to the list.

   163                 Map<String,List<JavaFileObject>> packageFiles =

   164                         searchSubPackages(subPackages, names, excludedPackages);

   166                 // Parse the packages

   167                 for (List<String> packs = names.toList(); packs.nonEmpty(); packs = packs.tail) {

   168                     // Parse sources ostensibly belonging to package.

   169                     String packageName = packs.head;

   170                     parsePackageClasses(packageName, packageFiles.get(packageName), packTrees, excludedPackages);

   171                 }

   173                 if (messager.nerrors() != 0) return null;

   175                 // Enter symbols for all files

   176                 docenv.notice("main.Building_tree");

   177                 javadocEnter.main(classTrees.toList().appendList(packTrees.toList()));

   178             }

   179         } catch (Abort ex) {}

   181         if (messager.nerrors() != 0)

   182             return null;

   184         if (docClasses)

   185             return new RootDocImpl(docenv, javaNames, options);

   186         else

   187             return new RootDocImpl(docenv, listClasses(classTrees.toList()), names.toList(), options);

   188     }

   190     /** Is the given string a valid package name? */

   191     boolean isValidPackageName(String s) {

   192         int index;

   193         while ((index = s.indexOf('.')) != -1) {

   194             if (!isValidClassName(s.substring(0, index))) return false;

   195             s = s.substring(index+1);

   196         }

   197         return isValidClassName(s);

   198     }

   200     /**

   201      * search all directories in path for subdirectory name. Add all

   202      * .java files found in such a directory to args.

   203      */

   204     private void parsePackageClasses(String name,

   205             Iterable<JavaFileObject> files,

   206             ListBuffer<JCCompilationUnit> trees,

   207             List<String> excludedPackages)

   208             throws IOException {

   209         if (excludedPackages.contains(name)) {

   210             return;

   211         }

   213         boolean hasFiles = false;

   214         docenv.notice("main.Loading_source_files_for_package", name);

   216         if (files == null) {

   217             Location location = docenv.fileManager.hasLocation(StandardLocation.SOURCE_PATH)

   218                     ? StandardLocation.SOURCE_PATH : StandardLocation.CLASS_PATH;

   219             ListBuffer<JavaFileObject> lb = new ListBuffer<JavaFileObject>();

   220             for (JavaFileObject fo: docenv.fileManager.list(

   221                     location, name, EnumSet.of(JavaFileObject.Kind.SOURCE), false)) {

   222                 String binaryName = docenv.fileManager.inferBinaryName(location, fo);

   223                 String simpleName = getSimpleName(binaryName);

   224                 if (isValidClassName(simpleName)) {

   225                     lb.append(fo);

   226                 }

   227             }

   228             files = lb.toList();

   229         }

   231         for (JavaFileObject fo : files) {

   232             // messager.notice("main.Loading_source_file", fn);

   233             trees.append(parse(fo));

   234             hasFiles = true;

   235         }

   237         if (!hasFiles) {

   238             messager.warning(Messager.NOPOS, "main.no_source_files_for_package",

   239                     name.replace(File.separatorChar, '.'));

   240         }

   241     }

   243     /**

   244      * Recursively search all directories in path for subdirectory name.

   245      * Add all packages found in such a directory to packages list.

   246      */

   247     private Map<String,List<JavaFileObject>> searchSubPackages(

   248             List<String> subPackages,

   249             ListBuffer<String> packages,

   250             List<String> excludedPackages)

   251             throws IOException {

   252         Map<String,List<JavaFileObject>> packageFiles =

   253                 new HashMap<String,List<JavaFileObject>>();

   255         Map<String,Boolean> includedPackages = new HashMap<String,Boolean>();

   256         includedPackages.put("", true);

   257         for (String p: excludedPackages)

   258             includedPackages.put(p, false);

   260         StandardLocation path = docenv.fileManager.hasLocation(StandardLocation.SOURCE_PATH)

   261                 ? StandardLocation.SOURCE_PATH : StandardLocation.CLASS_PATH;

   263         searchSubPackages(subPackages,

   264                 includedPackages,

   265                 packages, packageFiles,

   266                 path,

   267                 EnumSet.of(JavaFileObject.Kind.SOURCE));

   269         return packageFiles;

   270     }

   272     private void searchSubPackages(List<String> subPackages,

   273             Map<String,Boolean> includedPackages,

   274             ListBuffer<String> packages,

   275             Map<String, List<JavaFileObject>> packageFiles,

   276             StandardLocation location, Set<JavaFileObject.Kind> kinds)

   277             throws IOException {

   278         for (String subPackage: subPackages) {

   279             if (!isIncluded(subPackage, includedPackages))

   280                 continue;

   282             for (JavaFileObject fo: docenv.fileManager.list(location, subPackage, kinds, true)) {

   283                 String binaryName = docenv.fileManager.inferBinaryName(location, fo);

   284                 String packageName = getPackageName(binaryName);

   285                 String simpleName = getSimpleName(binaryName);

   286                 if (isIncluded(packageName, includedPackages) && isValidClassName(simpleName)) {

   287                     List<JavaFileObject> list = packageFiles.get(packageName);

   288                     list = (list == null ? List.of(fo) : list.prepend(fo));

   289                     packageFiles.put(packageName, list);

   290                     if (!packages.contains(packageName))

   291                         packages.add(packageName);

   292                 }

   293             }

   294         }

   295     }

   297     private String getPackageName(String name) {

   298         int lastDot = name.lastIndexOf(".");

   299         return (lastDot == -1 ? "" : name.substring(0, lastDot));

   300     }

   302     private String getSimpleName(String name) {

   303         int lastDot = name.lastIndexOf(".");

   304         return (lastDot == -1 ? name : name.substring(lastDot + 1));

   305     }

   307     private boolean isIncluded(String packageName, Map<String,Boolean> includedPackages) {

   308         Boolean b = includedPackages.get(packageName);

   309         if (b == null) {

   310             b = isIncluded(getPackageName(packageName), includedPackages);

   311             includedPackages.put(packageName, b);

   312         }

   313         return b;

   314     }

   316     /**

   317      * Recursively search all directories in path for subdirectory name.

   318      * Add all packages found in such a directory to packages list.

   319      */

   320     private void searchSubPackage(String packageName,

   321                                   ListBuffer<String> packages,

   322                                   List<String> excludedPackages,

   323                                   Collection<File> pathnames) {

   324         if (excludedPackages.contains(packageName))

   325             return;

   327         String packageFilename = packageName.replace('.', File.separatorChar);

   328         boolean addedPackage = false;

   329         for (File pathname : pathnames) {

   330             File f = new File(pathname, packageFilename);

   331             String filenames[] = f.list();

   332             // if filenames not null, then found directory

   333             if (filenames != null) {

   334                 for (String filename : filenames) {

   335                     if (!addedPackage

   336                             && (isValidJavaSourceFile(filename) ||

   337                                 isValidJavaClassFile(filename))

   338                             && !packages.contains(packageName)) {

   339                         packages.append(packageName);

   340                         addedPackage = true;

   341                     } else if (isValidClassName(filename) &&

   342                                (new File(f, filename)).isDirectory()) {

   343                         searchSubPackage(packageName + "." + filename,

   344                                          packages, excludedPackages, pathnames);

   345                     }

   346                 }

   347             }

   348         }

   349     }

   351     /**

   352      * Return true if given file name is a valid class file name.

   353      * @param file the name of the file to check.

   354      * @return true if given file name is a valid class file name

   355      * and false otherwise.

   356      */

   357     private static boolean isValidJavaClassFile(String file) {

   358         if (!file.endsWith(".class")) return false;

   359         String clazzName = file.substring(0, file.length() - ".class".length());

   360         return isValidClassName(clazzName);

   361     }

   363     /**

   364      * Return true if given file name is a valid Java source file name.

   365      * @param file the name of the file to check.

   366      * @return true if given file name is a valid Java source file name

   367      * and false otherwise.

   368      */

   369     private static boolean isValidJavaSourceFile(String file) {

   370         if (!file.endsWith(".java")) return false;

   371         String clazzName = file.substring(0, file.length() - ".java".length());

   372         return isValidClassName(clazzName);

   373     }

   375     /** Are surrogates supported?

   376      */

   377     final static boolean surrogatesSupported = surrogatesSupported();

   378     private static boolean surrogatesSupported() {

   379         try {

   380             boolean b = Character.isHighSurrogate('a');

   381             return true;

   382         } catch (NoSuchMethodError ex) {

   383             return false;

   384         }

   385     }

   387     /**

   388      * Return true if given file name is a valid class name

   389      * (including "package-info").

   390      * @param s the name of the class to check.

   391      * @return true if given class name is a valid class name

   392      * and false otherwise.

   393      */

   394     public static boolean isValidClassName(String s) {

   395         if (s.length() < 1) return false;

   396         if (s.equals("package-info")) return true;

   397         if (surrogatesSupported) {

   398             int cp = s.codePointAt(0);

   399             if (!Character.isJavaIdentifierStart(cp))

   400                 return false;

   401             for (int j=Character.charCount(cp); j<s.length(); j+=Character.charCount(cp)) {

   402                 cp = s.codePointAt(j);

   403                 if (!Character.isJavaIdentifierPart(cp))

   404                     return false;

   405             }

   406         } else {

   407             if (!Character.isJavaIdentifierStart(s.charAt(0)))

   408                 return false;

   409             for (int j=1; j<s.length(); j++)

   410                 if (!Character.isJavaIdentifierPart(s.charAt(j)))

   411                     return false;

   412         }

   413         return true;

   414     }

   416     /**

   417      * From a list of top level trees, return the list of contained class definitions

   418      */

   419     List<JCClassDecl> listClasses(List<JCCompilationUnit> trees) {

   420         ListBuffer<JCClassDecl> result = new ListBuffer<JCClassDecl>();

   421         for (JCCompilationUnit t : trees) {

   422             for (JCTree def : t.defs) {

   423                 if (def.hasTag(JCTree.Tag.CLASSDEF))

   424                     result.append((JCClassDecl)def);

   425             }

   426         }

   427         return result.toList();

   428     }

   430 }

Mercurial > jdk8-mips64-public > langtools / file revision

src/share/classes/com/sun/tools/javadoc/JavadocTool.java@467f4f754368

src/share/classes/com/sun/tools/javadoc/JavadocTool.java