001: /*
002: * Copyright 2001-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.tools.javadoc;
027:
028: import java.io.*;
029:
030: import java.util.Collection;
031:
032: import com.sun.tools.javac.code.*;
033: import com.sun.tools.javac.code.Symbol.*;
034: import com.sun.tools.javac.comp.*;
035: import com.sun.tools.javac.jvm.ClassReader;
036: import com.sun.tools.javac.jvm.ClassWriter;
037: import com.sun.tools.javac.parser.DocCommentScanner;
038: import com.sun.tools.javac.util.Paths;
039: import com.sun.tools.javac.tree.*;
040: import com.sun.tools.javac.tree.JCTree.*;
041: import com.sun.tools.javac.util.*;
042:
043: import com.sun.javadoc.LanguageVersion;
044: import static com.sun.javadoc.LanguageVersion.*;
045:
046: /**
047: * This class could be the main entry point for Javadoc when Javadoc is used as a
048: * component in a larger software system. It provides operations to
049: * construct a new javadoc processor, and to run it on a set of source
050: * files.
051: * @author Neal Gafter
052: */
053: public class JavadocTool extends com.sun.tools.javac.main.JavaCompiler {
054: DocEnv docenv;
055:
056: final Context context;
057: final Messager messager;
058: final JavadocClassReader reader;
059: final JavadocEnter enter;
060: final Annotate annotate;
061: private final Paths paths;
062:
063: /**
064: * Construct a new JavaCompiler processor, using appropriately
065: * extended phases of the underlying compiler.
066: */
067: protected JavadocTool(Context context) {
068: super (context);
069: this .context = context;
070: messager = Messager.instance0(context);
071: reader = JavadocClassReader.instance0(context);
072: enter = JavadocEnter.instance0(context);
073: annotate = Annotate.instance(context);
074: paths = Paths.instance(context);
075: }
076:
077: /**
078: * For javadoc, the parser needs to keep comments. Overrides method from JavaCompiler.
079: */
080: protected boolean keepComments() {
081: return true;
082: }
083:
084: /**
085: * Construct a new javadoc tool.
086: */
087: public static JavadocTool make0(Context context) {
088: Messager messager = null;
089: try {
090: // force the use of Javadoc's class reader
091: JavadocClassReader.preRegister(context);
092:
093: // force the use of Javadoc's own enter phase
094: JavadocEnter.preRegister(context);
095:
096: // force the use of Javadoc's own member enter phase
097: JavadocMemberEnter.preRegister(context);
098:
099: // force the use of Javadoc's own todo phase
100: JavadocTodo.preRegister(context);
101:
102: // force the use of Messager as a Log
103: messager = Messager.instance0(context);
104:
105: // force the use of the scanner that captures Javadoc comments
106: DocCommentScanner.Factory.preRegister(context);
107:
108: return new JavadocTool(context);
109: } catch (CompletionFailure ex) {
110: messager.error(Position.NOPOS, ex.getMessage());
111: return null;
112: }
113: }
114:
115: public RootDocImpl getRootDocImpl(String doclocale,
116: String encoding, ModifierFilter filter,
117: List<String> javaNames, List<String[]> options,
118: boolean breakiterator, List<String> subPackages,
119: List<String> excludedPackages, boolean docClasses,
120: boolean legacyDoclet, boolean quiet) throws IOException {
121: docenv = DocEnv.instance(context);
122: docenv.showAccess = filter;
123: docenv.quiet = quiet;
124: docenv.breakiterator = breakiterator;
125: docenv.setLocale(doclocale);
126: docenv.setEncoding(encoding);
127: docenv.docClasses = docClasses;
128: docenv.legacyDoclet = legacyDoclet;
129: reader.sourceCompleter = docClasses ? null : this ;
130:
131: ListBuffer<String> names = new ListBuffer<String>();
132: ListBuffer<JCCompilationUnit> classTrees = new ListBuffer<JCCompilationUnit>();
133: ListBuffer<JCCompilationUnit> packTrees = new ListBuffer<JCCompilationUnit>();
134:
135: try {
136: for (List<String> it = javaNames; it.nonEmpty(); it = it.tail) {
137: String name = it.head;
138: if (!docClasses && name.endsWith(".java")
139: && new File(name).exists()) {
140: docenv.notice("main.Loading_source_file", name);
141: JCCompilationUnit tree = parse(name);
142: classTrees.append(tree);
143: } else if (isValidPackageName(name)) {
144: names = names.append(name);
145: } else if (name.endsWith(".java")) {
146: docenv.error(null, "main.file_not_found", name);
147: ;
148: } else {
149: docenv.error(null, "main.illegal_package_name",
150: name);
151: }
152: }
153:
154: if (!docClasses) {
155: // Recursively search given subpackages. If any packages
156: //are found, add them to the list.
157: searchSubPackages(subPackages, names, excludedPackages);
158:
159: // Parse the packages
160: for (List<String> packs = names.toList(); packs
161: .nonEmpty(); packs = packs.tail) {
162: // Parse sources ostensibly belonging to package.
163: parsePackageClasses(packs.head, packTrees,
164: excludedPackages);
165: }
166:
167: if (messager.nerrors() != 0)
168: return null;
169:
170: // Enter symbols for all files
171: docenv.notice("main.Building_tree");
172: enter.main(classTrees.toList().appendList(
173: packTrees.toList()));
174: }
175: } catch (Abort ex) {
176: }
177:
178: if (messager.nerrors() != 0)
179: return null;
180:
181: if (docClasses)
182: return new RootDocImpl(docenv, javaNames, options);
183: else
184: return new RootDocImpl(docenv, listClasses(classTrees
185: .toList()), names.toList(), options);
186: }
187:
188: /** Is the given string a valid package name? */
189: boolean isValidPackageName(String s) {
190: int index;
191: while ((index = s.indexOf('.')) != -1) {
192: if (!isValidClassName(s.substring(0, index)))
193: return false;
194: s = s.substring(index + 1);
195: }
196: return isValidClassName(s);
197: }
198:
199: private final static char pathSep = File.pathSeparatorChar;
200:
201: /**
202: * search all directories in path for subdirectory name. Add all
203: * .java files found in such a directory to args.
204: */
205: private void parsePackageClasses(String name,
206: ListBuffer<JCCompilationUnit> trees,
207: List<String> excludedPackages) throws IOException {
208: if (excludedPackages.contains(name)) {
209: return;
210: }
211: boolean hasFiles = false;
212: docenv.notice("main.Loading_source_files_for_package", name);
213: name = name.replace('.', File.separatorChar);
214: for (File pathname : paths.sourceSearchPath()) {
215: File f = new File(pathname, name);
216: String names[] = f.list();
217: // if names not null, then found directory with source files
218: if (names != null) {
219: String dir = f.getAbsolutePath();
220: if (!dir.endsWith(File.separator))
221: dir = dir + File.separator;
222: for (int j = 0; j < names.length; j++) {
223: if (isValidJavaSourceFile(names[j])) {
224: String fn = dir + names[j];
225: // messager.notice("main.Loading_source_file", fn);
226: trees.append(parse(fn));
227: hasFiles = true;
228: }
229: }
230: }
231: }
232: if (!hasFiles)
233: messager.warning(null, "main.no_source_files_for_package",
234: name.replace(File.separatorChar, '.'));
235: }
236:
237: /**
238: * Recursively search all directories in path for subdirectory name.
239: * Add all packages found in such a directory to packages list.
240: */
241: private void searchSubPackages(List<String> subPackages,
242: ListBuffer<String> packages, List<String> excludedPackages) {
243: // FIXME: This search path is bogus.
244: // Only the effective source path should be searched for sources.
245: // Only the effective class path should be searched for classes.
246: // Should the bootclasspath/extdirs also be searched for classes?
247: java.util.List<File> pathnames = new java.util.ArrayList<File>();
248: if (paths.sourcePath() != null)
249: for (File elt : paths.sourcePath())
250: pathnames.add(elt);
251: for (File elt : paths.userClassPath())
252: pathnames.add(elt);
253:
254: for (String subPackage : subPackages)
255: searchSubPackage(subPackage, packages, excludedPackages,
256: pathnames);
257: }
258:
259: /**
260: * Recursively search all directories in path for subdirectory name.
261: * Add all packages found in such a directory to packages list.
262: */
263: private void searchSubPackage(String packageName,
264: ListBuffer<String> packages, List<String> excludedPackages,
265: Collection<File> pathnames) {
266: if (excludedPackages.contains(packageName))
267: return;
268:
269: String packageFilename = packageName.replace('.',
270: File.separatorChar);
271: boolean addedPackage = false;
272: for (File pathname : pathnames) {
273: File f = new File(pathname, packageFilename);
274: String filenames[] = f.list();
275: // if filenames not null, then found directory
276: if (filenames != null) {
277: for (String filename : filenames) {
278: if (!addedPackage
279: && (isValidJavaSourceFile(filename) || isValidJavaClassFile(filename))
280: && !packages.contains(packageName)) {
281: packages.append(packageName);
282: addedPackage = true;
283: } else if (isValidClassName(filename)
284: && (new File(f, filename)).isDirectory()) {
285: searchSubPackage(packageName + "." + filename,
286: packages, excludedPackages, pathnames);
287: }
288: }
289: }
290: }
291: }
292:
293: /**
294: * Return true if given file name is a valid class file name.
295: * @param file the name of the file to check.
296: * @return true if given file name is a valid class file name
297: * and false otherwise.
298: */
299: private static boolean isValidJavaClassFile(String file) {
300: if (!file.endsWith(".class"))
301: return false;
302: String clazzName = file.substring(0, file.length()
303: - ".class".length());
304: return isValidClassName(clazzName);
305: }
306:
307: /**
308: * Return true if given file name is a valid Java source file name.
309: * @param file the name of the file to check.
310: * @return true if given file name is a valid Java source file name
311: * and false otherwise.
312: */
313: private static boolean isValidJavaSourceFile(String file) {
314: if (!file.endsWith(".java"))
315: return false;
316: String clazzName = file.substring(0, file.length()
317: - ".java".length());
318: return isValidClassName(clazzName);
319: }
320:
321: /** Are surrogates supported?
322: */
323: final static boolean surrogatesSupported = surrogatesSupported();
324:
325: private static boolean surrogatesSupported() {
326: try {
327: boolean b = Character.isHighSurrogate('a');
328: return true;
329: } catch (NoSuchMethodError ex) {
330: return false;
331: }
332: }
333:
334: /**
335: * Return true if given file name is a valid class name
336: * (including "package-info").
337: * @param clazzname the name of the class to check.
338: * @return true if given class name is a valid class name
339: * and false otherwise.
340: */
341: public static boolean isValidClassName(String s) {
342: if (s.length() < 1)
343: return false;
344: if (s.equals("package-info"))
345: return true;
346: if (surrogatesSupported) {
347: int cp = s.codePointAt(0);
348: if (!Character.isJavaIdentifierStart(cp))
349: return false;
350: for (int j = Character.charCount(cp); j < s.length(); j += Character
351: .charCount(cp)) {
352: cp = s.codePointAt(j);
353: if (!Character.isJavaIdentifierPart(cp))
354: return false;
355: }
356: } else {
357: if (!Character.isJavaIdentifierStart(s.charAt(0)))
358: return false;
359: for (int j = 1; j < s.length(); j++)
360: if (!Character.isJavaIdentifierPart(s.charAt(j)))
361: return false;
362: }
363: return true;
364: }
365:
366: /**
367: * From a list of top level trees, return the list of contained class definitions
368: */
369: List<JCClassDecl> listClasses(List<JCCompilationUnit> trees) {
370: ListBuffer<JCClassDecl> result = new ListBuffer<JCClassDecl>();
371: for (JCCompilationUnit t : trees) {
372: for (JCTree def : t.defs) {
373: if (def.getTag() == JCTree.CLASSDEF)
374: result.append((JCClassDecl) def);
375: }
376: }
377: return result.toList();
378: }
379:
380: }
|